Your first test in under 30 minutes
This guide takes you from an empty workspace to a recorded test that replays on your own machine. Follow the parts in order: each one sets up something the next part needs.
You will need:
- A development or staging copy of your app on a real domain you control, such as
staging.example.com. Localhost and private IP addresses cannot be used as site domains. - Access to the app's HTML
<head>, to add the recorder snippet. Access to its DNS settings helps too: it is the easiest way to verify the domain. - Node.js 20 or newer on the machine that will run your tests.
- Test accounts and test data only. Never record with real customer data.
How the pieces fit together
Five things make up a working test. Most confusion comes from how they connect, so here they are in one place.
| Piece | What it is | Why you need it |
|---|---|---|
| Site | Your app, with the domains Locus may record and test | Everything else belongs to a site |
| Environment | One place a test can run: a site domain, a scheme (https or http) and an optional port | A run always targets one environment |
| Secret | A saved value, such as a test password, that is never shown again after saving | Recorded passwords are masked, so a step needs a secret to type them on replay |
| Auth setup | A ready login test case that runs first and shares its signed-in session | Tests for pages behind a login start already signed in |
| Runner | The locus-runner program on your machine or in your CI | It opens the browser and runs your tests next to your app |
The order that works: register the site, verify its domain, add an environment, add secrets, record, review and mark the test ready, then run it with your runner.
1. Register your site
- Open Sites and press Register site.
- Enter a Site name and add your domain under Registered domains. Type the bare host name only, such as
staging.example.com: nohttps://, no path and no port. - Press Register site. You land on the site page.
Only workspace admins and owners can register a site.
2. Install the snippet and verify the domain
The site page shows the recorder snippet, with tabs for plain HTML, React, Next.js, Vue and Google Tag Manager.
- Press Copy Active Snippet and paste it inside the
<head>of your app, on every page you want to record. - Deploy that change to your staging site.
- In the Domains panel on the site page, press Verify next to your domain.
Install the snippet on staging only. Every visitor of a page with the snippet sees the small Locus toolbar.
Recording works before the domain is verified, but a test can only run on a verified domain. Any one of three proofs works (open How to prove a domain on the site page for the exact values):
| Proof | What to do | Good to know |
|---|---|---|
| Snippet | Install the snippet, then press Verify | Locus loads the root page of your domain and looks for the recorder snippet in the HTML: a script tag that holds your site key (the copied snippet, or a script tag with data-site-key). The key written as plain text elsewhere on the page does not count. It follows redirects that stay on your own host (for example / to /login), up to three. It fails if the root page redirects to another host (for example a single sign-on page on auth.example.com) or if the snippet is added by Google Tag Manager |
| DNS record | Add a TXT record on _locus-challenge.<your domain> (or the domain itself) with the value shown | Best for apps behind a VPN or a login |
| File | Serve the value shown at https://<your domain>/.well-known/locus-verification.txt | Works when you can add a static file but not change the root page |
3. Add an environment
- On the site page, press Environments, then Add Environment.
- Give it an Environment Name and a Slug Identifier, for example
staging. The slug cannot be changed later; you will type it when you run tests from the command line. - Pick the Domain, the Scheme and, if your app uses one, the Port.
- Tick Set as Default Environment and press Save.
4. Add your secrets before you record a login
Locus never stores what you type into a password field: it records a masked value instead. To replay a login, the test needs the password as a secret.
- On the site page, press Secrets, then Add secret.
- Enter a Name (lowercase letters, digits and
_, for exampletest_password) and the Value. Use the Show button to check what you typed: after saving, nobody can see the value again. - Press Add secret.
If one environment needs a different password, add a second secret named after the first plus the environment slug, for example test_password_staging. Steps keep using test_password; runs on the staging environment get the override.
5. Record a test case
- Open Test Cases, press New test case, enter a Test case name, pick the Site and press Continue to recording.
- You see a pairing code. If your app runs on a port or starts on a page other than the home page, type its full address (for example
https://staging.example.com:8443/app) in Your app's address; Locus remembers it for this site in this browser. Then press Open link in new tab within about ten minutes. If the code expires, press Generate a new code. - In your app, the Locus toolbar says it is connected. Go to the page where the test should start, then press Begin test case.
- Use your app the way a person would: click, type, submit. The toolbar counts the steps as you go.
- Press Finish in the toolbar. The dashboard prepares the test and opens it as a draft.
The toolbar only appears on a page that Locus has accepted, so open the link from the pairing page (it carries the code); there is no box to paste a code into. Press Alt+Shift+L to hide or show the toolbar while recording.
One flow per test case. If the same form can succeed or show an error, record each outcome as its own test case.
6. Review the test and make it ready
A new recording is a draft. Drafts do not run: you review it, then mark it ready.
- On the test case page, press Edit to open the editor. Steps that need your attention are marked Needs review.
- For a password step, open the Step tab, choose Secret Reference under Input Value Source and pick your secret.
- Add at least one check, so the test proves something. The quickest way is the Suggested checks panel on the test case page: press Accept on the checks that matter.
- You can also add a check in the editor: open the Assertions & waits tab, press + Add assertion, choose what to check and press Add Assertion.
- Press Save Definition. Nothing is kept until you do; the status changes from Unsaved changes to Saved.
- Press Mark ready. If it says steps need review, fix each step marked Needs review first, usually a password step that needs a secret or a step Locus could not find a reliable way to target.
A run without checks only proves that every step could be performed. Its result shows Passed, no checks.
7. Test pages behind a login
Record your login once, then let other tests reuse it.
- Record the login as its own test case, using a secret for the password, and mark it ready.
- On Test Cases, press Auth setups, then New auth setup. Pick the login test case and press Create auth setup.
- Create a folder with + Folder. Under Auth, choose Use a different auth setup and pick the one you just made.
- Put the tests that need a signed-in user into that folder.
- Run them as usual, with Run folder or Run on one test. The login runs first, and every test in the folder starts already signed in.
A test outside any folder never signs in first, so keep tests that need a login inside the folder. If the login fails, the tests that depend on it are shown as blocked instead of failed.
8. Run your test with the runner
During the pilot, tests run on your own machine or CI through locus-runner. Your app never has to be reachable from the internet.
- Open Settings, then API tokens, and press Create token. Choose the role Runner (Local Replay), set an expiry and press Create token. Copy the token now: it is shown only once.
- On the machine that will run the tests, install the runner and its browser:
npm install --global @locusqa/runner
npx playwright install chromium
- Start it, with your token in the
LOCUS_TOKENvariable:
export LOCUS_TOKEN="<your runner token>"
locus-runner listen --base-url "https://api.locusqa.com"
- In the dashboard, open Test Cases and press Run on a test, Run folder on a folder, or Run Collection for several. Choose your Target Environment, keep Execution Target on Local Runner (Your machine / network) and press Run Collection.
- The run page shows each step as it finishes. Stop the runner with Ctrl+C when you are done.
For CI, use locus-runner run instead of listen. It runs the tests you choose, writes a JUnit report and exits with 0 when everything passed. Run locus-runner --help for the options, and see the runner page.
9. Read the result
- Passed means every step ran and every check held.
- Passed, no checks means every step ran, but the test has no checks yet. Use Review suggested checks to add some.
- Failed shows the step that failed, why, and a screenshot of the page at that moment.
- Download trace gives you the full Playwright trace, which you can open in the Playwright trace viewer to replay the run step by step.
When something does not work
| What you see | What to do |
|---|---|
| Verify fails with the snippet installed | Your root page probably redirects to another host (such as a single sign-on page) or the snippet is added by a tag manager or by your app's JavaScript after the page loads (Locus reads the page as served, not as rendered). Use the DNS record or the file instead |
| The pairing code expired | Press Generate a new code and open the link straight away |
| Open link in new tab opens the wrong page | It opens the root of your first domain. Go to your start page in that tab, then press Begin test case |
| Mark ready is blocked | Open each flagged step and fix it, usually a password step that needs a secret |
| Your test does not appear in the run drawer | Only ready test cases can run. Mark it ready first |
| The run waits for a local runner | Start locus-runner listen with a runner token, and check --base-url is https://api.locusqa.com |
| A run says the domain is not verified | Verify the exact domain your environment uses on the site page |
| A test behind a login fails at the start | Move it into a folder that uses your auth setup |
Your app uses a port, such as :8443 | Type the full address in Your app's address on the pairing page before you open the link. It must be on one of the site's registered domains |
Stuck, or something here does not match what you see? Write to [email protected]: during the pilot, every question helps us fix the product.