Keep track of your tests

In plain words

Recording and playing back tells you whether one check works. This part helps you keep track of all your checks: what they are, which ones to run this week, and how the last round went. It is a simple notebook that lives in your project folder. No account and no website are needed.

You need the helper programs from Part 2 of the set-up and a terminal.

Three ideas

Think of cooking.

In cooking	In StepTrails	What it means
A recipe	Test case	One check, written as steps: "Pay by card".
A menu for tonight	Test plan	The list of checks you want to do together: "Before the October release".
Cooking it tonight	Test run	One round of doing the plan, with a result for every check: passed, failed, blocked or skipped.

1. Create the notebook

In the StepTrails folder:

node bin/manage.js init

This creates a folder called .steptrails/manage. It holds small text files, one for each check and result. Because they are plain files, you can share them with your team the same way you share any other project file.

2. Add your checks

From a recording you already made (the steps are copied in plain words, with no passwords and no website addresses):

node bin/manage.js case add --title "Pay by card" --from steptrails-recording.json --priority high --requirement SHOP-1

Or by hand, for a check a person does:

node bin/manage.js case add --title "Refund an order" --requirement SHOP-2 --precondition "An order exists"

--requirement ties the check to the thing it proves, for example a ticket number from Jira. That lets StepTrails tell you which requirements are covered.

See your list any time:

node bin/manage.js case list
node bin/manage.js case show TC-0001

A check starts as a draft. When you are happy with it, mark it ready:

node bin/manage.js case set TC-0001 --status ready

3. Make a plan

Put the ready checks in a plan:

node bin/manage.js plan add --title "Before the October release" --status ready

You can also choose checks yourself with --cases TC-0001,TC-0002, or by folder or label.

4. Do a round of testing

Start a run. This creates a result slot for every check in the plan:

node bin/manage.js run start --plan TP-0001 --env staging --build 42 --by Raj

StepTrails answers with the run name, for example RUN-20261025-1. (To leave the round for a second computer to play, add --runner jiopc: see Run your tests on another computer.) Now fill in the results, any of these ways:

Play the checks for you. If a check was made from a recording, StepTrails can play it back and write down the result itself. This is the quickest way:

node bin/manage.js run execute RUN-20261025-1

You will see one line for each check as it finishes, for example TC-0001 passed Pay by card. What StepTrails does:

• It plays each recorded check, one after the other, and records passed or failed, the step that failed, how long it took, and a count of any security findings.
• Checks that a person does by hand are left for you. StepTrails says so.
• If a check could not be played at all (for example its recording file is missing), it is marked blocked and the reason is written next to it. That way a broken set-up is not mistaken for a problem in your website. The other checks carry on.
• Checks that already have a result are left alone. Add --failed to play again only the ones that failed or were blocked, or --again to play every recorded check again. --case TC-0001,TC-0003 picks checks yourself.
• To change how the playback works, add -- and then the options you would give to a playback. For example, node bin/manage.js run execute RUN-20261025-1 -- --locale de-DE --no-perf plays the checks in German and skips the speed measuring.

Keep a picture of what went wrong. Add --evidence:

node bin/manage.js run execute RUN-20261025-1 --evidence

When a check fails, StepTrails keeps the screenshot it took at the step that failed. You will see a line such as [screenshot: .steptrails/manage/runs/RUN-20261025-1/evidence/TC-0002.png]. Open that file to see what the screen looked like. The same line shows in run show and in report, and the results page says that a screenshot is saved with the run.

Look before you share

A screenshot shows everything that was on the screen. That can include names, email addresses or numbers. This is why it is off unless you ask for it. Look at the pictures before you share the folder. To keep them out of the files you share through git, add this line to a file called .gitignore in your project: .steptrails/manage/runs/*/evidence/

Only a real picture (a PNG, at most 2 MB) is kept. If the screenshot cannot be kept, the result is still saved and says why. When you play a failed check again and it passes, the old picture is removed. node bin/manage.js validate checks the pictures too.

See which bugs look fixed. After StepTrails plays the checks, it compares them with the earlier rounds. Suppose "Refund an order" failed last week and you wrote down bug SHOP-77. If it passes now, you will see:

RUN-20261026-1: 1 of 1 bug looks fixed.
  LOOKS FIXED  SHOP-77  TC-0002 Refund an order (passes now; it failed in RUN-20261025-1)
Nothing was closed or changed. Look at each fix, then close the bug yourself.

You can ask for the same view of any round at any time:

node bin/manage.js run verify RUN-20261026-1

• LOOKS FIXED: every check linked to that bug passes now.
• NOT FIXED: a check linked to it fails again.
• NOT CHECKED: the check was blocked or skipped this time, so nothing is known yet.

A bug counts as fixed only when all the checks that were linked to it pass. StepTrails never closes a bug or changes your Jira or GitHub. It only tells you where to look. Add --fail-on-unfixed to make an automatic system stop when a bug is still not fixed.

When something failed or was blocked, StepTrails ends with an error signal, so an automatic system can stop. Each playback may take up to 5 minutes; change that with --timeout 600 (seconds).

By hand, for a check you did yourself:

node bin/manage.js run record RUN-20261025-1 TC-0002 --status failed --comment "Refund button is missing" --bug SHOP-77

From a playback. Save the playback report, then attach it:

node bin/replay.js steptrails-recording.json --json > report.json
node bin/manage.js run import RUN-20261025-1 --replay report.json --case TC-0001

StepTrails records pass or fail, the step that failed, how long it took, and a count of any security findings.

From a test results file. Many testing tools save their results in a standard file that ends in .xml. If a test's name contains the check number, for example [TC-0001] Pay by card, StepTrails matches them for you:

node bin/manage.js run import RUN-20261025-1 --junit results.xml

When the round is over:

node bin/manage.js run finish RUN-20261025-1

5. See how it went

node bin/manage.js report --run RUN-20261025-1

You will see something like:

RUN-20261025-1: Before the October release
2 cases: 1 passed, 1 failed, 0 blocked, 0 skipped, 0 not run  (50% of the cases that ran passed)
  FAILED  TC-0002 Refund an order - Refund button is missing [SHOP-77]
Requirements: 1 of 2 covered by a passing case
  FAILING  SHOP-2 (TC-0002)

Leave out --run to see the latest result of every check across all rounds. Add --json to get the same facts in a form other programs can read, or --fail-on-failed to make an automatic system stop when something failed.

6. Share the results on a web page

Not everyone wants to use a terminal. You can turn your results into a web page that anyone can open, on a computer or a phone:

node bin/manage.js site --out results-page --title "Shop test results"

This makes a folder called results-page. Open the file index.html inside it with a double-click and your browser shows:

• Overview: how many checks passed, failed, were blocked or have not run yet, and a bar that shows the split.
• Needs attention: the checks that failed, with the note and the bug number.
• Test runs: every round, and the result of each check in it.
• Test cases: every check, with search and filters for result, priority and folder. Tap one to see its steps.
• Requirements: which requirements are covered by a passing check.

To share it, send the whole folder, or put it online behind a sign-in for free: see Put your results online for free. Many hosts have a free plan. The page works on its own. It does not contact any other website, does not use cookies and does not send anything anywhere.

This page has no sign-in

Anyone who has the folder can read it. It shows your check names, steps and notes. Share it only with people who should see them. To limit it to people with an account, use the sign-in server. StepTrails refuses to make the page if validate finds a problem, such as a password or key in a note.

Make the page again whenever results change. It only replaces files it made itself.

7. Keep it tidy

node bin/manage.js validate

This checks every file and every link between them, and warns you if a check mentions a missing recording. It also refuses to let a password, key or card number sit in these files, because they are meant to be shared.

Good to know

• Each check and each result is its own file. Two people can record results at the same time without getting in each other's way.
• Everything stays on your computer until you share the folder yourself.
• A finished run is locked. Until you finish a run you can record a result again if you made a mistake. After that it cannot be changed, so a finished round of testing is a record you can trust.
• Every command accepts --json for machine-readable output and --dir folder to use a different folder.
• Running node bin/manage.js with no words shows the full list of commands.

Connect it to your tools

Bring in your requirements from Jira, send results to the issues and create linked bugs: Connect your tests to Jira. Tell your team in Slack or Teams and raise bugs in GitHub: Slack, Teams and GitHub.

What is coming

Connections to more tools your team already uses, and dashboards that show how results change over time. See What's coming.