Skip to main content
Under the hood, decipher-qa test run-cdp connects to a Chrome DevTools Protocol (CDP) endpoint — either a Chromium instance it launches for you via decipher-browser, or an external browser you point it at.
Prerequisites:
  • Node.js 18 or later
  • A Decipher account with at least one recorded test
  • The numeric test ID you want to run (visible in the URL on the test’s page)

​
Step 1: Install the CLIs

You’ll need two packages — the decipher-qa CLI and the decipher-browser launcher. Install both globally: 
npm install -g @decipher-sdk/decipher-qa @decipher-sdk/decipher-browser
decipher-browser downloads Chromium via Playwright on install, so the first install can take a minute. If the download is skipped by your package manager, you can run it manually with npx playwright install chromium.

​
Step 2: Authenticate

1

Grab your API token

Copy it from app.getdecipher.com/settings?tab=general.
2

Log in

decipher-qa login --token $DECIPHER_API_TOKEN
The token is saved to ~/.decipher/qa-config.json — you only need to do this once per machine.
3

Verify

decipher-qa whoami

​
Step 3: Run a Test

The simplest invocation launches a headless Chromium, runs the test, and streams progress to your terminal: 
decipher-qa test run-cdp --testId 1522
Replace 1522 with your own test ID. The CLI exits 0 on pass and 1 on fail, so it drops straight into CI scripts.

​
Common flags

decipher-qa test run-cdp --testId 1522 --origin http://localhost:3000
--cdp — accepts any ws:// or wss:// CDP endpoint. Launch Chrome with --remote-debugging-port=9222 or use Playwright/Puppeteer to expose one. Omit this flag and the CLI spawns decipher-browser launch for you, reads its CDP URL from stdout, and cleans up on exit. --origin — redirects your test at a different environment (prod, staging, localhost) without re-recording.
  • Rewrites goto steps and the identity login URL whose origin matches the test’s primary origin (the first goto in the recording).
  • Path, query, and hash are preserved.
  • Third-party hosts (e.g. auth redirects) are left alone.

​
Sample Output

Each step prints its description, a ✓ (or ✗) marker, and the footer gives you a quick pass/fail verdict plus total elapsed wall-clock time. 
  Step 1: Log in as john@doe.com
    ✓ step passed

  Step 2: http://localhost:3003
    ✓ step passed

  Step 3: Click the theme toggle button in the top-left of the sidebar
    ✓ step passed

  Step 4: Click "Dark" from the dropdown menu
    ✓ step passed

  Step 5: The page background has changed to a dark color scheme
    ✓ step passed

  Step 6: Dark mode is active, indicated by a dark background and light text
    ✓ step passed

  Step 7: Click the theme toggle button in the sidebar
    ✓ step passed

  Step 8: Click "Light" from the dropdown menu
    ✓ step passed

  Step 9: The page background has changed to a light color scheme
    ✓ step passed

  ----------------------------------------------
  PASSED  · 9 steps · 127s

​
Running Programmatically

Need to call this from a script, test suite, or custom CI runner? Both wrappers spawn the CLI and return a typed { status, duration, runId, runUrl } result:
  • TypeScript Wrapper — for Node scripts, Vitest/Jest suites, or TS-based CI runners.
  • Python Wrapper — for Python scripts, pytest suites, or Python-based CI runners.

​
CLI Reference

​
decipher-qa test run-cdp

FlagDescription
--testId <id>Required. Positive integer test ID
--cdp <url>CDP websocket URL (ws:// or wss://). Omit to auto-launch a local Chromium via decipher-browser
--headfulShow the local Chromium window. Only applies when --cdp is omitted
--origin <url>Override origin for goto steps and the identity login URL whose origin matches the test’s primary origin. Path/query/hash preserved
--verbosePrint every SSE event and phase (noisy, useful for debugging the agent)

​
decipher-browser launch

FlagDescription
--headfulShow the Chromium window (default: headless)
--viewport <WxH>Viewport size, e.g. 1920x1080

​
Troubleshooting

The global install didn’t put the binary on your PATH. Reinstall globally and confirm your package manager’s global bin directory is on PATH:
npm install -g @decipher-sdk/decipher-browser
npm root -g          # shows where globals live
decipher-browser --help
On macOS/Linux, make sure $(npm root -g)/../bin is in your PATH.
decipher-browser relies on Playwright’s Chromium download. If the postinstall hook was skipped (common with --ignore-scripts or some CI caches), install it manually:
npx playwright install chromium
Your token may be expired or missing. Re-authenticate:
decipher-qa login
Grab a fresh token from app.getdecipher.com/settings?tab=general.
The CLI validates the CDP URL up front. Some browsers expose an http://localhost:9222/json/version endpoint whose webSocketDebuggerUrl field contains the actual ws:// URL you want to pass in.
This almost always means the CLI crashed before it could talk to our API. Re-run with --verbose to see the raw event stream, and double-check that decipher-qa whoami still succeeds.
Need help? Contact our support team.