Testomat Run Panel

Testomat Run Panel — user guide

A Chrome side panel for running Testomat.io manual runs next to the site under test. You read the steps, tick them off, set passed/failed/skipped, add a comment, an annotated screenshot and a console/network log — without leaving the tab you are testing.

This is the single entry point. Read part 1 and 2 before the first run; the rest is reference.

Contents:

  1. Install and update
  2. Quick start
  3. Feature guide by tab
  4. Limits and quirks
  5. What it does NOT do
  6. Where to report a problem

1. Install and update

The extension is not in the Chrome Web Store. You install it from the repo as an unpacked extension.

Install

  1. Clone the repo:

    git clone https://github.com/testomatio/browser-extension.git
  2. Open chrome://extensions in Chrome.
  3. Turn on Developer mode (top-right toggle).
  4. Click Load unpacked and select the extension/ folder inside the clone — not the repo root.
  5. Pin the panel: click the puzzle-piece (Extensions) icon in the toolbar and pin Testomat Run Panel.

Chrome asks for the extension’s permissions once, at load: it works on all websites, because the site you test is different every session (see site access). There is nothing to grant per site afterwards.

Connect it to your project

  1. Click the Testomat Run Panel icon in the toolbar. The panel opens on the right.
  2. You land on Settings — the other tabs stay disabled until the connection is saved.
  3. Fill in Connection — one field:
    • General token — starts with testomat_. The link “Find it in Account → Access Tokens” under the field opens the access-tokens page of the instance you are pointed at.
  4. Click Save & validate. The panel makes a live call, loads every project that token reaches and picks one; on success the status line reads Connected ✓ and you land on the Runs tab.
  5. Working on a different project? Use the Project row at the very top of the panel — see switching projects.

If the token is not accepted the status line says so and names the host (“Token rejected by app.testomat.io — create a new General token there and save again”). Nothing is changed until a save succeeds, so a bad paste never breaks the connection you already had.

That is it for app.testomat.io — the instance is already filled in for you. Self-hosted? Open Advanced at the bottom of Settings (it is folded away behind its heading) and put your own https:// URL in Instance before saving. Nothing to approve — the extension already reaches every host.

Switching projects

The Project row sits under the panel title and is there on every tab. Click it and a list of every project your General token reaches drops down — start typing to filter it (the box matches both the project name and its slug), move with ↑/↓, pick with Enter or a click, and Esc closes it without changing anything. Picking one repoints the whole panel at it:

Nothing you had open in the old project is carried over, on purpose: a row or a suite from another project would be a wrong-project write.

Per instance, per token: the project list belongs to the instance in Advanced. Point the panel at another host and you authorize there again — a token from one instance means nothing on another.

Update

  1. git pull in the clone.
  2. Open chrome://extensions and click the reload (↻) icon on the Testomat Run Panel card.
  3. Reopen the panel.

Your settings and the offline queue survive the reload.

2. Quick start

Zero to a first passed test, shortest real path:

  1. Open the site you are testing in a normal tab.
  2. Click the Testomat Run Panel toolbar icon to open the panel. Keep the tab under test focused when you capture or record — a chrome:// page is off limits to every extension.
  3. Runs tab → click your run. (No run in the list? Create it in the web app, or paste the run link into the search box above the list.)
  4. The run opens as a checklist grouped by suite. Click a suite header to expand it, then click a test row to open the test.
  5. Read the steps. Click a step’s checkbox to tick it off as you go — optional; the test status is what is reported.
  6. Click ✓ Passed (or press ⌘/Ctrl+Enter). The panel saves and jumps to the next untested test.

That’s it. For a failure, see the failure flow.

3. Feature guide by tab

The panel header is three rows, top-down:

| Tests   Runs   Settings      ● Rec |   tabs (Rec chip only while it can record)
| Project: Your Project            ▾ |   the active project, on every tab
| ← Manual tests at 29 Jul…          |   only while a run / test / suite is open

Three tabs at the top: Tests, Runs, Settings. Each tab remembers where you left it. The third row appears only when you have drilled into something — it names what is open, and its back arrow navigates inside the current tab. On a tab’s own landing screen (the test tree, the runs list, Settings) there is no third row: the highlighted tab already says where you are.

Runs tab

Runs list

Run view

Test view

The test’s name is in the panel header. Under it comes the test’s own summary card — the same card the run view opens with, so nothing moves as you go in and out of a test: the marks this test carries on the top line, the run’s progress under them, and a foot band with the shortcut legend and the pager. Then the three status buttons, and then the screen splits in two sections you switch between:

Description — what to do: the steps. Status — what happened: the reported result, the assignee, the custom status, the comment and the attachments.

The buttons stay above both, so marking a result is one click away whichever section is open. Marking one moves you to Status, which is where everything you write about a result lives. A dot on the Status segment, in the colour of the result, says the test already has one.

Moving on: marking a test leaves you on that test — every status, whether you clicked a button or pressed its shortcut. That is deliberate: Custom status, Assignee, the comment and the attachments only appear once the test carries a real status, and being redirected at that exact moment hid them. Failing additionally opens Attachments & log for you, since that is when you attach evidence.

You move on with the pager’s › (one step down the visible list) or with N — the next untested test, skipping anything already graded. When nothing untested is left you get Run complete 🎉 and land back on the run; if the test you are on is the last untested one, the panel says so and stays put. Fast marking is therefore two keystrokes — the status shortcut, then N. A landed status says nothing under the buttons: the chip in the card, the filled button and the dot on Summary are the answer. If a status fails to save, the status rolls back and the failure is toasted, so you never move on from a test the server never recorded.

Keyboard shortcuts (test view only, and never while you are typing in a field):

Action Keys
Passed ⌘/Ctrl + Enter
Failed ⌘/Ctrl + U
Skipped ⌘/Ctrl + I
Next untested test N
Previous test ↑ / ←
Next test in list ↓ / →

Arrows move ±1 through the visible list (filter and search applied) and stop at the ends — they never wrap and never write a status. N is the one that skips tests you have already graded.

Failing a test: the full story

  1. Before reproducing, click Rec in the panel header. Nothing pops up — no “…is debugging this browser” bar, and you can keep DevTools open. The recorder keeps only the last N seconds (60 by default), so arm it first.
  2. Reproduce the bug in the tab.
  3. Open Attachments & log → Console & network log to see the errors and failed requests as they arrive. Attach copies a single entry into the comment.
  4. Type what you saw in the comment.
  5. Click ✗ Failed. The panel then:
    • records Browser, OS, Viewport and URL as meta on the result — they show up in the Meta section of the test detail on the web, not in the Failure box (toggleable in Settings),
    • uploads the console+network log as a readable .txt and adds it as a Console & network log meta key (toggleable in Settings),
    • keeps you on the test and opens Attachments & log for you.
  6. Optionally 📸 Attach screenshot → annotate → Apply.
  7. Click Rec again to stop recording.

The annotator

After a capture, the screenshot opens as an overlay on the page you captured (if the page can’t host it, it opens in a tab instead and says so).

The toolbar reads left to right: the tools, the ink they draw with, the history, then what to do with the picture. Every button carries its shortcut in the tooltip, and ? opens the whole keyboard map over the image.

Tools (the letter picks it):

  Tool   Tool
V Select H Highlight — translucent marker
P Pen — freehand B Blur — softens, and destroys what was under it
A Arrow T Text — click, type, Enter
L Line N Number — drops 1, 2, 3… as you click
R Box C Crop — drag the part worth keeping
O Ellipse    

Ink — the colour swatch on the bar is the colour you are drawing with; click it for the other seven (or press 1–8, which never opens anything). Three stroke weights sit beside it ([ and ]). Pick either one with an annotation selected and it restyles that annotation instead of the next one. The weight is also the size control for what has no stroke: a text label and a numbered badge come out small, medium or large with it.

While you draw freehand, the pointer becomes the tool — a pen or a marker, in the ink it is about to lay down. The shape tools keep the crosshair, because a glyph would cover the corner the drag has to start on.

History — Undo (⌘/Ctrl Z) and Redo (⇧⌘/Ctrl Z) step through everything: draws, moves, deletes, restyles and crops alike.

With Select, click an annotation to pick it, drag it to move it, and press Delete (or Backspace) to remove it — Esc drops the selection.

A picked shape shows its grips: a box, an ellipse and a blur take their four corners (drag one, the opposite corner stays), a line takes its two ends, and an arrow takes its two ends plus a round grip in the middle — drag that and the arrow bends, which is how you reach around a dialog without drawing three arrows. Every drag is one step of Undo. Double-click a text label to retype it: it reopens as the input that wrote it, in its own place, with the words selected so typing replaces them. Enter commits, Esc puts the old wording back, and emptying it removes the label. Either way it is one step of Undo.

Then:

Tests tab

Browse and author test cases.

Reading a test

An existing test opens as a plain page: its title, its priority, and its description and steps as formatted text. Nothing on it can be changed — tests are edited in Testomat itself. ◀ goes back to the suite’s list.

Editor (new tests)

Creating a test opens the Markdown editor. Top to bottom: the header (◀, the trail, the priority dropdown), the title field across the full width, the Edit / Preview tabs, the writing tools, the text, and Save / Cancel in the footer. The title field takes a second line when the sentence needs one; Enter there moves you into the body rather than breaking the title. Leaving with unsaved work — Cancel included — prompts Save & leave / Discard / Cancel, and Cmd/Ctrl+S saves from anywhere on the page.

New tests are pre-filled from your project’s New Test template — the ones managed in Testomat (Project settings → Templates). The template dropdown leads the tools row above the text: the project’s default template is picked for you, and choosing another one fills the body with it. If you have already written something, it asks before replacing it. A project with no test template simply opens an empty body and shows no dropdown. Switch projects in the header and the next new test uses that project’s templates.

A test needs a title: saving without one outlines the field in red and says so right under it (the message clears as soon as you start typing). Save creates the test and the page turns into the read-only view of it — from there on, further edits happen in Testomat.

Two evidence tools share that row, next to the template dropdown (all three belong to Edit — Preview just shows the result):

Step recorder

Recording is part of writing a new test, so it lives in the editor.

  1. Open the tab you want to record, then start a new test.
  2. Click ● Record steps.
  3. Work through the flow in the page. A dark pill in the bottom-right corner counts what it caught (Recording · 7 steps) and carries + Expected, Pause and Stop buttons.
  4. Watch the test write itself: every action is appended to the ### Steps list a second or so after you do it, while the recording is still running. A page transition hangs under the step that caused it as an Expected: line — The "Sign in" page opens right under the click that opened it. The section is created if the test has none, and existing items are kept.
  5. Click ■ Stop recording (N) in the editor (or Stop in the pill) when you are done. That only ends the recording — the steps are already there.

What it records: clicks and double-clicks on buttons and links, typing into fields, dropdown selections, checkboxes and radios, and navigations. Custom controls that modern web apps build out of <div>s are recognized by their ARIA role and get the wording that fits — Open the “Details” tab, Choose “Export” in the menu, Toggle the “Dark mode” switch, Select “QA”.

Sensitive values are kept out of the steps. A password, a card number, a CVV, an expiry, a one-time code, a passport number or a tax id records as Type the password / the card number / the value into the … field — the field is named, the value is not. It is recognized from the field’s type, its autocomplete, the words it is named and labelled by, and — for a card — the number’s own checksum, so a card typed into a field called anything at all is still caught. That last net aside, the recognition is best-effort: if the site you test handles real payment or identity data, turn on Settings → Step recorder → Never record entered values and no value is recorded at all (see below).

Steps say where you clicked, not just what: a control inside a table row or a card is recorded with that row’s name, and one that has no label of its own borrows its column header. So the bulk checkbox in a product table records as Check the Bulk checkbox in the “Bolt Cutters” row instead of Check the checkbox. Outside lists the enclosing section answers instead — the nearest heading above, or a form’s caption: Click the “Save” button in the “Shipping” section. Only one such clause is ever added, and never one that just repeats the control’s own name.

Expected results while you record. Click + Expected in the pill the moment you have checked something, type what you saw and press Enter (Esc drops it). It attaches to the step you have just done, as the Expected: line the run panel shows under that step — the same place the automatic page-transition lines go. Nothing you type there is recorded as a step, and the page underneath never sees the keystrokes. Each expected result counts toward the step limit like a step.

Need to step out of the scenario mid-recording? Click Pause in the pill. It turns into Paused · N steps with a Resume button, and everything you do in between — clicks, typing, even navigating away — is dropped instead of landing in the test. Resume picks up exactly where you left off. (The editor’s Stop button says “— paused” while that lasts.)

It also pauses by itself at 50 steps and asks “Still recording?” — click Continue for another 50. That is a different pause: Continue raises the limit, Resume does not. Closing the recorded tab — or the editor — stops the recording, and everything recorded up to that moment is already in the test. The output is human-readable Markdown, not Playwright code.

Nothing recorded leaves your browser except into the test you are writing: the steps go straight into the editor, and the only place they are ever sent is your own Testomat instance, when you save.

Settings tab

Always-on bits

4. Limits and quirks

Basic vs full (JWT) mode

The panel authenticates with your General token, then quietly upgrades it to a session. Everything that lives on Testomat’s web API needs that session. When the upgrade fails you get basic mode: a Basic mode pill in the test view and a banner on the runs views, which suggests signing in to the instance in the same browser and clicking Refresh.

Available in basic mode: the runs list (a flatter one), opening runs and tests, reading steps, setting passed/failed/skipped, comments, the offline queue.

Not available in basic mode:

Site access: allowed everywhere from install

The extension asks for access to all websites when you install it, and that is the end of the subject — there is no per-site step, nothing to grant mid-run and nothing that expires when you switch tabs. It is the same model Jam, Tango and Loom use.

What that does and does not mean:

The “…is debugging this browser” bar

A Full page screenshot uses the DevTools protocol, so Chrome flashes its infobar over the tab while that shot is taken and drops it straight after. That is expected, and it is now the only thing that raises the bar: a plain viewport screenshot uses Chrome’s own capture and raises nothing, and recording does not either — it never touches that protocol. Recording also survives DevTools being open on the tab.

Another extension on the page can block a full-page screenshot

Some extensions put a frame of their own into the page they run on (overlays, sidebars, assistants — Jam and 1Password are the common ones). Chrome then refuses to let any other extension attach the DevTools protocol to that tab, so a Full page screenshot cannot be taken there. What you get instead is the viewport shot, with a note saying the page was cropped — and a plain viewport screenshot is unaffected in the first place, since it does not use that protocol at all. To get the whole page, turn that other extension off for the page or run the session in a clean Chrome profile.

Rec is not affected any more. It used to be blocked on exactly these pages; the recorder now works inside the page instead, so it records there like anywhere else.

Live sync is polling, ~20 s

While a run (or a test of it) is open and the panel is visible, the panel re-reads the run every 20 seconds and repaints what changed — a colleague’s status or assignee change lands within that window, with a toast if it hit the test you have open. Your own writes are never overwritten and trigger an immediate refresh. Switching back to the panel also refreshes immediately.

There is no push: if you need “now”, use Refresh on the runs list or reopen the run. Real-time push is blocked on server-side work.

Offline queue

If a status write fails because of the network (or a paused/refused token), the panel keeps your click, shows queued on the row and test, and counts it in the N changes pending strip. It replays when the connection returns, when you hit Retry, when a poll succeeds, and when you open the panel or a run. The queue survives a browser restart. If a sync is already running when you hit Retry, the panel tells you so and runs your retry right after it — the click is never simply ignored.

Only test statuses ✓/✗/– (with their comment) are queued. Assignee, custom status, finish-run, step results and uploads are not — they fail with an honest error.

The queue only drains while the panel is open. Close the panel with pending items and they wait for the next time you open it.

Recorder limits

Step recorder:

Console/network recorder:

Smaller things

5. What it does NOT do

Worth knowing before you plan a session around it:

Security or privacy question — what is sent where, and how to turn it off? One page answers them all: PRIVACY.md.

6. Where to report a problem

Issues go to the repo: https://github.com/testomatio/browser-extension/issues

There are no issue templates yet, so please include:

Label the issue bug for something broken, enhancement for an idea, or question if you are not sure. Anything site-access, recorder or upload related: say which site you were on, and what Chrome shows under chrome://extensions → Details → Site access.

This site is open source. Improve this page.