@sudobility/testomniac_runner 0.0.144 → 0.0.145

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +100 -10
  2. package/bun.lock +2 -2
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -1,22 +1,112 @@
1
- # testomniac_runner
1
+ # @sudobility/testomniac_runner
2
2
 
3
- Scanner worker service for Testomniac.
3
+ 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()`.
4
4
 
5
- This project is responsible for:
6
- - polling for pending scan runs
7
- - driving browser automation and discovery
8
- - reporting progress through the shared PostgreSQL event model
9
- - exposing a lightweight `/health` endpoint for container orchestration
5
+ ## Architecture
10
6
 
11
- ## Development
7
+ 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`.
8
+
9
+ ```
10
+ Every SCAN_POLL_INTERVAL_MS (default 10s):
11
+ GET /api/v1/scanner/runs/pending
12
+ If run found -> claim it, launch browser, call runTestRun()
13
+ On completion -> PATCH /runs/:id/complete
14
+ On error -> PATCH /runs/:id/complete with failure
15
+ ```
16
+
17
+ `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.
18
+
19
+ ### Key Responsibilities
20
+
21
+ - **Polling**: Claims pending test runs from the API on a configurable interval
22
+ - **Concurrency**: Manages parallel test runs via `RunnerManager`
23
+ - **Browser**: Launches Chromium via Puppeteer-core with a persistent browser profile (`ChromiumManager`)
24
+ - **Adapter**: `PuppeteerAdapter` implements `BrowserAdapter` from `testomniac_runner_service`
25
+ - **Plugins**: SEO, Security, Content, and UI Consistency check implementations
26
+ - **Auth automation**: Form login detection, credential management, 2FA handling, and Signic disposable email registration for testing sign-up flows
27
+ - **Email reports**: Scan summaries via Postmark with deep-link JWT tokens
28
+ - **Health endpoint**: HTTP `/health` on port 8030 (Hono)
29
+
30
+ ## Setup
12
31
 
13
32
  ```bash
14
33
  bun install
15
- bun run dev
34
+ cp .env.example .env
35
+ # Fill in SCANNER_API_KEY and other values
16
36
  ```
17
37
 
18
- Default health endpoint:
38
+ ## Running
39
+
40
+ ```bash
41
+ bun run dev # Watch mode (polls for pending runs, restarts on changes)
42
+ bun run start # Production mode
43
+ ```
44
+
45
+ Health check:
19
46
 
20
47
  ```bash
21
48
  curl http://localhost:8030/health
22
49
  ```
50
+
51
+ ## Commands
52
+
53
+ | Command | Description |
54
+ |----------------------|------------------------------------|
55
+ | `bun run dev` | Start in watch mode |
56
+ | `bun run build` | Bundle with Bun |
57
+ | `bun run start` | Run production build |
58
+ | `bun run test` | Run Vitest tests |
59
+ | `bun run test:unit` | Run unit tests only |
60
+ | `bun run test:watch` | Vitest watch mode |
61
+ | `bun run typecheck` | TypeScript type check |
62
+ | `bun run lint` | ESLint |
63
+ | `bun run lint:fix` | ESLint with auto-fix |
64
+ | `bun run format` | Format with Prettier |
65
+ | `bun run verify` | typecheck + lint + test + build |
66
+
67
+ ## Environment Variables
68
+
69
+ | Variable | Description | Default |
70
+ |----------|-------------|---------|
71
+ | `TESTOMNIAC_API_URL` | API server URL | `http://localhost:8027` |
72
+ | `SCANNER_API_KEY` | Shared secret for `X-Scanner-Key` auth | **required** |
73
+ | `CHROMIUM_PATH` | Path to Chrome/Chromium binary | auto-detected |
74
+ | `PORT` | Health endpoint port | `8030` |
75
+ | `MAX_CONCURRENT_RUNNERS` | Max parallel test runs | `5` |
76
+ | `SCAN_POLL_INTERVAL_MS` | Poll interval in ms | `10000` |
77
+ | `OPENAI_API_KEY` | OpenAI API key for AI analysis | required for AI phase |
78
+ | `USER_DATA_DIR` | Persistent browser profile directory | `./testomniac-browser-profile` |
79
+ | `ARTIFACT_DIR` | Screenshots/logs storage | `./testomniac-artifacts` |
80
+ | `LOG_LEVEL` | Pino log level | `info` |
81
+ | `POSTMARK_SERVER_TOKEN` | Postmark API token (email reports) | optional |
82
+ | `POSTMARK_FROM_EMAIL` | Sender email for reports | optional |
83
+ | `DEEP_LINK_SECRET` | JWT secret for report deep links | optional |
84
+ | `APP_BASE_URL` | Frontend URL for deep links | `http://localhost:3000` |
85
+ | `SIGNIC_INDEXER_URL` | Signic indexer for verification emails | optional |
86
+ | `SIGNIC_EMAIL_API_URL` | Signic email API for disposable accounts | optional |
87
+
88
+ See `.env.example` for full documentation of each variable.
89
+
90
+ ## Docker
91
+
92
+ 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.
93
+
94
+ ```bash
95
+ docker build --build-arg NPM_TOKEN=<token> -t testomniac-runner .
96
+ docker run -p 8030:8030 --env-file .env testomniac-runner
97
+ ```
98
+
99
+ ## Related Projects
100
+
101
+ | Project | Description |
102
+ |---------|-------------|
103
+ | **testomniac_runner_service** | Shared execution library -- this runner calls `runTestRun()` from it |
104
+ | **testomniac_api** | REST API this runner polls and reports to (default `localhost:8027`) |
105
+ | **testomniac_extension** | Chrome extension that also uses `runTestRun()` with `ChromeAdapter` |
106
+ | **testomniac_types** | Shared TypeScript type definitions |
107
+ | **testomniac_app** | Web frontend that displays scan results |
108
+ | **testomniac_runner_mcp** | MCP server for AI-driven browser automation (also wraps runner_service) |
109
+
110
+ ## License
111
+
112
+ BUSL-1.1
package/bun.lock CHANGED
@@ -9,7 +9,7 @@
9
9
  "@noble/hashes": "^1.0.0",
10
10
  "@sudobility/signic_sdk": "^0.1.7",
11
11
  "@sudobility/testomniac_runner_service": "^0.1.140",
12
- "@sudobility/testomniac_types": "^0.0.73",
12
+ "@sudobility/testomniac_types": "^0.0.74",
13
13
  "hono": "^4.7.0",
14
14
  "jose": "^6.1.2",
15
15
  "openai": "^6.7.0",
@@ -174,7 +174,7 @@
174
174
 
175
175
  "@sudobility/testomniac_runner_service": ["@sudobility/testomniac_runner_service@0.1.140", "", { "peerDependencies": { "@sudobility/testomniac_types": "^0.0.73", "openai": ">=6.0.0", "react": ">=18.0.0" }, "optionalPeers": ["openai", "react"] }, "sha512-yUBfBH1e8/4/1ZyXfshdRMtJ0aJgEJJOhyc2U9DQetjs73s8dZwTWKGI/3kUP3jrStpL1x4UwlY0lz10e3Xfig=="],
176
176
 
177
- "@sudobility/testomniac_types": ["@sudobility/testomniac_types@0.0.73", "", { "peerDependencies": { "@sudobility/types": "^1.9.62" } }, "sha512-TEC+FPGji7rKYPDlFS3gY/BwSK9djkDXMxvp7tvswzYg7O/VgOev6OO4AFr799tIOSsfVt14w1vjKyW3SMz1QA=="],
177
+ "@sudobility/testomniac_types": ["@sudobility/testomniac_types@0.0.74", "", { "peerDependencies": { "@sudobility/types": "^1.9.62" } }, "sha512-F6PYBoSStBMvtg33sk4ICy3m4+l+zeTlDXC4lvA5O7U8RupyEffDYGXmJRe1JM3K56aizIjokFv6b83yUEyW+w=="],
178
178
 
179
179
  "@sudobility/types": ["@sudobility/types@1.9.61", "", {}, "sha512-SODGpstB/iKfK3H/4BvJx/FBcc1h3gutUjGotyxN19VnOfWyzaDoEmW7eyoxOAYhZyXMXagSiii+NIEZvuxKog=="],
180
180
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sudobility/testomniac_runner",
3
- "version": "0.0.144",
3
+ "version": "0.0.145",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
@@ -25,7 +25,7 @@
25
25
  "@noble/hashes": "^1.0.0",
26
26
  "@sudobility/signic_sdk": "^0.1.7",
27
27
  "@sudobility/testomniac_runner_service": "^0.1.140",
28
- "@sudobility/testomniac_types": "^0.0.73",
28
+ "@sudobility/testomniac_types": "^0.0.74",
29
29
  "hono": "^4.7.0",
30
30
  "jose": "^6.1.2",
31
31
  "openai": "^6.7.0",