Share your results safely (with sign-in)

In plain words

The results web page from Keep track of your tests has no password: anyone who gets the folder can read it. This page shows how to let only people with an account see your results. Each person gets their own email and password, and you decide which projects each one may open.

You need the helper programs from the set-up page and a terminal. Someone comfortable with a terminal should do the one-time set-up. After that, everyone else just opens a web address and signs in.

What people can see

Role	What it means
viewer	Can look at results, test plans, runs and requirements.
tester	Can do everything a viewer can. If you switch it on (see below), can also record results on the page.
lead	Same as tester, plus the person in charge of a project.
admin	Looks after the system.

Each account lists the projects it may open and a role in each, for example shop=viewer. A star means every project: *=admin.

1. Create the accounts

Do this on the computer that will run the server. You are asked for the password, and it is never shown on screen.

node bin/manage.js user add ada@example.com --projects "*=admin" --name "Ada"
node bin/manage.js user add sam@example.com --projects shop=viewer

To have StepTrails choose a strong password for someone, add --generate. It shows the password once. Write it down, then give it to the person safely.

A password needs at least 12 characters. A few random words work well.

Other useful commands:

node bin/manage.js user list                          # see all accounts
node bin/manage.js user projects sam@example.com --projects shop=lead,blog=viewer
node bin/manage.js user passwd sam@example.com        # set a new password
node bin/manage.js user disable sam@example.com       # lock an account at once
node bin/manage.js user audit                         # who signed in, who looked at what

The accounts are kept in a private folder called .steptrails/server. It keeps itself out of your project's history. Never share that folder.

2. Start the server

On your own computer only:

node bin/manage.js serve

Open the address it prints, usually http://localhost:8787. People on the same computer can sign in.

3. Let other people reach it

When other people will use it over a network, the connection must be secured with HTTPS. Otherwise passwords travel as plain text. StepTrails refuses to start on a network address without HTTPS.

The usual way is to run the server behind a web server or a free service that provides HTTPS, then tell StepTrails:

node bin/manage.js serve --host 0.0.0.0 --behind-https-proxy --host-name results.example.com

--host-name is the web address people will type. The server refuses requests for any other name. If you have your own certificate files, use --tls-key and --tls-cert instead of --behind-https-proxy.

To show more than one project:

node bin/manage.js serve --project shop=shop/.steptrails/manage --project blog=blog/.steptrails/manage

Let testers record results on the page

By default the page is read-only. To let people with the tester, lead or admin role record results without a terminal, start the server with one more word:

node bin/manage.js serve --allow-results

You should see People with the tester role or higher can record results on the page. Now, when a tester opens a run that is still in progress, each test case has a Record button. It opens a small form:

1. Choose the result: passed, failed, blocked or skipped.
2. Add a comment if you want to (up to 400 characters).
3. Add bug numbers if you want to, such as SHOP-12.
4. Press Save. The page updates at once and the run stays open.

How it stays safe:

• Viewers can never record. They do not even see the button, and the server refuses them if they try.
• Only a run that is still in progress. A finished run cannot be changed.
• The server writes down who recorded it. It uses the account's name (or the part of the email before the @). Nobody can type in someone else's name.
• A mistake can be corrected by recording again. The log keeps what it said before.
• No secrets. If the comment holds a key, a password or a card number, nothing is saved and you are told why.
• A limit of 60 results a minute for each account.
• The log records every result and every refusal: who, which project, run and test case, and the old and new result. It never holds the comment.

The results are saved as small files in the project folder on the server's computer. Share them the way you share the rest of the project, for example with git.

What keeps it safe

• Passwords are never stored. Only a salted one-way scramble is kept, and the file is private to the person who runs the server.
• Guessing is slowed down. After five wrong tries the sign-in waits, then waits longer each time.
• A wrong password and an unknown email look exactly the same, so nobody can find out who has an account.
• Sessions end by themselves: after 8 hours of no use, and always after 24 hours. Signing out ends it at once. Restarting the server signs everyone out.
• Other websites cannot act for a signed-in person. The session cookie cannot be read by page scripts and is not sent from other sites.
• A project you may not open looks the same as one that does not exist.
• The page makes no requests to other websites, and the browser is told to refuse anything else.
• Disabling an account or removing a project takes effect on the very next request.
• A log records sign-ins, failed tries and who looked at which project. It never holds passwords.
• Results that contain a password, key or card number are not shown to anyone until they are fixed.

Good to know

• Only people you create an account for can sign in. There is no public sign-up.
• Today you manage accounts in the terminal. A page for that, and editing test cases on the page, are planned. See What's coming.
• People can also sign in with one click using Google or Microsoft. See Sign in with Google or Microsoft.
• No server and no computer that stays on? See Put your results online for free, with sign-in.
• Keep the results page that has no sign-in (site --out) for your own computer or for people you trust.