Appearance
Record a session
In plain words
Recording is how you show StepTrails what to do. You click through your website once, and every click and every word you type is written down as a step. Then you can check, tidy and save it.
The extension watches what you do and saves it as a recording file.
Before you begin
Install the extension and reload the tab you want to record.
Record
- Navigate to the page where your flow starts.
- Click the StepTrails icon and choose Start recording. A red REC badge appears on the icon.
- Perform the flow. Reopen the popup at any time to see how many steps were captured.
- Click the icon and choose Stop recording.
- Review the steps, then choose Download Playwright test (see Generate a test script) or Save recording (.json).
The popup refuses to start on pages it cannot record, such as chrome:// pages, and says why.
Add checks
A check says what must be true at a point in the flow, for example "the page shows Order confirmed". While recording, right-click the element and choose one of:
| Menu item | What replay verifies |
|---|---|
| StepTrails: check this text is shown | The element still contains that text |
| StepTrails: check this field value | The field has the value it had when you recorded |
| StepTrails: check this is visible | The element is visible |
| StepTrails: check this is not visible | The element is hidden |
A failed check stops the replay and the report shows what was expected and what was found. Password values are never saved as checks.
How the recorder picks the element
The recorder records the element you actually used, once, and nothing around it:
- Clicking an icon or text inside a button, link, switch, table row or dialog records that control, not the inner icon or span.
- A box that only the script makes clickable (it shows the pointer cursor) is recorded as one control, not its inner text.
- Typing is recorded on the field itself. Clicking a field's label just to focus it adds no extra step.
- Things you cannot do are not recorded: disabled buttons and fields, read-only fields, right-clicks.
- Elements below the fold, inside scrolled boxes, frames and shadow DOM are recorded the same way.
- A styled checkbox whose real box is hidden is recorded as a check on that box. Replay and generated scripts toggle it directly, because a hidden box cannot be clicked.
How locators are chosen
The recorder follows what an experienced test engineer would do by hand, best first: a test id the developers added (data-testid), then the control's role and accessible name (for example role=button[name="Save"], the same words a screen reader says), then a stable id, label, placeholder or text. When the same words appear many times, the locator is scoped to its row or container: li:has-text("Beta") >> role=button[name="Delete"]. Generated ids, class names that only style, the text a user typed into an editor, and positions are used only when nothing better exists, and are marked Weak. Every locator must find exactly one element on the page before it is kept.
Check how reliably each step finds its element
For every click, typing or selection the recorder keeps up to three locators: different ways to find that element, such as its test id, its name, its label, its text or its position. Each one is checked on the page while you record (it must find exactly one element) and gets an accuracy score from 1 to 100, shown as High, Good, Fair or Weak. A generated test tries the best locator first and falls back to the others if the page has changed.
In the review list, click ▸ 3 locators under a step to see them:
- Locate highlights the element on the page (the highlight lasts about 8 seconds, so switch to that tab if it is not the one in front).
- Each locator shows how many elements it matches right now: 1 match (exact) is what you want.
- Check locators on picks which open tab to check. It starts with the tab you recorded. Re-check all tests every locator on that tab and marks each step Found, Uses a backup (the best locator no longer works but another does), Not found, or a count when it matches several elements. Steps that belong to a different page than the tab show Different page.
Open the page you are testing in a tab, press Re-check all, and fix anything that is not green before you download.
Include session values
Open Options before you start and tick Stay logged in when replaying if the flow needs you to be logged in. This stores cookies and storage values so replay can restore the login. After you stop, a matching Include my login in the test box lets you decide per download.
Treat the file like a password
A recording with session values can contain login tokens. Never share it or attach it to an issue. Without the option, only names are stored.
What is captured
Clicks, typing, dropdowns and multi-selects, checkboxes and radios, date pickers, sliders, key presses, file uploads and address-bar navigations. It works inside iframes and open shadow DOM. See Supported controls.
Only real user actions are recorded, not events a page triggers by itself. Passwords are saved as ***.
Limits
chrome://pages and the Chrome Web Store cannot be recorded.- Closed shadow DOM and pop-up windows are not captured yet.
Fix your steps before downloading
After you press Stop recording, the popup lists every recorded step with its action (Click, Type, Check and so on). Give the test a name at the top, then:
- Reorder a step with the ↑ and ↓ buttons.
- Delete a step with the ✕ button, for example an accidental click.
- Correct a value by editing the box under a typed or selected step, for example to fix a typo. Passwords and other masked values cannot be edited; they are supplied when you run the test.
- Add a pause with the ⏱ button, which inserts a 1 second wait after that step. Use it when a page needs a moment to load.
The first step (opening the page) cannot be deleted or moved. Editing is only possible while recording is stopped. Start a new recording at the bottom throws the steps away, after a second click to confirm.