Test Conventions

What It Does

Reference conventions for the yellow-browser-test plugin's testing workflow.
Defines the config schema, report format, severity levels, and safety rules.

When to Use

Use when yellow-browser-test commands or agents need the config schema, severity
classification, or credential handling rules.

Usage

This skill is not user-invocable. It provides shared context for the
yellow-browser-test plugin.

Config Schema

Config is stored at .claude/yellow-browser-test.local.md as YAML frontmatter +
markdown notes.

---
schema: 1
generated: '2026-02-13T10:30:00Z'
devServer:
  command: 'npm run dev'
  port: 3000
  baseURL: 'http://localhost:3000'
  readyTimeout: 60
  readyPath: '/'
auth:
  type: 'email-password'
  loginPath: '/login'
  credentials:
    email: '$BROWSER_TEST_EMAIL'
    password: '$BROWSER_TEST_PASSWORD'
  formFields:
    email: 'email'
    password: 'password'
routes:
  - path: '/dashboard'
    name: 'Dashboard'
    auth: true
---

Required fields: schema, devServer.command, devServer.baseURL

Severity Classification

Severity	Criteria	Example
critical	App crashes, data loss, security hole	Unhandled exception on form submit
major	Feature broken, console error, blank section	Settings page renders empty
minor	Slow load, UI glitch, non-blocking error	Button misaligned, 5s load time
cosmetic	Visual imperfection, typo	Font inconsistency, extra whitespace

Credential Handling Rules

1. Never store actual credentials — config references env var NAMES only
   ($BROWSER_TEST_EMAIL)
2. Auth state file — .claude/browser-test-auth.json must be gitignored
3. Missing vars — If env vars are not set, error with: "Set {VAR_NAME} in
   your environment or .env.local"
4. PID file — .claude/browser-test-server.pid must be gitignored
5. Env var naming — Use BROWSER_TEST_* prefix for all test credentials
   (e.g., BROWSER_TEST_EMAIL, BROWSER_TEST_PASSWORD)
6. Never log credentials — Mask credential values in reports with ***
7. Auth state expiry — If tests fail with auth errors, delete
   .claude/browser-test-auth.json and re-run setup to refresh auth state

Safe Exploration Rules

During autonomous exploration, the test-runner agent MUST:

1. Follow safety rules from agent-browser-patterns skill
2. Limit depth — Max 3 levels from starting page
3. Limit time — Max 10 minutes per exploration session
4. Save incrementally — Write partial results every 5 routes to prevent data
   loss

Report Template

Reports are written to test-reports/YYYY-MM-DD-HH-MM.md. This is the
canonical template — test-reporter follows it verbatim (GitHub issue creation
flow lives in the test-reporter agent):

# Browser Test Report — {YYYY-MM-DD HH:MM}

- **Mode:** structured | exploratory
- **Base URL:** {baseURL}
- **Duration:** {Xm Ys}
- **Results:** {passed} passed / {failed} failed / {skipped} skipped

## Summary

| Route | Status | Severity | Notes |
|-------|--------|----------|-------|
| /     | pass   | —        |       |

## Failures

### {route} — {one-line description}

- **Severity:** critical | major | minor
- **Screenshot:** `screenshots/{slug}.png`
- **Repro steps:**
  1. {step}
- **Observed:** {what happened}
- **Expected:** {what should happen}

## Warnings

- {skipped routes and non-critical observations, one bullet each}

Security: ALWAYS use AskUserQuestion before creating GitHub issues. Never
auto-create. Warn that screenshots may contain sensitive data.