> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getdecipher.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Run in Local Browser

> Execute a recorded Decipher test against a local Chromium browser using the decipher-qa CLI

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.

<Info>
  **Prerequisites:**

  * Node.js 18 or later
  * A [Decipher account](https://app.getdecipher.com) with at least one recorded test
  * The numeric test ID you want to run (visible in the URL on the test's page)
</Info>

## Step 1: Install the CLIs

You'll need two packages — the `decipher-qa` CLI and the `decipher-browser` launcher. Install both globally:

<CodeGroup>
  ```bash npm theme={null}
  npm install -g @decipher-sdk/decipher-qa @decipher-sdk/decipher-browser
  ```

  ```bash yarn theme={null}
  yarn global add @decipher-sdk/decipher-qa @decipher-sdk/decipher-browser
  ```

  ```bash pnpm theme={null}
  pnpm add -g @decipher-sdk/decipher-qa @decipher-sdk/decipher-browser
  ```

  ```bash bun theme={null}
  bun add -g @decipher-sdk/decipher-qa @decipher-sdk/decipher-browser
  ```
</CodeGroup>

<Tip>
  `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`.
</Tip>

## Step 2: Authenticate

<Steps>
  <Step title="Grab your API token">
    Copy it from [app.getdecipher.com/settings?section=api-keys](https://app.getdecipher.com/settings?section=api-keys).
  </Step>

  <Step title="Log in">
    <CodeGroup>
      ```bash CI/CD (non-interactive) theme={null}
      decipher-qa login --token $DECIPHER_API_TOKEN
      ```

      ```bash Interactive theme={null}
      decipher-qa login
      ```
    </CodeGroup>

    The token is saved to `~/.decipher/qa-config.json` — you only need to do this once per machine.
  </Step>

  <Step title="Verify">
    ```bash theme={null}
    decipher-qa whoami
    ```
  </Step>
</Steps>

## Step 3: Run a Test

The simplest invocation launches a headless Chromium, runs the test, and streams progress to your terminal:

```bash theme={null}
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.

<Note>
  Up to **20 local browsers** can run concurrently per account. Additional runs will return a `429 Too Many Requests` error — retry once a slot frees up.
</Note>

### Common flags

<CodeGroup>
  ```bash Target a preview/staging URL theme={null}
  decipher-qa test run-cdp --testId 1522 --origin http://localhost:3000
  ```

  ```bash Show the browser window theme={null}
  decipher-qa test run-cdp --testId 1522 --headful
  ```

  ```bash Use your own browser theme={null}
  decipher-qa test run-cdp --testId 1522 --cdp ws://127.0.0.1:9222/devtools/browser/<uuid>
  ```

  ```bash Verbose event stream theme={null}
  decipher-qa test run-cdp --testId 1522 --verbose
  ```
</CodeGroup>

**`--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.

<Accordion title="Example: passing run">
  ```
    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
  ```
</Accordion>

## 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](/pages/features/testing/run-locally-wrapper)** — for Node scripts, Vitest/Jest suites, or TS-based CI runners.
* **[Python Wrapper](/pages/features/testing/run-locally-python)** — for Python scripts, pytest suites, or Python-based CI runners.

## CLI Reference

### `decipher-qa test run-cdp`

| Flag             | Description                                                                                                                           |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `--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`                                  |
| `--headful`      | Show 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 |
| `--verbose`      | Print every SSE event and phase (noisy, useful for debugging the agent)                                                               |

### `decipher-browser launch`

| Flag               | Description                                  |
| ------------------ | -------------------------------------------- |
| `--headful`        | Show the Chromium window (default: headless) |
| `--viewport <WxH>` | Viewport size, e.g. `1920x1080`              |

## Troubleshooting

<AccordionGroup>
  <Accordion title="'decipher-browser: command not found'">
    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`:

    ```bash theme={null}
    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`.
  </Accordion>

  <Accordion title="Chromium fails to launch / 'executable doesn't exist'">
    `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:

    ```bash theme={null}
    npx playwright install chromium
    ```
  </Accordion>

  <Accordion title="'Not logged in' / 401 errors">
    Your token may be expired or missing. Re-authenticate:

    ```bash theme={null}
    decipher-qa login
    ```

    Grab a fresh token from [app.getdecipher.com/settings?section=api-keys](https://app.getdecipher.com/settings?section=api-keys).
  </Accordion>

  <Accordion title="'--cdp must be a ws:// or wss:// URL'">
    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.
  </Accordion>

  <Accordion title="Test run starts but exits without a runId">
    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.
  </Accordion>
</AccordionGroup>

***

*Need help? [Contact our support team](mailto:team@getdecipher.com).*