Groma Help

Groma is a precision-guided manual test runner. One person authors a flow by walking through an app; anyone the resulting link reaches runs it. A flow is a short list of checkpoints — the things worth judging — each led up to by spotlights that light the path and advance on their own as you go. Groma never decides pass or fail — you are the arbiter of every checkpoint. Each run is filed as a report you can open, share by link or save as a PDF.

Authoring a flow

Clicking the Groma icon opens Home — your test case library, your Projects, your run history, and + Author a flow at the top of it. The very first time you click it after installing, Home also introduces itself.

  1. Open the app you want to test in a normal tab, if it isn't already.
  2. Click the Groma toolbar button to open Home, click + Author a flow at the top and pick that page — your open tabs are listed there, or you can type an address. You don't need a Project connected to start.
  3. Groma opens the app in a tab of its own and docks its author panel beside it (a floating panel on Safari). Walk the flow as a tester would — nothing is captured until you ask for it.
  4. To leave the tester a spotlight, open the step it belongs to and press its own + Add spotlight to this step button (or Alt+S, which arms from wherever your hands already are), then click — or drag across — the button, link, field or section it should point at. That pick is captured as a spotlight and doesn't reach the app. Groma confirms each spotlight on the page, and tells you when an element can't be targeted reliably so you can pick a better one.
  5. At each point worth judging, add a checkpoint and give it an Instruction (what the tester should do) and an Expected result (what they verify). The spotlights you picked before it become that checkpoint's, shown one at a time as the tester works through them — so testers get a few clear goals to judge, not a click-by-click script.
  6. If a checkpoint is one that must pass before any release, press Mark critical on its row. It then also appears in the project's smoke test. Press it again to take the checkpoint out.

The author panel's header holds everything that isn't about one particular step. A house leads it, beside the title, and three icons sit in the far corner:

Between the title and those icons sits a small screen-size chip reading the width of the app beside you (see screen sizes). It is a readout, not a control.

The test case you are looking at is removed from its own card — the trash beside Test case title, the same mark a step row wears one size up — which asks you to confirm, since the steps you captured go with it. (Reopening a saved test suite to revise it is the one case where the header's exit throws work away: its one row is Cancel editing, which leaves the editor and drops every change you made — it doesn't ask twice — and the test suite on disk stays exactly as it was.)

Dictate instead of typing. The microphone icon in the author panel's header sends speech into whichever field your cursor is in — an instruction, an expected result, a note — using your browser's own speech recognition. It's off until you click it; the first click opens a small window of its own to ask for microphone access, which happens once. Groma capitalizes the start of each sentence for you (speech engines return everything lowercase) but changes nothing else, so iOS, shop.test/cart and the like stay as spoken. Not shown in a browser with no speech-recognition engine (Firefox, as of this writing).

Issues — what you saw while authoring

Authoring is itself a test pass: you walk the app, and on the way you see things that are wrong. An issue is where those go. They are for the developers, not for the tester — an issue is never part of a test case, never rides a shared link, and never reaches whoever runs the flow.

Reusing a test case you've already captured

Test cases that are variations on each other — the same checkout as a guest and then signed in, the same form with good data and then bad — don't need walking twice. Every test case saved this session carries a ⧉ beside Edit, the same mark a step row wears: it drops a copy of that test case into the test suite, named … (copy) and ready to edit. The editor has the same control, ⧉ Duplicate, beside + Add a test case; there it opens the copy for you straight away.

A copy is a copy — its own test case from the moment it exists. Editing it changes nothing in the test case it came from, and there is nothing to re-sync, which is what keeps the test case you share self-contained. Steps, spotlights and screen sizes all come across; rename it, delete the steps you don't want, and walk only the part that differs.

Linking a step you've already written

Some steps turn up in every flow — signing in, dismissing a cookie banner, getting to the right account. Beside + Add step there is Link step, which lists the test cases you've saved in this session plus, when you have one connected, every test case in the active project. Pick a test case, tick the steps you want (or Link the whole test case), and they are copied in. The search box filters both test case names and the text of their steps, so you can find the sign-in step without remembering which flow you wrote it in.

A linked step is a copy, not a reference. From the moment it exists it moves, edits, duplicates and deletes like any other step, and nothing re-reads its source when you export — so a test case you share stays self-contained, exactly as a duplicated test case does. Taking a step out of the middle of another flow is safe too: a step usually inherits the page the steps before it navigated to, so Groma makes that address explicit as it copies, rather than leaving the step to run against whatever page the receiving test case happened to be on.

This needs no project: test cases saved in the session you are in are a source on their own.

The order of the test cases is the order of the run

Every test case saved this session carries ↑ ↓ beside Edit, exactly like a step row. That order is what a test suite's Run all walks, so a test case that sets up the state a later one needs — sign in, then check out — can be moved in front of it without being walked again. In the editor, where the test cases are chips laid out across the panel rather than a column, the same move is a single ← → pair acting on the test case you are looking at. Reordering only reorders: nothing is re-captured and no locator moves.

Writing a step for a screen size

A step can be written for a particular screen width — a mobile drawer at step 2, a desktop table at step 5, in one test case rather than two test suites kept in step with each other. The width is your real browser window, and the tester's real browser window is what gets put to it.

  1. Resize your browser until the layout you want is on screen. Drag the window's edge, or the side panel's own splitter — the chip in the panel's header names the width the app is at as you drag (Mobile · 390px), so you can stop where the layout changes rather than guessing a number.
  2. Press Set size on the step's row. It stamps whatever width the app is at right then: the point is the layout you can see, not a phone model.
  3. The stamped chip stays on that row. If you later resize away from it, the chip marks itself stale and says so on hover — anything you pick while the window is a different width is frozen against the layout in front of you, not the one the step is written for. Click the chip to re-stamp it at the current width, or the × beside it to stop writing that step for a size at all.

A step nobody stamped runs at whatever size the tester's window already has, which is why this is a per-step control and there is nothing to set for a test suite as a whole. Reaching a stamped step resizes the tester's window before the step's page loads, so the app lays out at the width it was written for. It is best-effort: browsers enforce a minimum window width, and if the width can't be reached Groma says so in the panel rather than letting a step fail for a reason that isn't the app's fault. On Safari, where the panel floats inside the page itself, nothing is resized and the tester is told the size the step wants.

Keeping your test cases as files, in Projects

Groma starts you with one project, This browser, kept in the browser's own storage for the extension: nothing to set up, but not a folder you can open, and removing Groma deletes it. To keep your test cases as files, connect a Groma Project on the Home page — the project band below Author a flow — and that folder becomes where your test cases live. Finishing a session then writes one .groma.json file per test case straight into it and downloads nothing: the panel tells you what landed and where, and turning those test cases into something a tester can run happens on Home, whenever you want, from whichever test cases you tick. The built-in project works the same way. Only where there is no project at all — a private window, or Safari's floating panel — does finishing download a Groma archive instead: a zip of the same files, to import into a project later.

A project is just a folder. Put it in a git repo and your test cases get diffs, review, blame and branches, and sit beside the code they describe. Put it in a Google Drive, Dropbox or OneDrive folder and they sync to whoever you share it with — Sharing a project with your team, below, walks through it. Put it nowhere in particular and it's a folder. Groma has no account, no sign-in and no server, and doesn't know or care which of those you chose — that's the whole point.

You can connect more than one project — a client's app and an internal tool, say, or separate staging and production test case sets. Home shows one at a time: the project in force names the band at the top of the page, and everything below it — the search and every test case listed — is that project's. Click its name to switch to another, and each project keeps its own colour on that band so two of them are never mistaken for one another. The active project is also where a freshly authored test case is saved: the author panel carries its own Project field, right under the document title, so you always know which project a session's test cases are headed for and can switch it before you export.

Within a project, organise test cases however you like with ordinary subfolders — Groma looks a few levels down, so checkout/ and admin/mobile/ both work. Renaming a subfolder renames the group Home shows it under.

Saving again updates the files already written rather than piling up copies, and it follows a test case you renamed. Nothing is ever deleted from a project by an export: a test case you drop from a test suite stays there. Groma writes only its own files (.groma.json test cases, and the .groma-reports, .groma-issues and .groma-test-suites subfolders described below) and never reads, changes or removes anything else in the folder. Disconnect and + Add project live in the menu behind the project's name on Home; disconnecting only makes Groma forget the project and leaves every file exactly where it is. (Delete… in a test case row's ⋯ does delete that one file, and asks first.)

Not sure where a project actually lives? Pick Locate folder… from that same menu — or Locate folder… in any group heading's ⋯ — and your system's own folder dialog opens at that location so you can read the path and cancel it. Nothing is picked, changed or re-granted by doing it, and it is not a file browser: to open or tidy the files, go to that location in your own file manager. (A FileSystemDirectoryHandle never exposes a path to an extension, so this dialog is the only honest answer available — there is no “Show in Finder” to give you.)

After a browser restart your browser may ask you to confirm access to a project again. That is the browser's rule rather than Groma's: permission to a folder is re-granted by a click, so Home shows a Reconnect button rather than quietly asking on load. Exporting asks for it too, at the moment it is about to write.

Connecting a folder needs a browser that offers extensions a folder picker — Chrome and Edge, as of this writing.

Any project can be synced with your Google Drive. Pick Sync with Google Drive from the project menu on Home (Chrome, Edge and Firefox) and sign in on Google's page. Groma keeps one folder named Groma at the top of your Drive and, inside it, a folder with your project's own name holding the same files — test cases, runs with their videos, issues and test suite records. Your project stays where it is; Drive holds a copy. Groma can open only what it put there, never the rest of your Drive. The project menu says which folder and which Google account the project syncs with, and Open in Google Drive shows you that folder once it exists. Two projects with the same name sync with the same folder and their files mix there; the menu warns you when two of yours do, and renaming one of the folders keeps them apart.

Test cases and test suite briefs always sync. Under Sync with Google Drive, untick Sync run reports, Sync run videos or Sync issues to keep those on this computer only — videos are the largest files a project holds, and a failed run's screenshots and console and network logs can hold what you would rather not copy. What Drive already holds of them stays there, untouched, and ticking them again syncs them from the next sync. The choice is per project and per computer.

When you have saved, run or deleted something since the last sync, a sync icon beside the project's name on Home carries how many changes are not synced yet. Click it to sync; the number then counts down the files still to go. A sync runs both ways: each side gets what it lacks, and where both hold a file that differs, the one written more recently replaces the other. That is also how work reaches a second computer: there, sign in to the same Google account, give the project the same name and sync — the test cases and runs made elsewhere come down, and Groma says how many files it sent and received; Which files under that line lists them by name. Hover the sync icon to see which changes are waiting, or narrow the library to Not synced to find the test cases they belong to. Home cannot see what is waiting in Drive until you sync. A test case, run or other record you delete on Home goes to Drive's bin on the next sync rather than coming back — unless the copy in Drive was changed after you deleted it, when the newer copy comes down instead. Where a file you still hold was deleted from the backup, on another computer or in Drive itself, the sync says so and asks: Delete here too, or Keep and back up again, which puts it back in Drive for every computer that syncs. Nothing is deleted on your computer without that click. A file removed in your file manager rather than on Home still comes back from Drive. Sync happens when you press it, never on its own.

Groma remembers which Google account you signed in with, so Google does not ask you to choose it each time. To use another, pick Switch Google account… from the project menu and choose it on Google's page; syncing and sharing then use that account's Drive. What the first account's Drive holds stays there, and links you already sent keep working. Find duplicate shares…, in the same menu, looks through the project's shared links in Drive for the same test cases or report shared more than once, says how many it found, and moves the extra copies to Drive's bin only when you say so. One link to each stays; a link you sent to a removed copy stops working until you restore that folder from Drive's bin.

Sharing a project with your team

A team shares a project by keeping its folder on a drive that syncs to everyone's computer, and each person connecting that same folder on their own Home. Groma itself never signs in to the drive or talks to it: the drive's own desktop app does the syncing, and Groma reads and writes the folder as it would any other. The steps below are for Google Drive; OneDrive, Dropbox and a network share work the same way — a folder every teammate can open on their own machine.

  1. Everyone installs Google Drive for desktop and signs in. It adds a Google Drive location to Finder or File Explorer, which is what lets a folder in Drive be picked like any other folder.
  2. One person makes the shared place.
    • With a work or school account: at drive.google.com open Shared drives, choose New, name it, then Manage members and add your teammates as Content manager (or Manager). Contributor is not enough — on a computer it can only read, and Groma needs to save.
    • With a personal Google account, which has no shared drives: make a folder in My Drive, Share it with your teammates as Editor, and have each of them open Shared with me, right-click the folder and choose Organize → Add shortcut to put it in their own My Drive. Without that shortcut the folder never reaches their computer.
  3. Make a folder for the project inside it — Checkout tests, say. Pick this folder, not the drive itself: it keeps Groma's files apart from everything else kept there, and a browser may refuse to hand over the top of a drive.
  4. Everyone connects that folder on their own Home with + Add project, finding it under Google Drive in the folder dialog. If you already have a project on your machine, move its folder into the shared one first, then disconnect the old location and add the new one.

From then on a test case one person saves, and every run anyone files, reaches the others as soon as Drive has synced it and they next return to Home. Test runs, its summary and the filters then count the whole team's runs, each under the name its tester signed off with. A run's video syncs too, so a project with many recorded runs takes real space on the drive.

What a whole team can do at once: run test cases and file their reports, log issues, and author new test cases. Each of those adds a file of its own, so nothing anybody else filed is lost. An unfinished authoring session is the one thing that is not shared: a draft stays in the browser it was started in, so nobody's half-written work appears in anyone else's Unfinished work.

What one person should do at a time: edit a particular test case. A drive does not merge two people's changes to one file — whoever saves last wins, or the drive keeps both as two files. The same goes for anything that rewrites many test cases in one go: Reorder test cases… and find and replace. Say so in your team's chat before you start one. If two files do end up holding the same test case, Home says so at the top of the library and names both; find the project folder (Locate folder…), open it in your file manager, keep the one you want and delete the other.

Working somewhere without a connection? Set the project's folder to be available offline first (right-click it in the Google Drive folder). What you save then syncs when you are back online — which is exactly when two people's edits to one test case are most likely to meet, so check Home for that note afterwards.

If your team reviews changes before they land, a git repository does that better than a drive does: every edit to a test case becomes a diff somebody can read.

Home — your test case library

Home is one page, reached by three doors that lead to the same tab: the Groma toolbar icon, the house at the leading edge of any live panel's header, and the Home link in every Groma footer, this page's included. It opens in an ordinary tab — a library needs width, and 320 px of side panel is the wrong shape for one — and opening it never ends a session you are in the middle of. The one time the toolbar icon does something else is when the tab you are on is a Groma session: then it just re-opens that session's panel, so a click can never bury a run or a draft in progress.

When a parked run, a parked run-all, an unfinished draft or a run-all's uncollected reports are waiting, the toolbar icon wears a badge and Home leads with an Unfinished work section holding a card for each. Everything there is already saved, so nothing needs a decision right away: Resume it, Discard it (which asks first), or Not now to hide the card until the next time you open Home. The side panel only ever shows a session in progress, so Home is where saved work waits.

It lists every test case in the active project, read fresh off disk every time it paints. Nothing is cached between paints, so a file you moved, renamed or deleted in Finder is reflected the moment you come back to the tab.

Beside the project's name, Test cases and Test runs switch between its two views. Test cases is the library: writing, organising, running and sharing what the project holds. Test runs is every run filed into it, newest first, with how they went (see Past runs). Each is its own address, so the browser's Back button and a reload keep the one you were on.

Finding a test case

The project band carries a search box, always open, and a funnel icon at its end for filters.

The search box looks inside each test case, not only at its name: the description, the preconditions, and the instruction and expected result of every step. So “which test case covers coupons?” is answerable even when the test case is called Checkout and the coupon field is step 4 of it. Aa and ab, which appear beside the field once you type, make the match case-sensitive or whole-word.

A row that matched on something other than its name says where — the step it was found in, and a short excerpt with your words marked — so a result you did not expect can be checked without opening it. Only text you can then go and read is searched: locators, actions and navigation are left out, because a match you cannot see in the test case reads as the filter having gone wrong.

Changing a word in every test case at once

A feature gets renamed, a test account changes, a button stops being called “Basket”. Replace, which appears beside the search field once you have searched for something, opens a second box: what the text you searched for should become. It runs over every test case the search matched (or just the ticked ones, if you have ticked any), in the same text the search reads, and it says what it is about to do before it does it — Replace 14 occurrences of “Basket” with “Cart”, across 6 matching test cases — then asks you to press it a second time to confirm. Leave the second box empty and the text is deleted, which it says in those words rather than letting you infer it.

The count is recomputed as you type, and a confirm that no longer matches its count is retired rather than left standing over a button that rewrites files. One thing is called out before you commit: a test case whose new text would be too long for the field is named and left alone (writing it would produce a file Groma could no longer read back). This rewrites the files in your project and there is no undo.

Nothing here touches a locator: renaming what a button is called in your instructions does not re-point the test case at a different button, and it never can — which is why a rename in the app itself is a job for the locator check, not for this.

Narrowing to what still wants attention

The funnel opens with a few rows, and they are all the same question — what in this project have I not finished with? Each one counts what it would leave you, over whatever the search has already narrowed, so a row reading 3 hands back three test cases.

One of those at a time, deliberately. Questions about the runs themselves — when, who, skipped or noted steps, what is still unresolved, and what this week still owes you — are answered under Test runs.

Groups

Test cases are grouped by the test suite title the session that saved them was named after, and by their subfolder where there is no title. A title wins because it is the more deliberate fact: you name a session once and everything it banks reads as one test suite, even when the files sit in different subfolders. Everything else groups by where you filed it.

Groups start collapsed, so a library of several test suites opens as a scannable column of headings rather than a wall of rows — click a heading to open the one you mean. Typing in the search box opens every group that still has a match in it. Each heading carries its own tick (select the whole group), its own count, a + to start a new test case in it, and a ⋯ holding Show runs, Reorder test cases…, Add a brief… and Locate folder….

A brief is what a test suite says for itself, written once instead of repeated in every test case: About this round (what this round of testing covers) and Setup the tester needs (two accounts, a file to upload, a flag someone has to turn on). Every test case you share from that test suite carries it, and the tester reads it above the test case's own description and preconditions. Once written, the brief's first line shows under the heading, and clicking it opens the brief to edit. Empty both fields and save to remove it. Briefs belong to titled test suites only, not to plain folders.

The heading's second line says where this test suite's test cases run — the server they were captured on, or, accented, the one you have pointed them at. It is the same line whether the group is folded or open, because “where does this point?” is asked about a folded test suite at least as often as an open one, and the heading is sticky, so it stays over whichever rows you are reading. Click it and the Run against picker opens in place — see below. It changes no selection and rewrites nothing on disk.

A test case's row

Edit… opens the test case in the side panel. Finishing saves it back into the project it came from, never into whichever project happens to be active by the time you finish.

Putting a test suite in order

Which test case runs before which is what a Run all walks, so a test case that seeds state can be put in front of the one that needs it. Reorder test cases…, in a group heading's ⋯, sets the order of the test cases in that test suite. It acts on what is inside the group, never on the groups themselves: test suites and folders have no order of their own to set, and a test case never moves between them this way. Moving one between test suites is a filing act — retitle the session, or drag the file.

The rows drop back to a name and a pair of ↑ ↓, and a Done button appears where the ⋯ was; press it to leave. Reordering only reorders: no wording changes, no locator moves, and nothing is re-captured. The order of the steps inside a test case is set in the editor (Edit…), with the ↑ ↓ on each step.

Past runs

With a project connected, a run files itself into it the moment it ends — Terminate included — under a .groma-reports subfolder, one folder per test case and one file per run, so a history accumulates instead of each run overwriting the last. The tester then signs it on the done screen, and Save & view report writes their name and summary into that same filed copy and opens the report in a tab. Open a test case's row and, under its steps, its last run shows when it completed, whether anything failed and who signed it, with Open report beside it. Every run is listed under Test runs, newest first; All runs opens it on that test case alone. On each run you can Open its report in a tab, save it as a PDF (your browser's print dialog opens with the report laid out for paper), or delete that run. An opened report plays the run's video from the start; a PDF carries the screenshots and evidence and no video. To send someone a run with its video, use Share link on that run, or at the top of its opened report (Chrome, Edge and Firefox): Groma signs you in to Google and copies one link. If the project is already synced with Google Drive, nothing is uploaded — the report and video already there are made readable by link, and sharing the run again gives the same link. If it is not, a copy of the two goes into a folder of its own in your Drive, once — sharing that run again reuses it. Whoever opens the link sees the same report you get from Open, video included, in any browser — they do not need Groma — and can save it as a PDF. Anyone holding the link can open it, so send it only to the people you mean. To end a link, stop sharing those files (or delete that folder) in Drive; deleting the run on Home does not. The newest fifty are listed, and Show older runs lists more — every run is kept until you delete it.

Once a failed, skipped or noted step has been dealt with, open the run's report and press Mark as resolved under that step. Groma records the date and time, your name and an optional note in the filed run; the step keeps the status the tester gave it, and the report and its PDF show the resolution beneath it. Reopen clears it again. The run's row then reads resolved, or how many steps are still unresolved. A link shared before a step was resolved keeps showing the report as it was — use Share link again to send the resolved one.

Test runs groups the list by test cycle: runs close together in time count as one — a quiet stretch of more than 16 hours starts the next, and no cycle spans more than a week — so a burst of runs before a release reads as one pass, headed by its dates, how many runs it holds and the share of their steps that passed. Above the list, Test suite, Tester, Outcome and When narrow it — When takes Today, Last 7 days, Last 30 days or a Custom range — one day typed for that day alone, two for everything between them, both included, on your own clock's days. The summary above the list then counts how many test cases were run in that stretch and names those that were not. Open one and each choice says how many runs picking it would list — a test suite nobody has run reads 0; Show runs in a test suite heading's ⋯ opens it on that test suite, and Clear filters puts it back. A project switch starts it afresh.

The summary over the list counts the same runs: the pass rate of the latest test cycle and how it moved on the one before, runs filed, how many test cases have been run, and when it was last run. Show charts adds a pass rate by test cycle chart (hover a point for that cycle's dates and counts); where every step status landed (passed, failed, skipped, not reached); who ran it; each test case's own pass rate and last result, lowest first, with Show runs to list that test case alone; and the steps that keep failing. Every pass rate counts steps — those passed out of those passed or failed, a skipped step left out. The summary counts every outcome: Outcome narrows only the list. PDF saves the summary through the browser's print dialog — the numbers and charts as they stand, without the list of runs.

What is stored is the run's JSON, not its web page: the report you open is regenerated from it on demand by the same reporter that wrote the original, so there is only ever one copy of a run and no two formats free to disagree. The video is the exception — it is the one part that cannot be re-derived, so it is kept beside the JSON.

Filing never stands between you and a finished run: where no project can take it, the run downloads as a Groma archive to import later.

Project Issues Logged

Finishing an authoring session with a project connected also files what you logged into it, under a .groma-issues subfolder — both the issues you wrote yourself and the errors the app threw at you while you walked it. Project Issues Logged — the flag on the row of icons at the end of the project band — is where they are read back: one bucket for the whole project, newest first, each row naming the session it came from, how many issues it holds and how many of those the app reported on its own.

It is one bucket for the whole project: what is outstanding is a fact about the project, whichever test suite you were walking when you noticed it.

Download regenerates the Markdown a developer pastes into a tracker, from the stored records rather than from a second copy kept beside them; the delete confirms first, since this may be the only copy left of what you saw. None of it ever reaches a tester: a logged issue is never part of a test case, never rides a shared link, and is never included in a Test suite.

Repeated steps

Repeated steps — in the same ⋯ as Pages covered — lists every step that is worded the same in more than one test case, the most widely shared first. Pick one and the test cases that hold it open side by side, each in full, with the shared steps marked — so you can see whether two test cases are walking the same ground. Only the instruction is compared (capitals and spacing aside), it follows the search and filters, and it changes nothing: edit a test case from its own row.

Pages covered

Pages covered — in the ⋯ at the end of the project band's row of icons — lists every page your test cases actually visit — with how many test cases and how many steps land on each. It is worked out from the test cases themselves, so it costs nothing to keep correct: a page is on the list because a test case goes there, and it leaves the list when the last test case that went there is deleted.

It is deliberately a map of pages rather than of URLs. The query string is dropped (/search?q=hats and ?q=boots are one page exercised twice), a record id becomes :id so a real app is not forty rows of one order page, and a #/route is kept where an app routes on the hash. Where your test cases span more than one server — a payment or sign-in provider is part of a flow but not part of the app — each origin gets its own heading.

The counts are the point: 4 test cases · 22 steps beside 1 test case · 1 step is where the thin coverage is. But only pages your test cases visit can be listed: Groma has never seen the app, so a page missing from this list is one to check against what you know is there — not one Groma has ruled out. It follows the search box too, so you can ask what one test suite’s test cases cover rather than the whole project’s.

Smoke Tests — the critical checkpoints, before a deploy

Mark a checkpoint critical while authoring or editing, and Home lists it in a Smoke Tests group at the top of the library. The group holds one row per test case with a critical checkpoint in it. Each row carries only those checkpoints and the test case's preconditions, so a short pass over the whole app is ready whenever a release is. Nothing is maintained twice: the rows are worked out from the test cases every time Home paints, so editing the original is editing its smoke row.

Starting a new test case from here

The + on a group heading (or in the bar, when the project is still empty) asks which page to start from — prefilled with a start URL the project already uses, since most projects hold test cases for one app — and opens it in a new tab with an authoring session already running. Finish, and the test case lands in that project.

Run against — where a test suite's test cases run

A test case freezes its addresses when it is captured, so something has to say where it runs when that is somewhere else. That something is the server line on each group heading: click it and a short menu opens in place, listing as captured, the servers your other test cases in this project already use, and the ones you have open in a tab right now — plus Other address… for one that is neither. An address you type there is remembered per project and offered back next time.

One heading, one test suite, one destination: each heading points its own test cases and no others, so a project holding a staging test suite and a production one is not a contradiction. What you pick governs both the row's ▶ and the links the next Share builds, so the address you read above a row is the address it actually runs against. Only the server part of each URL moves — paths, queries, steps and locators stay exactly as captured, and a step that navigates off to a payment provider or a sign-on page is left where it is.

Nothing on disk is rewritten by picking one. A test case in your folder stays pointed where it was really captured, so it never comes back out aimed at wherever it was last sent, and re-pointing a test suite never makes its test cases read as edited.

Sharing from Home

Tick whichever test cases you mean. A Selected tray opens straight away at the top of the project band and stays in view as you scroll, holding one field and the ways to use the selection: Run selected runs them yourself, one after another in a new tab, saving each report into this project; Share link, Excel and Checklist PDF send them to someone else. Share link is the one to reach for: it puts the test cases in your Google Drive and gives you one link. Whoever opens it with Groma installed runs them as if from their own Home: the test cases and each report are saved in their own project, nothing is sent back to you, and they send you a report as a PDF or by its own Share link (see Past runs above). Anyone holding the link can open it, so send it only to the people you mean. Excel and Checklist PDF are the steps alone, to follow by hand; Groma hears nothing back from them. Two things decide what a shared test suite is:

Aiming happens at share time, never on the way into the project. That is deliberate: a test case in your folder stays pointed where it was actually captured, so it never comes back out aimed at whichever server it was last sent to, and re-pointing a test suite never makes its test cases read as edited. Send the same set at staging this week and a review box the next by changing one field and sharing again.

What you share is a copy, built from whatever the files say at the moment you press the button, so a test case you fixed this morning goes out fixed. The recipient can run those test cases and cannot change yours; a test case you edit afterwards reaches them only when you share again.

Checking a test case's locators against the live app

A test case points at buttons and fields by a locator frozen when it was captured. Apps change. Without a check, a stale locator is found by a tester mid-run or not at all — so the editor carries Check against the live app just above the step list (or Check all N test cases against the live app, when the test suite holds several).

  1. Press it and Groma opens the test case's start page in a tab of its own.
  2. Walk the flow yourself, as a tester would. Groma only looks — it never clicks anything for you.
  3. As you reach each page, every locator that lives on it is checked, and the step's row gets a mark. The bar keeps a running count: 12 of 17 found · 1 ambiguous · 4 not walked to yet.

One walk answers for the whole test suite, not just the test case on screen — the count is the test suite's, and each test case chip above carries its own small mark so you can see which one the trouble is in. Four marks are possible, and only two of them are problems:

A step you haven't walked to yet says exactly that and is not coloured as broken: at that moment the only fact Groma has is that nobody has been there. And a test suite whose checkpoints are purely visual has no locators to check — the button then just says Open the live app and offers the one thing the app is still needed for, which is picking a spotlight onto a step.

Sharing test cases

Test cases reach a tester from Home: tick them, and the Selected tray offers three ways out (see Sharing from Home above).

One field decides which server the shared test cases run against: Run against on a group heading on Home. It starts out set to wherever the test cases were captured, so if you author and test on the same server there is nothing to do. Change it and everything shared from that group opens against the new server instead: only the server part of each URL moves, and each test case's paths, queries, steps and locators stay exactly as you captured them. That is how the same set is run against staging one week and a review box the next — re-point it and share again. Steps that navigate somewhere else entirely, like a payment provider or a single-sign-on page, are left alone. Testers are never asked to choose: by the time a link reaches them the answer is already in it. That is also the security property — a tester cannot edit where a test case runs, so it can only run where its author aimed it.

The issues you logged are never part of what a tester receives: the test cases go to a tester, the issues go to whoever fixes them (see Project Issues Logged above).

A link needs Groma; Excel and PDF do not. A shared link opens Groma's run page. With the extension installed, the link's test cases are listed there to pick from; without it, the page says to install Groma. For someone who cannot install an extension, send the steps as Excel or PDF, to follow by hand. A shared report link is different: it opens for anyone, in any browser.

Running a test case

  1. Open the link you were sent. Under This link opens in Groma, Groma lists the link's test cases, each with the address it opens: untick any that don't apply, put them in order with the arrows, and press Run. (From Home, a row's ▶ does the same for one of your own.)
  2. Groma opens the app in a tab and step 1 appears in the panel beside it — there is nothing to click through first. Anything the author wrote about the flow, and anything that must already be true before you start, rides along with step 1.
  3. Spotlights lead you toward each checkpoint, advancing on their own as you act on each one; the ‹ › arrows under the instruction step through them by hand if you want one back. Turn spotlights off to free-form your way to the goal instead.
  4. At each checkpoint the panel shows its instruction and expectation. Judge the result and mark Pass (or Alt+P) or Fail (or Alt+X) — optionally with a note, which a Fail carries into the report along with a screenshot. The shortcuts work while you're in the app as well as in the panel, and while you're typing a note, so a long run needs no reaching for the mouse. Groma never auto-passes or auto-fails a checkpoint; the spotlights only guide, they never render a status.
  5. Can't attempt a step at all — no test card, a feature switched off in this environment — but the rest of the flow still works? Mark Skip (or Alt+K) and carry on. It is the one status that needs a reason: type it in the note box, since a skipped step nobody explained tells the report's reader that something was left out and not what would have to change for it to run. A skip is not a failure and is left out of the pass rate, so one untestable step doesn't drag a clean run down — the report states the count separately instead. Use it rather than failing a step that isn't broken; use Terminate instead if you can't carry on at all.
  6. A house at the left of the panel's header opens Home, the test case library, in a tab of its own. It ends nothing — your run stays exactly where it is, and switching back to its tab resumes on the step you were on. The undock mark on the right, left of the exit, moves the panel into a window of its own — for a second screen, or to minimise and bring back — and the run carries on from the same step; the same mark there docks it back (Chrome and Edge). The exit icon in the top corner opens the ways out, listed by how much survives. Picking one does it, except a row that would throw away steps you've judged: that one asks first, in its own place, with Stay as the default answer. Clicking anywhere else closes the list:
    • Finish later — everything. Parks the run on this device, closes the panel and brings Home forward. Pick it up later from the card there, on the step you left, even after quitting the browser. Inside a Run all it parks the whole sequence: resuming picks up the test case you were on, and the ones after it still run.
    • Terminate — the statuses. Ends the run here and writes the report. Every status you've given is kept; nothing is recorded for the step you were on, and the steps below it are counted rather than judged, so the report says "3 of 9 steps ran". It is not a status — leaving doesn't fail anything. Inside a Run all it ends this test case, and the sequence moves straight on to the next one with no going back to add more.
    • Discard this run — nothing. No report, no saved copy. Inside a Run all this row is Skip test case instead: write no report for this one, with an optional reason typed under it, and move on to the next. Stop the whole run-all below it ends the sequence here and keeps the test case you were on, just as Terminate would, along with every report before it.
    (On Safari the floating panel draws its own × instead of a Discard row — two ways to throw a run away, a few pixels apart, is a guess you shouldn't have to make.)
  7. If the author wrote a step for a particular screen size, your browser window is resized to it as you reach that step, before the page loads. Nothing else about the browser changes, and if the width can't be reached (browsers enforce a minimum), the panel says so rather than leaving you to fail a step over it.
  8. Nothing is lost if you close the panel — the run's page shows Reopen panel in its corner (or click the toolbar icon on the run's tab), and the run resumes on the step you were on. (If the recorder had stopped by then, the resumed run has no flow video, and Groma says so on screen rather than letting you find out in the report.)

A shared link, and Run selected or Run smoke tests on Home, run their test cases in sequence: each hands off to the next in the same tab with nothing to click between them, and each report is saved into your project as its test case ends. Nothing downloads. The run ends on one Run complete screen, after the last test case; it asks only for your name, which is written into every one of those reports. From the exit menu you can skip the test case in front of you or stop the whole sequence.

Where Groma has no project it can write to — a private window, or Safari's floating panel — a finished run, or a finished authoring session, downloads as a Groma archive instead: a zip holding exactly the files a project would have kept. Nothing is lost by it: on Home, open the project menu and pick Import from a file… to bring it into a project, where it lists and syncs like anything saved there directly. The same item takes a single test case file (.groma.json) someone sent you: it is added as a new test case, unless the project already holds that one.

Reports

A run is filed into your project the moment it ends. Sign it with your name and Save & view report adds your name and summary to that filed copy, then opens the report in a tab as the panel and the app's tab close. That tab reads the run from your project, so it survives a reload, and its replay plays step by step right there. The report holds per-step statuses and notes, a screenshot of every step you failed, and a video of the flow, all captured locally. The name you sign with is remembered on this browser, so the next sign-off arrives already filled in.

A picture in a report always means that step failed — passing steps carry none. What a passing step looked like is the video's job.

A failed step carries two more things beside its screenshot, on the same rule and covering the same window — only that step, only since it began:

Both are a mirror of what your own DevTools Console and Network tabs were already showing for that page. In the requests, Groma masks what it can recognise as a credential by name — an Authorization or cookie header, and a header, URL parameter or body field called password, token, secret, api_key and the like — and nothing else: an app is free to print anything it likes to its console, and a session id or someone's personal data under an ordinary name is something Groma has no way to tell from ordinary content. Read a report before you forward it widely. Both are best-effort: a page or engine that can't be watched (Safari has no full request observation) simply yields no log, never a blocked status.

The video records itself from the moment the run starts — there is nothing to switch on and no screen-sharing prompt. Every run is recorded: the tabs in the run's tab group only (see Which tab is Groma on?), showing the one you're looking at, and nothing while none of them is on screen. If a video can't be recorded — the recording couldn't start, or the run was resumed after the recorder had stopped — the panel says so and the run carries on without one. It is the length of the run, so a frozen screen still reads as a frozen screen, but the player can skip the pauses where nothing moved. Click a marker on its timeline to jump to a step, or press ▶ Play this step on any step below: the player moves down into that row and plays just that step's stretch, until you scrub the timeline yourself.

Nothing is sent back to whoever gave you the test cases. To hand a run back, save its report as a PDF, or use that run's Share link to send the report with its video (see Past runs above).

Because the run is filed the moment it ends, a closed panel or a forgotten Save loses nothing. A test case's last run sits under its steps on Home, and every earlier one is listed under Test runs, to open, save as a PDF, share or delete.

Appearance

The palette — Light, Dark, or follow your system — is the three icons in the top-right corner of Home; it is stored on this device and applies to every Groma surface, this page included. Your Projects, if you want any, are connected from the row just below them (see Keeping your test cases as files).

What Groma does to the app

Groma runs the app in an ordinary browser tab, so it needs no special access to the site itself — it changes no headers and touches no cookies. The app behaves exactly as it does when you open it yourself.

During a run Groma does watch two things about the app, to have something to attach to a failed step: it wraps the page's own console so the messages it prints are readable afterwards, and it notes the requests that tab makes — every one of them by method, URL, status and timing, and the ones the app makes in script by their headers, payload and response too, read from the page's own fetch and XMLHttpRequest. All of it is read-only: nothing is blocked, delayed, redirected or rewritten. Both cover only the tab a run is actually driving, and both stop when the run ends or its tab closes. Everything they collect stays on your machine, and only the part covering a step you failed reaches the report.

To test a flow at a phone or tablet size, resize your browser window — Groma records and runs at whatever size the window actually is. A step written for a screen size resizes the window itself when a tester reaches it, using the browser's ordinary window API; that needs no permission and does nothing to the app beyond making it lay out at that width.

Only use Groma on apps you're authorized to test, and only run test cases from people you trust — see the Terms & Conditions.

Troubleshooting

A shared link opened a web page instead of running in place

That page is Groma's run page, where every shared link lands. With the extension installed, Groma lists the link's test cases on that page to pick from — press Run and the run opens with each step spotlighted. Without the extension the page can only say so: install Groma and reload it, or ask whoever sent the link for the steps as a PDF or an Excel file.

The step panel doesn't appear beside the app

Reload the tab Groma opened. If the panel still doesn't appear, the app may have navigated away from where the test case starts — start the run again. (On Safari the panel floats over the page rather than docking beside it: Safari has no side-panel API.)

Groma won't start on this page

Groma can't act on browser-internal pages (chrome://, extension pages, about:). Open a normal web page first.

The browser window resized itself in the middle of a run

That's a step written for a particular screen size — the author wrote it against a mobile or tablet layout, and Groma puts your window to that width as you reach the step so you see what they did. The window stays there for the rest of the run unless a later step asks for a different width. Nothing else about the browser is changed.

Which tab is Groma on?

The one with a blue line under it in the tab strip — that's the tab to test on. Groma puts it in a tab group of its own while a run or authoring session is on, and ungroups it when the session ends. A tab already in one of your groups is left as it is.

To compare states side by side, open another tab or window from that tab, or drag a tab into the group: a tab or window opened from the group joins it (a window gets a group of its own in the same colour). The group is one run with one panel: move between its tabs and the panel stays with you at the step you're on. In another window, the Groma icon brings the run's window forward — or undock the panel to have it beside every window. The video and a failed step's screenshot show whichever of the group's tabs is in front in the window you're using; a tab outside the group is never recorded, and the panel says so beside one, with a button to add it. The run's own tab is still the one Groma navigates and spotlights. Closing the run closes every tab in its group; Finish later leaves them open, and picking the run up from Home reopens its own tab.

There's a badge on the Groma icon

Something is waiting for you. Click the icon: it opens Home, which leads with an Unfinished work section holding a card for each. (The house in a live panel's header leads to the same page.) Three things put the badge up:

Work being driven right now isn't counted — a run you're in the middle of is on screen, not waiting. Not now on a card hides it until you next open Home without touching what it holds. Anything left unclaimed is kept for 7 days.

I lost an authoring session — a closed tab, a crash, a browser restart

The draft is almost certainly still there. Groma parks a copy on this device as you work, so click the toolbar icon: Home leads with an Unfinished work card for the draft, to resume or discard. Only finishing the session, or discarding it yourself, clears it; drafts left untouched expire after 7 days. The toolbar icon badges while a draft is waiting, so you don't have to remember it's there.

I duplicated a test case and the copy doesn't work on the page

A copy carries the original's frozen locators, so it only resolves on the same site the original was captured on. To run it against another deployment, set Run against on its group heading on Home — that re-points every test case in the test suite at once, keeping each one's paths and steps exactly as captured, rather than leaving you to rewrite the copy's URLs by hand.

Questions?

Contact selahsolution@gmail.com. See also the Terms & Conditions and the Privacy Policy.