Command-line tools and runner runtimes for TestMutant.

The package has two first-class runtime adapters:

• Public CLI and GitHub Action flows for API-driven CI runs.
• Internal HTTP Playwright runner service for API-owned orchestration.

Both paths reuse the same Playwright execution engine under runner-core.

• Node.js 20 or newer
• A TestMutant API key

Run the CLI without installing it globally:

npx @testmutant/cli --help

Or install it globally:

npm install -g @testmutant/cli
testmutant ping

The CLI reads configuration from environment variables or command-line flags.

You can also put environment variables in a .env file in the directory where you run the CLI:

TESTMUTANT_API_KEY=tm_key_...
TESTMUTANT_API_URL=http://localhost:5086

Verify that the CLI can connect to TestMutant:

TESTMUTANT_API_KEY=tm_key_... testmutant ping

Use a non-default API URL:

TESTMUTANT_API_KEY=tm_key_... TESTMUTANT_API_URL=https://api.example.com testmutant ping

Pass configuration directly as flags:

testmutant --api-key tm_key_... --api-url http://localhost:5086 ping

Print machine-readable output:

testmutant --json ping

Store TESTMUTANT_API_KEY as a secret in your CI provider. Pass the deployed or preview application URL as the positional ci argument, or use --base-url. Example GitHub Actions step:

permissions:
  contents: read

jobs:
  testmutant:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v5

      - name: Run TestMutant
        uses: TestMutant/cli@alpha
        with:
          mode: Advisory
          base_url: https://preview.example.com
        env:
          TESTMUTANT_API_KEY: ${{ secrets.TESTMUTANT_API_KEY }}

Verifies that the CLI can authenticate with the TestMutant API and prints the connected organization and CLI API version.

Detects repository, branch, commit, and CI provider metadata, creates a TestMutant run, executes any Playwright tests returned by the API against the provided base URL, completes the run with pass/fail results, and prints the run id, status, and test counts.

testmutant ci https://preview.example.com
testmutant ci --base-url https://preview.example.com
testmutant ci --mode Enforce https://preview.example.com

Generated Playwright tests run with the CLI-managed Playwright runtime. In Enforce mode, failed generated tests are reported to the API before the CLI exits with a nonzero status.

Starts the internal HTTP Playwright runner service. This is for TestMutant API orchestration and is not a public customer CI entrypoint.

npm run build
node dist/index.js runner-service --port 8080 --token dev-runner-token

See docs/runner-service.md for endpoint, auth, and configuration details.

The hosted runner commands used by the API process/container are internal and hidden from public help output. See docs/hosted-runner-invocation.md for the API command shape, required environment variables, and Windows versus Linux/container packaging assumptions.

MIT. Copyright (c) 2026 Sleepycat Software LLC.