@cogitogroupltd/benj-qa-worker

Record UI QA journeys on your own machine.

The hosted recorder runs a browser in the cloud, which can only reach publicly-resolvable URLs. This worker runs a real browser window on your screen instead — so it can record against localhost:3000, a VPN-only staging site, or anything else your machine can see, and you can change code between takes.

Use

Get a pairing code from Pair a local worker in the web app, then:

npx -y @cogitogroupltd/benj-qa-worker@latest pair <code>

That joins this machine to your project and stays running, serving recordings. Start a recording from the web app and a browser window opens here. Ctrl-C to stop.

Already paired? npx -y @cogitogroupltd/benj-qa-worker@latest relay

Requirements

• Node 20+
• Windows, macOS or Linux. Same command on each.
• A desktop session (the point is a visible browser window — this will not work over a plain SSH shell, and a container cannot show a window on macOS or Windows). On Linux the window opens on the display you started the worker from; set QA_RECORD_DISPLAY only if you need to override that.
• On first run, Playwright downloads Chromium (~150 MB). Windows may prompt for a Defender/Firewall allowance the first time it launches.

What it sends

Recorded steps, screenshots and the journey metadata, to the API you paired with. The pairing code is single-use and expires 10 minutes after it is minted; after redeeming it, this machine holds a worker token in ~/.config/benj-qa/record-worker.json. It never holds your account credentials or the platform's service key.

Build and release (maintainers)

cd worker-cli && node build.mjs        # bundle only
pnpm release:worker --dry-run          # bundle, smoke-test, show the tarball
pnpm release:worker                    # ...and publish

build.mjs bundles src/record/worker-main.ts from the parent repo into dist/benj-qa-worker.mjs. playwright stays external — it ships platform binaries and its own browser download.

release.ts wraps that: it runs the built bin and checks it reports the version in package.json, refuses a version already on the registry, lists the tarball and fails if the bin is missing from it (that has happened), publishes, then re-reads the registry to confirm. --ignore-scripts on pack and publish keeps the bytes it inspected and the bytes it uploads the same.

From CI (preferred). The publish worker-cli workflow releases with trusted publishing — GitHub's OIDC id-token, no npm secret anywhere. release.ts detects it and skips the token path; everything else about the release is identical. Bump the version, merge, then run the workflow.

From a laptop. The token comes from NPM_TOKEN in the environment or the repo .env, is written to a 0600 .npmrc in a temp dir removed on every exit path, and is redacted from anything printed. It must be a granular token with "Bypass two-factor authentication (2FA)" ticked — that box is off by default, npm's 403 does not name it, and no other kind of token can publish unattended. npm no longer offers TOTP enrolment, so --otp <code> only helps an account with a legacy authenticator.

Both routes are on a clock: npm retires bypass-2FA publishing around January 2027, and the current token expires 2026-10-28.