Your environment. Your browser. Your pipeline.
Run Locus Playwright tests from your own machines and CI.
# Node 20 or newer
$ npm install --global @locusqa/runner
$ npx playwright install chromium
# a Runner token from Settings, API tokens
$ export LOCUS_TOKEN="$LOCUS_RUNNER_TOKEN"
$ locus-runner listen \
--base-url "https://api.locusqa.com"
Locus plans the run. Your runner executes it.
The runner only makes outbound HTTPS calls, so private apps stay private: no inbound firewall rule, no tunnel.
-
api.locusqa.com
Locus
- Test definitions
- Queued runs
- Results and evidence
-
your machine or CI job
locus-runner
- Runner token
- Playwright and Chromium
- Secrets held in memory
-
your network
Your application
- Staging behind a VPN
- IP allow-listed hosts
- Hosts inside a private VPC
Two commands
locus-runner listen-
A worker that stays connected and polls for runs your team queues with Local runner as the execution target. Stop it with Ctrl+C; it finishes the current step first.
locus-runner listen \ --base-url "https://api.locusqa.com" locus-runner run-
One run, for CI. It executes the selected test cases, writes a JUnit report and exits 0 when everything passed, 1 when anything failed.
locus-runner run \ --base-url "https://api.locusqa.com" \ --site "<site_id>" --env "<env_slug>" \ --all --junit locus-junit.xml
Both read the token from LOCUS_TOKEN, which keeps it off the command line. locus-runner --help lists every option.
Where the runner runs
Anywhere Node 20 runs and your application can be reached.
| Environment | How it is used |
|---|---|
| Developer workstation | Run listen; dashboard runs execute on your machine. |
| Staging behind a VPN | Run it on a machine inside the VPN. |
| Private VPC | Run it on an instance inside the VPC. |
| Docker | Run the npm package in your own Node 20 image. There is no official image yet. |
| GitHub Actions, GitLab CI | A job step runs locus-runner run and publishes the JUnit file. |
Start URLs must sit under a verified site domain. Localhost and raw private IP addresses are not accepted as site domains.
JUnit XML your CI already reads
--junit writes one test case per Locus test, with the failing step.
Decrypted secrets never appear in the report.
<testsuites tests="2" failures="1" ...>
<testsuite name="Checkout" ...>
<testcase classname="Checkout"
name="Guest places an order" time="..." />
<testcase classname="Checkout"
name="Expired coupon is refused" time="...">
<failure type="failure" message="...">
...</failure>
</testcase>
</testsuite>
</testsuites>
locus-junit.xml, abridged. Sample test names.Hosted or local
| Dimension | Hosted cloud runner | Customer-run local runner |
|---|---|---|
| Browser execution | Locus-hosted, sandboxed workers | Your machine or CI job |
| Reachable apps | Publicly reachable registered domains | Registered domains your network can reach |
| Infrastructure | Managed by Locus | Managed by you |
| CI | Runs queued from the dashboard | Your existing pipeline, JUnit out |
| Private networks | Not reachable | Reached directly from inside |