manual-tester

A manual testing skill for AI coding tools. Uses a checkpoint architecture to prevent context limit exhaustion during long browser test runs.

The Problem

Manual testing in AI cowork sessions hits context limits quickly. Every browser interaction — screenshots, DOM snapshots, network logs — adds 10,000–50,000 tokens. After 10 steps, the session is saturated.

The Solution

Every test step runs inside an isolated subagent. The subagent handles all browser interactions in its own disposable context and returns only a compact checkpoint summary (~100 tokens) to the main session. A 50-step test run uses ~5K tokens in the main context instead of 500K+.

Installation

Via npx (recommended)

npx @zinokhedri/manual-tester

Automatically detects and installs to all supported tools found on your machine.

Via npm (global)

npm install -g @zinokhedri/manual-tester
manual-tester

Supported Tools

| Tool | Install location | |------|-----------------| | Claude Code | ~/.claude/skills/manual-tester/ | | Cursor | ~/.cursor/rules/manual-tester.mdc | | Windsurf | ~/.codeium/windsurf/memories/manual-tester.md | | GitHub Copilot | .github/copilot-instructions.md (project-level) |

Restart your AI tool after installation to activate the skill.

Usage

/manual-tester                        Full interactive intake
/manual-tester https://myapp.com      Skip URL question
/manual-tester --report               Regenerate report from existing checkpoints
/manual-tester --rerun                Re-run only FAIL/BLOCKED steps

How It Works

Phases

| Phase | What happens | Output | |-------|-------------|--------| | 0. Intake | URL, flows to test, credentials, final delivery method | — | | 1. Plan | Auto-generates numbered test steps, user confirms before running | TEST_PLAN.md | | 2. Execute | Each step runs in an isolated subagent via the Agent tool | CHECKPOINTS.md + screenshots | | 3. Report | Compiles results, delivers via chosen method | TEST_REPORT.md |

Output Structure

Each run creates a timestamped directory in your current working directory:

test-results/<ISO-timestamp>/
├── TEST_PLAN.md          # Confirmed test plan
├── CHECKPOINTS.md        # Live checkpoint log
├── TEST_REPORT.md        # Final report with pass/fail summary
└── screenshots/
    ├── step-1-before.png
    ├── step-1-after.png
    └── ...

Final Delivery Options

• Save to file — TEST_REPORT.md written to the results directory
• Email — Drafted and sent via Gmail MCP
• Slack — Summary posted to a channel via Slack MCP
• Inline — Report printed in the conversation

File Structure

manual-tester/
├── package.json
├── LICENSE
├── README.md
├── SKILL.md                          # Main skill definition
├── bin/
│   └── install.js                    # npx install script
├── .claude-plugin/
│   └── plugin.json                   # Claude Code plugin manifest (alternative install)
├── agents/
│   └── step-executor.md              # Isolated subagent prompt for one test step
├── references/
│   ├── intake-questions.md           # Intake question set
│   ├── checkpoint-format.md          # CHECKPOINTS.md column spec
│   └── test-plan-format.md           # TEST_PLAN.md row format
└── templates/
    ├── TEST_PLAN.md
    ├── CHECKPOINTS.md
    └── TEST_REPORT.md

Publishing to npm

cd skills/manual-tester
npm publish --access public

Users can then install with:

npx @zinokhedri/manual-tester

License

MIT