@sudobility/testomniac_runner

Scanner worker service for Testomniac. A thin wrapper that launches Puppeteer, polls for pending test runs, and delegates execution to @sudobility/testomniac_runner_service via runTestRun().

Architecture

The runner is a stateless HTTP-polling worker. It communicates with testomniac_api exclusively via HTTP using X-Scanner-Key authentication -- it never accesses the database directly. All execution logic (element extraction, page analysis, test generation, expertise evaluation, finding creation) lives in testomniac_runner_service.

Every SCAN_POLL_INTERVAL_MS (default 10s):
  GET /api/v1/scanner/runs/pending
  If run found -> claim it, launch browser, call runTestRun()
  On completion -> PATCH /runs/:id/complete
  On error -> PATCH /runs/:id/complete with failure

RunnerManager tracks active runs and spawns up to MAX_CONCURRENT_RUNNERS (default 5). Within each run, test jobs execute across 3 worker threads by default.

Key Responsibilities

• Polling: Claims pending test runs from the API on a configurable interval
• Concurrency: Manages parallel test runs via RunnerManager
• Browser: Launches Chromium via Puppeteer-core with a persistent browser profile (ChromiumManager)
• Adapter: PuppeteerAdapter implements BrowserAdapter from testomniac_runner_service
• Plugins: SEO, Security, Content, and UI Consistency check implementations
• Auth automation: Form login detection, credential management, 2FA handling, and Signic disposable email registration for testing sign-up flows
• Email reports: Scan summaries via Postmark with deep-link JWT tokens
• Health endpoint: HTTP /health on port 8030 (Hono)

Setup

bun install
cp .env.example .env
# Fill in SCANNER_API_KEY and other values

Running

bun run dev      # Watch mode (polls for pending runs, restarts on changes)
bun run start    # Production mode

Health check:

curl http://localhost:8030/health

Commands

| Command | Description | |----------------------|------------------------------------| | bun run dev | Start in watch mode | | bun run build | Bundle with Bun | | bun run start | Run production build | | bun run test | Run Vitest tests | | bun run test:unit | Run unit tests only | | bun run test:watch | Vitest watch mode | | bun run typecheck | TypeScript type check | | bun run lint | ESLint | | bun run lint:fix | ESLint with auto-fix | | bun run format | Format with Prettier | | bun run verify | typecheck + lint + test + build |

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | TESTOMNIAC_API_URL | API server URL | http://localhost:8027 | | SCANNER_API_KEY | Shared secret for X-Scanner-Key auth | required | | CHROMIUM_PATH | Path to Chrome/Chromium binary | auto-detected | | PORT | Health endpoint port | 8030 | | MAX_CONCURRENT_RUNNERS | Max parallel test runs | 5 | | SCAN_POLL_INTERVAL_MS | Poll interval in ms | 10000 | | OPENAI_API_KEY | OpenAI API key for AI analysis | required for AI phase | | USER_DATA_DIR | Persistent browser profile directory | ./testomniac-browser-profile | | ARTIFACT_DIR | Screenshots/logs storage | ./testomniac-artifacts | | LOG_LEVEL | Pino log level | info | | POSTMARK_SERVER_TOKEN | Postmark API token (email reports) | optional | | POSTMARK_FROM_EMAIL | Sender email for reports | optional | | DEEP_LINK_SECRET | JWT secret for report deep links | optional | | APP_BASE_URL | Frontend URL for deep links | http://localhost:3000 | | SIGNIC_INDEXER_URL | Signic indexer for verification emails | optional | | SIGNIC_EMAIL_API_URL | Signic email API for disposable accounts | optional |

See .env.example for full documentation of each variable.

Docker

The included Dockerfile uses a multi-stage build on oven/bun:latest with system Chromium and all required libraries pre-installed. The container runs as a non-root user and includes a health check.

docker build --build-arg NPM_TOKEN=<token> -t testomniac-runner .
docker run -p 8030:8030 --env-file .env testomniac-runner

Related Projects

| Project | Description | |---------|-------------| | testomniac_runner_service | Shared execution library -- this runner calls runTestRun() from it | | testomniac_api | REST API this runner polls and reports to (default localhost:8027) | | testomniac_extension | Chrome extension that also uses runTestRun() with ChromeAdapter | | testomniac_types | Shared TypeScript type definitions | | testomniac_app | Web frontend that displays scan results | | testomniac_runner_mcp | MCP server for AI-driven browser automation (also wraps runner_service) |

License

BUSL-1.1