---
name: test
description: Test Runner using Chrome DevTools Protocol (CDP). Run UI tests with Claude-in-Chrome browser automation. Triggers include: "run my tests", "run the test suite", "execute tests", "test this code", "check if tests pass".
argument-hint: [test-name]
---

# Test Runner (CDP)

Run UI tests using Claude-in-Chrome browser automation.

## Prerequisites

Complete these steps before executing test assertions:

### 1. Load Credentials

Read `tests/.env` for: `TEST_USER_EMAIL`, `TEST_USER_PASSWORD`, `TEST_BASE_URL`, `TEST_APP_ID`

- `TEST_USER_EMAIL` / `TEST_USER_PASSWORD`: credentials used to log in during browser setup.
- `TEST_BASE_URL`: the root URL the browser will navigate to (e.g. `http://localhost:3000`).
- `TEST_APP_ID` _(optional)_: an application or workspace identifier passed to tests that need to target a specific app instance. When unset, tests run against the default app/workspace returned by the base URL.

If the file is missing, instruct user to copy `tests/.env.example` to `tests/.env`.

### 2. Connect to Chrome

```
mcp__claude-in-chrome__tabs_context_mcp with createIfEmpty: true
```

If connection fails: Install Claude-in-Chrome extension, ensure Chrome is running.

### 3. Setup Browser

```
mcp__claude-in-chrome__tabs_create_mcp
```

Navigate to `${TEST_BASE_URL}`. Login if required using credentials from step 1.

### 4. Verify Ready State

Confirm main dashboard is visible before proceeding.

## Execution

1. **Locate test file**: `.github/docs/tests/<test-name>.md`
2. **Validate exists**: If not found, list available tests in `.github/docs/tests/`. If that directory does not exist, search for common test patterns: `*.test.*`, `*.spec.*`, `__tests__/`, `test/`, `tests/` directories, or check `package.json` for a `test` script to determine how tests should be run.
3. **Create results file**: `tests/claude-runs/<test-name>-<YYYY-MM-DD-HHmmss>.md`
4. **Execute sequentially**: Update checkboxes as you go
5. **Save results**: Write completed file with summary header

## 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

- **Network errors**: Retry once, then mark failed
- **Timeout**: Mark failed with timeout note
- **Element not found**: Screenshot, mark failed, continue
- **Browser disconnect**: Stop, save partial results, inform user

## Screenshots

Take screenshots: before each major section, on failures, after completion.