Run your tests on another computer

In plain words

You can leave a round of testing for a second computer to do while your own computer is switched off. That second computer can be a spare PC, a cloud computer, or a computer in another country. It plays the tests, writes down the results and sends them back. You do not need a server, and it costs nothing. This page is for people comfortable with a terminal.

How it works

Think of a shared notebook that both computers can read and write. That notebook is your project, kept in git (a tool that stores the project and shares it between computers).

1. On your computer, you start a round of testing and say which second computer should do it.
2. You share the project (this is called a push).
3. The second computer, called a runner, gets the latest project (a pull), plays the tests, and shares the results back.
4. You get the project again and read the results.

Before you begin

• The second computer needs StepTrails, Node.js and git. Check your computer tells you in about ten seconds whether it is ready.
• The project must be in a git repository that both computers can reach, for example on GitHub. The second computer needs its own login to it. StepTrails never stores a password.
• You need some tests already: see Keep track of your tests.

1. On your computer: leave a round for the runner

Give the second computer a short name, in small letters. Here it is jiopc:

node bin/manage.js run start --plan TP-0001 --runner jiopc

StepTrails answers with the round's name and says it is left for jiopc. Share the project:

git add .steptrails
git commit -m "Round of testing for jiopc"
git push

2. On the second computer: start the runner

Get the project and set up StepTrails there. Then, in the StepTrails folder:

node bin/runner.js --name jiopc --only-hosts shop.example.com --git

You should see a line such as Runner "jiopc" waiting for runs, every 60 s, with git. The runner now looks for rounds left for jiopc every minute. For each one it plays the recorded tests and shows a line per test. Then it shares the results back. Stop it any time with Ctrl+C.

Useful options:

Option	What it does
--once	Does one round of checking and stops. Good for a scheduled job.
--interval 300	Waits 5 minutes between checks. The default is 60 seconds.
--evidence	Keeps a picture of the screen when a test fails. It may show personal details, so read Keep track of your tests first.
--timeout 600	Allows each playback up to 10 minutes. The default is 5.
-- --locale de-DE	Everything after a lone -- goes to the playback, so the tests run in German. See Run from another place.

Without --git the runner works on the folder as it is. Then you keep the folder up to date yourself.

3. Back on your computer: read the results

git pull
node bin/manage.js run show RUN-20261025-1

Results written by a runner say runner jiopc next to them. A test that could not be played at all is marked blocked, with the reason.

Staying safe

The runner plays whatever the recordings in the project say, with nobody watching. A bad recording could try to open a page inside your own network. So the runner will not start unless you give it a list of allowed web addresses with --only-hosts. A recording that opens any other address is not played. It is marked blocked instead.

• Write host names only, such as shop.example.com. Use *.example.com for every name under it.
• The check covers the addresses a recording opens. It cannot know where a click leads. Also use your network's own rules, and only run projects you trust.
• --allow-any-host turns the list off. Use it only for a project that only you can change.
• Git is used with the second computer's own login. The runner shares only the test-management folder, never anything else in the project, and never forces anything over other people's work.

What it does not do yet

• It does not start by itself at a certain time. Use the second computer's own scheduler, or the GitHub template, with --once.
• One runner works on a round at a time. Do not give two computers the same name.
• The results page does not show which runner did what yet.
• It checks one moment at a time: whether the second computer stays switched on is something only that computer's provider can tell you.