Agent-Skills.md

Agent Skills: Testing Standards

Testing standards and TDD workflow. Use when writing tests, running test suites, implementing TDD, or organizing test files. Covers unit vs integration test separation, pytest patterns, and test-driven development methodology.

UncategorizedID: tianjianjiang/smith/smith-tests

Repository

tianjianjiang/smith
tianjianjiang

Install this agent skill to your local

pnpm dlx add-skill https://github.com/tianjianjiang/smith/tree/HEAD/smith-tests

Skill Files

Browse the full folder contents for smith-tests.

Download Skill

Loading file tree…

smith-tests/SKILL.md

Skill Metadata

Name
smith-tests
Description
Testing standards and TDD workflow. Use when writing tests, running test suites, implementing TDD, or organizing test files. Covers unit vs integration test separation, pytest patterns, and test-driven development methodology.

Testing Standards

Load if: Writing tests, running test suites, TDD Prerequisites: @smith-principles/SKILL.md, @smith-standards/SKILL.md, @smith-python/SKILL.md

CRITICAL

  • MUST mirror source structure: foo/bar/xyz.py → tests/unit/foo/bar/test_xyz.py
  • MUST use pytest functions (not classes) - see @smith-python/SKILL.md
  • MUST separate unit (tests/unit/) and integration (tests/integration/) tests
  • MUST use virtual env runner for pytest (poetry run or uv run)
  • MUST write tests BEFORE implementation (TDD)
  • MUST run full test suite proactively after code changes — do not wait for the user to ask
  • MUST run the module's quality gate before reporting completion — linting, type checks, and tests (make quality > project CI script > run individually; see @smith-dev/SKILL.md Pre-PR Quality Gates)
  • Run explicit test paths instead of pytest -m "not integration" when the folder structure is mirrored — that flag causes import conflicts
  • Mock only true external boundaries (LLM, network, DB, clock) — never the branch/unit under test itself; a test that mocks the code path it claims to cover is a false green (the test-masking trap; see @smith-validation/SKILL.md Bugfix Discipline)
  • For a bugfix, write a test that reproduces the real failure FIRST and watch it fail (red) before fixing — write the test to match the real bug, not to fit the fix

Test Organization

Unit:

  • Location: tests/unit/
  • Characteristics: Mock dependencies (external boundaries only — never the unit under test; see CRITICAL above), fast

Integration:

  • Location: tests/integration/
  • Characteristics: Real services, @pytest.mark.integration

TDD Workflow

  1. Bugfix only: reproduce the real failure as a failing regression test first (drive the real code path; mock only true externals) — see @smith-validation/SKILL.md Bugfix Discipline
  2. Understand: Read existing test patterns
  3. Design: Write failing tests defining expected behavior
  4. Implement: Write minimal code to pass tests
  5. Verify: Run tests, validate coverage
  6. Refactor: Improve code while keeping tests green

Environment Configuration

  • tests/conftest.py disables tracking (OPIK, etc.)
  • Virtual env runners load .env automatically
  • Use .env.example as template (NEVER commit .env)

Claude Code Plugin Integration

When pr-review-toolkit is available:

  • pr-test-analyzer agent: Analyzes behavioral coverage, identifies critical gaps
  • Rates test gaps 1-10 (10 = critical, must add)
  • Trigger: "Check if the tests are thorough" or use Task tool

Ralph Loop Integration

TDD = Ralph iteration: test → implement → pytest → iterate until <promise>TESTS PASS</promise>.

See @smith-ralph/SKILL.md for full patterns.

Related

  • @smith-python/SKILL.md - Python testing patterns (pytest functions)
  • @smith-playwright/SKILL.md - Playwright failure monitoring
  • @smith-dev/SKILL.md - Development workflow (quality gates)
  • @smith-validation/SKILL.md - Bugfix Discipline: trace the real path, reproduce first
  • @smith-principles/SKILL.md - Core principles

Before You Finish

Run tests (use project's virtual env runner):

VENV_RUNNER pytest tests/unit/ -v
VENV_RUNNER pytest tests/integration/ -v

VENV_RUNNER = poetry run, uv run, etc. — check project CLAUDE.md or pyproject.toml.

Success criteria:

  • All new functionality has tests
  • Test names follow project conventions
  • Tests are isolated and deterministic
  • No regressions in existing tests