Requirement-driven test design CLI for AI-assisted QA workflows.
TestSpec is a CLI tool that helps QA teams create, manage, and track test artifacts through a structured workflow. It integrates with AI-powered agents like Claude Code, Qoder, Codex, and Trae to streamline the testing process.
- Structured Workflow: Follow a proven test design process from requirements to test cases
- AI Integration: Works with Claude Code, Qoder, Codex, Trae, and other AI agents
- Excel Export: Generate executable test cases with functional and performance worksheets
- Mind Map Export: Create visual test case maps for review and collaboration
- Traceability: Maintain links between requirements, test points, and test cases
- Archive System: Organize and preserve completed test cycles
npm install -g @wangjh2001/testspecOr use npx without installation:
npx @wangjh2001/testspec init
npx @wangjh2001/testspec new <test-name> --requirement <path>testspec initThis sets up the TestSpec workspace and configures AI agent integrations. By default, the interactive selection starts with Claude Code and Qoder selected. Use Space to select/deselect integrations and Enter to confirm. Before regenerating selected agent command files, init removes stale TestSpec-generated command files in the selected .claude/commands/test/, .qoder/commands/test/, or .trae/commands/test/ directories that still contain the generated marker; custom command files without the marker are preserved. Command files with the generated marker are treated as TestSpec-managed and may be deleted/recreated by testspec init.
Available integrations:
| Agent | Output |
|---|---|
| Claude Code | .claude/commands/test/*.md for /test:* slash commands |
| Codex | AGENTS.md guidance mapping test:* labels to CLI commands |
| Qoder | .qoder/commands/test/*.md for the same workflow labels |
| Trae | .trae/commands/test/*.md for the same workflow labels |
| Generic | Tool-agnostic AGENTS.md workflow guidance |
For non-interactive setup:
testspec init --agents claude,qoder
# or all integrations
testspec init --agents alltestspec new login-v2 --requirement docs/login-prd.md --object "Login service"This creates a new test change directory with a proposal template. --requirement accepts a local path or URL, --object records the tested object name, and --force overwrites an existing workspace.
For requirement-grounded generation, run the test:* labels inside Claude Code, Codex, Qoder, Trae, or another configured coding agent. The agent reads the requirement document and writes semantic artifacts; the CLI remains provider-free and handles validation, export, reporting, and archive.
/test:analysis login-v2
/test:points login-v2
/test:excel login-v2
CLI commands such as testspec analysis and testspec points remain deterministic fallback/template helpers when no agent is available.
# Fallback/template requirement analysis
testspec analysis login-v2
# Fallback/template test points
testspec points login-v2
# Validate generated artifacts before export
testspec validate login-v2
# Export test cases to Excel
testspec excel login-v2
# Export mind map for review
testspec mind login-v2
# Generate report (after filling execution results in Excel)
testspec report login-v2
# Archive completed test cycle
testspec archive login-v2| CLI command | Workflow label | Slash command | Description |
|---|---|---|---|
| `testspec init [--agents <ids | all>] [--force]` | — | — |
testspec new <name> [--requirement <path>] [--object <name>] [--force] |
test:new |
/test:new |
Create a test proposal workspace from a requirement document |
testspec analysis [name] |
test:analysis |
/test:analysis |
Decompose requirements into testable items, risks, and questions |
testspec points [name] |
test:points |
/test:points |
Generate fallback/template test points for a test change |
testspec validate [name] |
test:validate |
/test:validate |
Validate generated artifacts for schema, traceability, and quality |
testspec excel [name] |
test:excel |
/test:excel |
Export executable Excel test cases |
testspec mind [name] |
test:mind |
/test:mind |
Export mind-map style test cases for review |
testspec report [name] |
test:report |
/test:report |
Generate execution statistics from Excel results |
testspec archive [name] |
test:archive |
/test:archive |
Archive the full test artifact chain for traceability |
testspec --help |
— | — | Display help information |
testspec --version |
— | — | Display version |
--agents accepts claude, codex, qoder, trae, generic, or all; multiple agent IDs are comma-separated, for example --agents claude,qoder,trae. Use --force with testspec init to refresh existing TestSpec-generated agent command files, or with testspec new to overwrite an existing test change workspace.
When a command accepts [name], TestSpec uses the explicit name if provided. If omitted, it infers the only active change; when multiple exist, it asks you to specify the change name.
testspec excel [name] exports artifacts/<name>_cases.xlsx with two worksheets:
| Worksheet | Purpose |
|---|---|
功能测试 |
Minimal functional test cases with steps, expected results, priority, and execution status |
性能测试 |
Compact performance scenarios with baseline targets, metrics, and execution status |
The Excel workbook is execution-oriented. Compact artifacts/testcases.json uses exactly the executable schema title, module, type, priority, preconditions, steps, and expectedResult; the CLI normalizes generated cases to that schema before validation and export.
The performance worksheet is generated from deterministic rules:
- Core flows → load-test scenarios
- Query/search/list/report flows → query performance scenarios
- Submit/create/update/delete/order/payment flows → transaction or pressure-test scenarios
- Batch/import/export/upload/download flows → capacity or stability scenarios
- Dependency/callback/message/queue flows → stability scenarios
Unknown business targets (concurrency, target TPS/QPS) remain 待确认 until specified.
After initialization and creating test changes, your project will have:
your-project/
├── .claude/commands/test/ # Claude Code slash commands (if selected)
├── .qoder/commands/test/ # Qoder commands (if selected)
├── .trae/commands/test/ # Trae commands (if selected)
├── AGENTS.md # Codex or generic agent guidance (if selected)
└── testspec/
├── changes/
│ ├── login-v2/ # Active test change
│ │ ├── proposal.md # Test proposal
│ │ ├── requirements-analysis.md # Requirement decomposition
│ │ ├── specs/
│ │ │ └── testpoints.md # Test points
│ │ ├── artifacts/
│ │ │ ├── testcases.json # Generated test cases
│ │ │ ├── performance-cases.json
│ │ │ ├── login-v2_cases.xlsx # Excel export
│ │ │ └── login-v2_cases.xmind # Mind map export
│ │ └── report.md # Execution report
│ └── archive/
│ └── 2026-06-04-login-v2/ # Archived change
│ ├── manifest.json
│ └── ...archived artifacts...
└── ...
After testspec init, AI agents can use workflow labels directly:
Claude Code:
/test:new login-v2 --requirement docs/login-prd.md
/test:analysis login-v2
/test:points login-v2
/test:validate login-v2
/test:excel login-v2
/test:mind login-v2
/test:report login-v2
/test:archive login-v2
Qoder / Trae:
Use the same /test:* workflow labels from .qoder/commands/test/*.md or .trae/commands/test/*.md. These command files include the brief instruction, user arguments, and provider-neutral prompt-pack rules in the command body.
Codex / Generic Agents:
Read AGENTS.md for the same provider-neutral prompt-pack rules. Semantic labels such as test:analysis, test:points, and test:excel should read requirement evidence and generate artifacts before running deterministic CLI validation/export commands.
The test:* labels are Agent workflow labels, not shell commands.
- The agent must read
proposal.mdand the referenced requirement document before semantic generation. - If a requirement file is missing, remote, unreadable, or ambiguous, the agent must ask for readable content or explicit authorization instead of guessing.
- Generated requirements and test points should cite source evidence with document, section, and short quote when available; compact cases should stay executable and use the documented compact schema.
- Unknown business rules, roles, state transitions, limits, and SLA values should be marked
待确认or added as clarification questions. - Run
testspec validate [name]before export and fix blocking validation errors.
Good case steps are concrete and observable:
1. Log in as user-a.
2. Open the login page.
3. Enter username=user-a and password=ValidPass123.
4. Click Login.
5. Verify the home page shows user-a as logged in.
Avoid generic template steps:
1. Prepare test data.
2. Execute the operation.
3. Verify the system meets requirements.
# Install dependencies
npm install
# Run in development mode
npm run dev -- --help
# Build the CLI
npm run build
# Run checks
npm run typecheck
npm run test
npm run checkMIT