Locus

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"
You can read the runner's code before you run it. The package includes the original TypeScript, and the licence is source-available.

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.

  1. api.locusqa.com

    Locus

    • Test definitions
    • Queued runs
    • Results and evidence
  2. your machine or CI job

    locus-runner

    • Runner token
    • Playwright and Chromium
    • Secrets held in memory
  3. your network

    Your application

    • Staging behind a VPN
    • IP allow-listed hosts
    • Hosts inside a private VPC
The runner calls out to Locus with a Runner token, claims a queued run, executes it next to your application and streams step results back.

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.

EnvironmentHow it is used
Developer workstationRun listen; dashboard runs execute on your machine.
Staging behind a VPNRun it on a machine inside the VPN.
Private VPCRun it on an instance inside the VPC.
DockerRun the npm package in your own Node 20 image. There is no official image yet.
GitHub Actions, GitLab CIA 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>
The shape of locus-junit.xml, abridged. Sample test names.

Hosted or local

Pilot workspaces run tests through the customer-run runner.
DimensionHosted cloud runnerCustomer-run local runner
Browser executionLocus-hosted, sandboxed workersYour machine or CI job
Reachable appsPublicly reachable registered domainsRegistered domains your network can reach
InfrastructureManaged by LocusManaged by you
CIRuns queued from the dashboardYour existing pipeline, JUnit out
Private networksNot reachableReached directly from inside

Keep test execution close to your application.

Request pilot access to run Locus tests from your own infrastructure.