---
name: browser-interactive-testing
description: >
  This skill should be used when the user asks to "test a web page",
  "take a screenshot of a site", "automate browser interaction",
  "create a test report", "verify a page works", or mentions
  rodney, showboat, headless Chrome testing, or browser automation.
version: 0.1.0
---

# Browser Interactive Testing

Test web pages interactively using **rodney** (headless Chrome automation) and document results with **showboat** (executable demo reports).

## Prerequisites

Ensure `uv` is installed. If missing, instruct the user to run:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Do NOT install rodney or showboat globally. Run them via `uvx`:

```bash
uvx rodney <command>
uvx showboat <command>
```

## Rodney Quick Reference

### Start a browser session

```bash
uvx rodney start            # Launch headless Chrome
uvx rodney start --show     # Launch visible browser (for debugging)
uvx rodney connect host:port # Connect to existing Chrome with remote debugging
```

Use `--local` on all commands to scope the session to the current directory.

### Navigate and inspect

```bash
uvx rodney open "https://example.com"
uvx rodney waitload
uvx rodney title
uvx rodney url
uvx rodney text "h1"
uvx rodney html "#content"
```

### Interact with elements

```bash
uvx rodney click "#submit-btn"
uvx rodney input "#email" "user@example.com"
uvx rodney select "#country" "US"
uvx rodney js "document.querySelector('#app').dataset.ready"
```

### Assert and verify

```bash
uvx rodney assert "document.title" "My App" -m "Title must match"
uvx rodney exists ".error-banner"
uvx rodney visible "#loading-spinner"
uvx rodney count ".list-item"
```

Exit code `0` = pass, `1` = fail, `2` = error.

### Screenshots and cleanup

```bash
uvx rodney screenshot -w 1280 -h 720 page.png
uvx rodney screenshot-el "#chart" chart.png
uvx rodney stop
```

Run `uvx rodney --help` for the full command list, including tab management, navigation, waiting, accessibility tree inspection, and PDF export.

## Showboat Quick Reference

```bash
uvx showboat init report.md "Test Report Title"
uvx showboat note report.md "Description of what we are testing."
uvx showboat exec report.md bash "uvx rodney title --local"
uvx showboat image report.md '![Page screenshot](screenshot.png)'
uvx showboat pop report.md          # Remove last entry (fix mistakes)
uvx showboat verify report.md       # Re-run all code blocks and diff
uvx showboat extract report.md      # Print commands that recreate the document
```

Run `uvx showboat --help` for details on `--workdir`, `--output`, `--filename`, and stdin piping.

## Output Directory

Save all reports under `.agent-tests/` in the project root:

```
.agent-tests/
└── YYYY-MM-DD-<slug>/
    ├── report.md
    └── screenshots/
```

Derive the slug from the test subject (e.g., `login-flow`, `homepage-layout`). Keep it lowercase, hyphen-separated, max ~30 chars. If a directory with the same date and slug already exists, append a numeric suffix (e.g., `tetris-game-2`) or choose a more specific slug (e.g., `tetris-controls` instead of reusing `tetris-game`).

### Setup Script

Run the bundled `scripts/setup.py` to create the directory, init the report, start the browser, and capture `DIR` in one step. Replace `<SKILL_DIR>` with the actual path to the directory containing this skill's files:

```bash
DIR=$(python3 <SKILL_DIR>/scripts/setup.py "<slug>" "<Report Title>")
```

This single command:
1. Creates `.agent-tests/YYYY-MM-DD-<slug>/screenshots/`
2. Adds `.rodney/` to `.gitignore` (if `.gitignore` exists)
3. Runs `showboat init` for the report
4. Starts a browser (connects to existing, launches system Chrome/Chromium, or falls back to rodney's built-in launcher)
5. Prints the directory path to stdout (all status messages go to stderr)

After setup, `$DIR` is ready for use with all subsequent commands.

**Important:** The `--local` flag stores session data in `.rodney/` relative to the current working directory. Do NOT `cd` to a different directory during the session, or rodney will lose the connection. Use absolute paths for file arguments instead.

## Workflow

1. **Setup** — Run the setup script to create the dir, init the report, start the browser, and set `$DIR`
2. **Describe the test** — `uvx showboat note "$DIR/report.md" "Testing [subject] for [goals]."` so the report has context up front
3. **Open page** — `uvx showboat exec "$DIR/report.md" bash "uvx rodney open --local 'URL' && uvx rodney waitload --local"`
4. **Add a note** before each test group — Use a heading followed by a short explanation of what the tests in this section verify and why it matters. Use unique section titles; avoid duplicating headings within the same report.
   ```bash
   uvx showboat note "$DIR/report.md" "## Keyboard Controls"
   uvx showboat note "$DIR/report.md" "Verify arrow keys move and rotate the active piece, and that soft/hard drop work correctly."
   ```
5. **Run assertions** — Before each assertion, add a short `showboat note` explaining what it checks. Then wrap the `rodney assert` / `rodney js` call in `showboat exec`:
   ```bash
   uvx showboat note "$DIR/report.md" "The left arrow key should move the piece one cell to the left."
   uvx showboat exec "$DIR/report.md" bash "uvx rodney assert --local '...' '...' -m 'Piece moved left'"
   ```
6. **Capture screenshots** — Take the screenshot with `rodney screenshot`, then embed with `showboat image`. **Important:** `showboat image` resolves image paths relative to the current working directory, NOT relative to the report file. Always use absolute paths (`$DIR/screenshots/...`) in the markdown image reference to avoid "image file not found" errors:
   ```bash
   uvx rodney screenshot --local -w 1280 -h 720 "$DIR/screenshots/01-initial-load.png"
   uvx showboat image "$DIR/report.md" "![Initial load]($DIR/screenshots/01-initial-load.png)"
   ```
   Number screenshots sequentially (`01-`, `02-`, ...) and use descriptive filenames.
7. **Pop on failure** — If a command fails, run `showboat pop` then retry
8. **Stop browser** — `uvx rodney stop --local`
9. **Write summary** — Add a final `showboat note` with a summary section listing all pass/fail results and any bugs found. Every report must end with a summary.
10. **Verify report** — `uvx showboat verify "$DIR/report.md"`

### Best Practices

- Use `uvx rodney waitload` or `uvx rodney wait <selector>` before interacting with page content.
- Run `uvx showboat pop` immediately after a failed `exec` to keep the report clean.
- Prefer `rodney assert` for checks — clear exit codes and self-documenting output.
- Use `rodney js` only for complex checks or state manipulation that `assert` cannot express.
- Take screenshots at key stages (initial load, after interaction, error states) for visual evidence.
- Add a `showboat note` before each logical group of tests with a heading and a short explanation of what the section tests. Use unique heading titles — duplicate headings make the report confusing.
- Always end reports with a summary `showboat note` listing pass/fail results and any bugs found. This is required, not optional.

## Quoting Rules for `rodney js`

`rodney js` evaluates a single JS **expression** (not statements). Nested shell quoting with `showboat exec` causes most errors. Follow these rules strictly:

1. **Wrap multi-statement JS in an IIFE** — bare `const`, `let`, `for` fail at top level:
   ```bash
   # WRONG
   uvx rodney js --local 'const x = 1; x + 2'
   # CORRECT
   uvx rodney js --local '(function(){ var x = 1; return x + 2; })()'
   ```

2. **Use `var` instead of `const`/`let`** inside IIFEs to avoid strict-mode eval scoping issues.

3. **Direct `rodney js` calls** — use single quotes for the outer shell, double quotes inside JS:
   ```bash
   uvx rodney js --local '(function(){ var el = document.querySelector("#app"); return el.textContent; })()'
   ```

4. **Inside `showboat exec`** — use a heredoc with a **quoted delimiter** (`<<'JSEOF'`) to prevent all shell expansion (`$`, backticks, etc.):
   ```bash
   uvx showboat exec "$DIR/report.md" bash "$(cat <<'JSEOF'
   uvx rodney js --local '
   (function(){
     var x = score;
     hardDrop();
     return "before:" + x + ",after:" + score;
   })()
   '
   JSEOF
   )"
   ```
   For simple one-liners, single quotes inside the double-quoted bash arg also work:
   ```bash
   uvx showboat exec "$DIR/report.md" bash "uvx rodney js --local '(function(){ return String(score); })()'"
   ```

5. **Avoid without heredoc**: backticks, `$` signs, unescaped double quotes. The heredoc pattern avoids all of these.

6. **Prefer `rodney assert` over `rodney js`** when possible — separate arguments avoid quoting entirely.

7. **Pop after syntax errors** — always `showboat pop` before retrying to keep the report clean.