TestBlocks Agent

Standalone Node.js CLI that polls the TestBlocks server for test jobs, executes them locally using Playwright, and reports results back.

Architecture

agent/src/
  index.ts      CLI entry point, poll loop, graceful shutdown (SIGINT/SIGTERM)
  config.ts     Configuration loading: CLI args > env vars > ~/.testblocks/agent.json
  client.ts     HTTP client for server API (validate, poll, progress, results, artifact upload)
  executor.ts   Job execution: writes spec files, spawns Playwright, parses results, uploads artifacts

Installation & Usage

# From the monorepo root
npm install

# Configure the agent
npx testblocks-agent config --server http://localhost:3001/api --token tbat_xxx --project <project-id>

# Start listening for jobs
npx testblocks-agent

Configuration

Configuration is loaded with this priority (highest first):

1. CLI flags: --server, --token, --project
2. Environment variables: TESTBLOCKS_SERVER, TESTBLOCKS_TOKEN, TESTBLOCKS_PROJECT
3. Config file: ~/.testblocks/agent.json

Config File Format

{
  "serverUrl": "http://localhost:3001/api",
  "token": "tbat_...",
  "projectId": "uuid-here"
}

How Execution Works

When a job is received from the server:

1. Create temp directory in os.tmpdir()/testblocks-agent/<jobId>/
2. Write files:
   • test-<n>.spec.ts — Generated Playwright spec for each test case
   • playwright.config.ts — Configuration (browser, timeout, retries, viewport, artifacts)
   • .env — Environment variables for the test run
   • package.json — Minimal package for the test project
3. Symlink node_modules from workspace root for Playwright access
4. Spawn npx playwright test --reporter=json as child process
5. Stream progress updates to server (test count parsing from stdout)
6. Parse report.json for per-test results (pass/fail/skip, duration, error messages)
7. Collect artifacts — screenshots, videos, traces from the test-results/ directory
8. Upload artifacts to server via multipart API
9. Report final results (status, per-test outcomes, timing)
10. Cleanup temp directory

CI/CD Integration

The agent supports a --ci mode for CI/CD pipelines. In this mode, the agent triggers a test run via the server API, polls for completion, and outputs results in a CI-friendly format. No local Playwright installation is required.

Basic Usage

# Run all tests, output TAP format
testblocks-agent --ci --server https://api.testblocks.io --token tbat_...

# Run specific suites with JUnit output (for CI systems)
testblocks-agent --ci --suite "Auth" --suite "Smoke" --output-format junit > results.xml

# Run tests by tag with JSON output
testblocks-agent --ci --tag p0 --output-format json

# Run a test plan
testblocks-agent --ci --plan <plan-id> --output-format tap

# Run with specific environment
testblocks-agent --ci --suite "Regression" --env staging

CI Flags

| Flag | Description | Default | |------|-------------|---------| | --ci | Enable CI mode (trigger + poll + output) | - | | --output-format <fmt> | Output format: tap, json, junit | tap | | --wait / --no-wait | Wait for completion | true in CI mode | | --timeout <seconds> | Max wait time | 300 | | --suite <name> | Suite name filter (repeatable) | all suites | | --tag <name> | Tag filter (repeatable) | all tags | | --env <name> | Environment name | none | | --plan <id> | Test plan ID | none | | --browser <name> | Browser override | project default |

Exit Codes

• 0 — All tests passed
• 1 — One or more tests failed or errored

GitHub Actions Example

- name: Run TestBlocks Tests
  run: |
    npx testblocks-agent --ci \
      --server ${{ secrets.TESTBLOCKS_SERVER }} \
      --token ${{ secrets.TESTBLOCKS_TOKEN }} \
      --suite "Smoke Tests" \
      --output-format junit > test-results.xml

- name: Publish Test Results
  uses: EnricoMi/publish-unit-test-result-action@v2
  if: always()
  with:
    files: test-results.xml

GitLab CI Example

test:
  script:
    - npx testblocks-agent --ci --suite "Smoke" --output-format junit > report.xml
  artifacts:
    reports:
      junit: report.xml

Legacy CI Mode (--once)

The --once flag triggers a test run and executes it locally using the agent's own Playwright installation. This requires Playwright to be installed on the CI runner.

testblocks-agent --once --suite "Auth" --env staging

Cancellation

• Server can cancel a running job via the cancel API
• Agent checks for cancellation during progress reporting
• On cancel: sends SIGTERM to Playwright process, reports cancelled status

Graceful Shutdown

• Handles SIGINT (Ctrl+C) and SIGTERM signals
• Kills any running Playwright child process
• Cleans up temp directories
• Exits with code 0