test

name	test
description	Runs project test suite with coverage, auto-detects framework (pytest, vitest, jest, flutter, go, cargo, phpunit). Triggers: run tests, test suite, coverage report.
effort	medium
disable-model-invocation	true
argument-hint	[file or pattern]
allowed-tools	Bash, Read, Grep
hooks	{"PostToolUse":[{"matcher":"Bash","hooks":[{"type":"command","command":"echo 'Reminder: check test coverage meets threshold (>70%)'"}]}]}

Test Runner

$ARGUMENTS

Run tests based on detected project type.

Project context

• Project config: !cat package.json 2>/dev/null || cat pyproject.toml 2>/dev/null || cat pubspec.yaml 2>/dev/null || echo "unknown"

Auto-Detection

Run the bundled script to detect test framework:

python3 ${CLAUDE_SKILL_DIR}/scripts/detect-runner.py .

File Found	Runner	Command
pyproject.toml / setup.py	pytest	pytest --cov=src --cov-report=term-missing tests/
package.json (vitest)	vitest	npx vitest run --coverage
package.json (jest)	jest	npx jest --coverage
pubspec.yaml	flutter test	flutter test --coverage
go.mod	go test	go test -cover ./...
Cargo.toml	cargo test	cargo test
composer.json	phpunit	./vendor/bin/phpunit --coverage-text

Usage

/test                        # Run all tests
/test path/to/test_file      # Run specific test file
/test -k "test_name"         # Run tests matching pattern
/test --coverage             # Run with coverage report

Common Options by Runner

Python (pytest)

pytest tests/                          # All tests
pytest tests/unit/test_example.py      # Specific file
pytest -k "test_search"               # Pattern match
pytest --lf                            # Last failed only
pytest -v                              # Verbose

JavaScript/TypeScript (vitest/jest)

npx vitest run                         # All tests
npx vitest run src/utils.test.ts       # Specific file
npx vitest run --reporter=verbose      # Verbose
npx jest --testPathPattern=utils       # Pattern match

PHP (phpunit)

./vendor/bin/phpunit                   # All tests
./vendor/bin/phpunit tests/Unit/ExampleTest.php  # Specific
./vendor/bin/phpunit --filter testName # Pattern match

Flutter/Dart

flutter test                           # All tests
flutter test test/widget_test.dart     # Specific file
dart test --name="pattern"             # Pattern match

Go

go test ./...                          # All tests
go test ./pkg/utils/                   # Specific package
go test -run TestName ./...            # Pattern match
go test -v ./...                       # Verbose

Coverage Targets

• Overall: >70%
• Core modules: >80%
• New code: 100% (for PRs)

Test Structure Convention

tests/               # or test/, spec/, __tests__/
├── unit/            # Fast, isolated tests
├── integration/     # Tests with external dependencies
└── e2e/             # End-to-end tests

Rules

• MUST detect the framework automatically via detect-runner.py — do not assume
• NEVER modify tests to make them pass
• CRITICAL: coverage reporting must use the project's configured tool (--cov=src, --coverage, etc.) — do not invent flags
• MANDATORY: when a test fails, report the failure exactly; do not paraphrase

Gotchas

• pytest --cov=src inflates coverage when tests/ lives under src/ — test files count toward covered lines. Either move tests/ out, or use --cov=src --cov-branch --cov-report=term-missing with an explicit [tool.coverage.run] omit = ["tests/*"] in pyproject.toml.
• go test ./... runs packages in parallel by default; a test depending on shared global state may pass alone and fail in the suite. If flakiness appears only under ./..., suspect shared state, not a bug in the test.
• flutter test without an emulator falls back to the headless "null platform" — widget tests that require a render surface are silently skipped. CI without a display must add flutter test --platform vm or a virtual framebuffer.
• vitest run and jest interpret glob patterns differently: *.test.ts in vitest matches filenames, in jest matches paths. Passing the same CLI arg to both produces different test sets — use the framework-native config file when possible.
• pytest --lf (last-failed) silently runs all tests if there is no cache from a prior run. First-time runs in CI therefore ignore --lf and re-run everything, which can hide "only failed tests" bugs in local runs.

When NOT to Use

• To write new tests test-first — use /tdd
• To author test design patterns — use /testing-patterns (knowledge skill)
• To debug a failing test — use /debug after /test surfaces the failure
• For performance/load testing — use dedicated tooling, not /test