Check your computer

In plain words

Before you rely on a computer for playing back your steps, ask it one question: "can you run StepTrails?" One command answers it in about ten seconds. It gives you a short report that says ready, ready, with warnings or not ready, and tells you how to fix each problem. It is safe to paste the report into a chat, because it holds no names, folders or network addresses.

You need the StepTrails files and a terminal open in that folder. If you have not yet added the helper programs, do that first: Part 2 of the set-up.

Run the check

node bin/doctor.js

You should see a list with one line for each thing it looked at. Each line starts with a word:

Word	What it means
OK	This is fine.
WARN	It will work, but not as well as it could. The line under it says what to do.
FAIL	StepTrails cannot work until this is fixed. The line under it says how.
INFO	Something to know. It is not a problem.

At the bottom you will see the verdict, for example Verdict for replaying tests: READY.

What it looks at

• The system: the kind of computer, how many processors, how much memory and how much free space.
• Node.js and git: two programs StepTrails uses. Git is only needed if you download StepTrails with it.
• The StepTrails packages: the helper programs from the set-up.
• The browser: it opens a small page in the browser that StepTrails uses and tells you how long it took.
• The internet: it checks that it can reach github.com. Leave this out with --offline.
• A small server: it starts one on this computer only, for a moment, to see that it is allowed.
• Saving files: it makes a tiny folder next to you and removes it again.
• Administrator rights: some fixes on Linux need them. This is only a note.

What it cannot tell you

A check looks at one moment. It cannot know:

• whether the computer stays on when nobody is signed in, or when you close the window. You need that for runs on a schedule;
• whether the company that runs the computer allows programs that keep running in the background;
• whether the computer can be reached from the internet. A cloud computer usually cannot. A free tool called Cloudflare Tunnel solves that by making an outgoing connection instead.

For those, read the rules of the service, or try it for a day.

Is a cloud computer a good place to run tests?

A computer in the cloud that you reach through a browser can be a good place to play back tests, so your own laptop does not need to stay on. Run the check there. If the verdict is ready, replays will work. If you want it to run on a schedule, also confirm the first point above.

If it says "not ready"

Follow the line under each FAIL. The usual ones:

• Packages missing: run npm ci in the StepTrails folder.
• Browser cannot start: run npx playwright-core install chromium. On Linux, missing libraries need npx playwright-core install-deps chromium and administrator rights. If you already have Chrome or Chromium, you can point StepTrails at it with the setting STEPTRAILS_CHROMIUM.
• Not enough memory or space: use a bigger computer, or free some space.

Run the check again after each fix.

For programs

node bin/doctor.js --json prints the same answer as data. The exit code is 0 for ready (with or without warnings), 1 for not ready and 2 if the command was used wrongly.