# The CDP runner — `/testing run <name>`

Run a markdown UI test against the running app through Claude-in-Chrome browser automation, and record each assertion's outcome in a results file.

## Prerequisites

Complete these steps before executing any assertion.

### 1. Load credentials

Read `tests/.env`:

| Variable | Use |
| --- | --- |
| `TEST_USER_EMAIL` / `TEST_USER_PASSWORD` | Login credentials for browser setup |
| `TEST_BASE_URL` | The root URL the browser opens, e.g. `http://localhost:3000` |
| `TEST_APP_ID` *(optional)* | The app or workspace instance a test targets; unset, tests run against the default one the base URL serves |

If `tests/.env` is missing, stop and tell the user to copy `tests/.env.example` to `tests/.env`.

### 2. Connect to Chrome

Call `mcp__claude-in-chrome__tabs_context_mcp` with `createIfEmpty: true`. If the connection fails, stop and tell the user to install the Claude-in-Chrome extension and start Chrome.

### 3. Set up the browser

Open a tab with `mcp__claude-in-chrome__tabs_create_mcp`, navigate to `${TEST_BASE_URL}`, and log in with the step 1 credentials if the app asks.

### 4. Verify ready state

**Never** run an assertion until the main dashboard is visible.

## Execution

1. Locate the test file at `docs/tests/<test-name>.md` (under the repository's docs root).
2. If it is not there, list the tests in `docs/tests/`. If that directory does not exist, find how the repo runs its tests: search for `*.test.*`, `*.spec.*`, and `__tests__/`, `test/`, `tests/` directories, and check `package.json` for a `test` script.
3. Create the results file at `tests/claude-runs/<test-name>-<YYYY-MM-DD-HHmmss>.md`.
4. Execute the assertions in order, updating each checkbox as you go.
5. Save the completed results file with the summary header from § Results template.

## Checkbox markers

| Marker | Meaning |
| --- | --- |
| `[x]` | Passed |
| `[!]` | Failed — add `**FAILED**: <reason>` |
| `[-]` | Skipped |
| `[ ]` | Not run |

## Results template

```markdown
# Test Results: <Test Name>

## Execution Summary

| Property    | Value                           |
| ----------- | ------------------------------- |
| Test File   | `<path>`                        |
| Executed At | `<YYYY-MM-DD HH:mm:ss>`         |
| Status      | `PASSED` / `FAILED` / `PARTIAL` |

## Results Overview

| Metric           | Count |
| ---------------- | ----- |
| Total Assertions | X     |
| Passed           | X     |
| Failed           | X     |
| Skipped          | X     |

## Failed Assertions Summary

- Section X.X: <failure description>

---

## Test: <Original Title>

... (test content with updated checkboxes)
```

## Error handling

| Error | Action |
| --- | --- |
| Network error | Retry once, then mark failed |
| Timeout | Mark failed with a timeout note |
| Element not found | Screenshot, mark failed, continue |
| Browser disconnect | Stop, save partial results, tell the user |

## Screenshots

Take a screenshot before each major section, on every failure, and after completion.