Skip to main content
skill CX Codex

testing-principles — Claude Code skill: what it does, how to install

testing-principles — a skill for Claude Code enforces language-agnostic guidelines for test selection, mock boundaries, and assertion design. Triggers when writing new tests, planning test scope, or reviewing test suites.

MIT ★ 720 updated 2026-11-11

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add shinpr/claude-code-workflows --skill testing-principles -a claude-code
Open on GitHub

What testing-principles does

The skill sets principles for testing behavior at observable system boundaries: integration and end-to-end tests for user journeys, and focused unit tests for complex branching or parsing. Every behavioral claim is owned by a single test to eliminate duplication and brittle tests coupled to internal code. Test coverage serves as a diagnostic tool rather than a vanity metric.

It dictates an Arrange-Act-Assert structure, strict state isolation, and cleanup after every run. Mocking rules restrict doubles to direct external I/O boundaries via existing application adapters, keeping core business logic real. When testing repository queries, schema constraints, or migrations, tests must execute against the repository's real database engine.

Bug fixes require an executable regression test, while legacy modifications mandate characterization tests before altering code.

What it helps with

  • choose the right boundary between E2E, integration, and unit tests
  • structure assertions using Arrange-Act-Assert without targeting internal implementation
  • confine test doubles to external I/O boundaries while running core domain logic real
  • verify database queries and migrations against an actual database engine
  • write characterization or regression tests before modifying legacy behavior

Example prompts for the agent

  • Review our existing test suite for checkout and point out implementation-coupled assertions
  • Design integration and unit tests for the user registration flow following testing-principles
  • Add a regression test for the caching bug before applying the patch

How to install testing-principles

1Skills CLI (Vercel)

npx skills add shinpr/claude-code-workflows --skill testing-principles -a claude-code

2Manually: put the files in place

~/.claude/skills/testing-principles/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/testing-principles/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about testing-principles

How do I install testing-principles in Claude Code?

Run npx skills add shinpr/claude-code-workflows --skill testing-principles -a claude-code. Alternatively, place the skill file into ~/.claude/skills/testing-principles/SKILL.md.

What does the testing-principles skill do?

It provides language-agnostic rules for scoping and structuring tests, guiding agents to verify observable outcomes at public boundaries. It prevents tests that couple to private implementation details and ensures each behavioral claim is owned by a single test.

When does the skill require a real database instead of mocks?

Mocks are permitted only when data access is an incidental dependency. When validating repository code, custom queries, schema constraints, or migration compatibility, the skill requires executing against the project's actual database engine.

Source text

SKILL.md · MIT
---
name: testing-principles
description: Language-agnostic testing principles for choosing which tests a change needs, test quality, and proof ownership, including frontend and browser E2E tests. Use when writing tests, deciding test scope, or reviewing test quality.
---

# Language-Agnostic Testing Principles

Tests here guarantee accepted behavior, and the next agent reads every existing test as a requirement to preserve. A brittle, duplicated, or implementation-shaped test therefore becomes a false requirement: it gets worked around, and the workaround leaves debt in the implementation. Keep the set of tests whose proof is worth its maintenance.

## Test Selection

- Prove accepted behavior by default through integration and E2E tests at the boundary users and callers observe. Add a unit test for logic whose cases one representative boundary test cannot prove, such as calculations, parsing, or branching rules.
- Each behavioral claim is owned by one test: such logic by its unit test, other behavior by the test at the narrowest integration or E2E boundary where it is observable. A test at a wider boundary or in a variant (viewport, device, role) proves what that boundary or variant adds, such as wiring, mapping, persistence, rendering, or navigation, and keeps at most one representative case of a rule owned elsewhere.
- Determine the required proof boundary from the accepted outcome before minimizing tests. An outcome delivered through an application or service entry point includes the relevant production composition, such as routing, providers, state ownership or adapters. An isolated component test or a test-built substitute composition does not prove that wiring. Reuse proof that traverses it, or select a test that will; choose the harness by what it must observe, not by component count or a lane quota. A disconnected action, lost state update or broken transition can remain invisible to tests below that boundary. Explicitly component-scoped outcomes retain their component boundary.
- Treat coverage as a diagnostic signal for finding untested areas, not a target; any CI threshold is the project's config, not a quality goal in itself.
- Use project-configured speed budgets when present. Otherwise investigate test speed only when observed feedback or CI cost is material to the current outcome; retain slower tests when their proof boundary requires it.

## Test Design Rules

- Structure each test as Arrange, one Act, and Assert; multiple assertions may prove one behavior.
- Follow the repository's test naming convention and name the condition and observable outcome.
- Exercise behavior through a public or integration boundary. Assertions verify return values, outputs, errors, or state changes rather than private implementation.
- Use independently derived literal, property, approved snapshot, or fixture expectations. An implementation-derived oracle cannot detect the same implementation defect.
- Keep each test's expected outcome unconditional. Table-driven or property-based cases are acceptable when each case is reported distinctly and uses an independent oracle.
- Cover accepted boundary and error behavior; derive cases from the contract instead of adding generic edge-case permutations.
- Each test creates and cleans up its own state, passes in isolation and any order, and controls time or randomness that affects its result.
- Keep tests executable. Fix or remove tests that no longer describe accepted behavior; restore tests disabled only to bypass a failure.

## Mock and Boundary Rules

- Mock direct external I/O boundaries; keep internal business logic and the boundary under test real.
- Use the existing application-owned adapter as the mock boundary. Introduce an adapter only when external I/O, an unstable contract, or required substitution cannot be controlled through the current design.
- Keep mock behavior limited to the contract needed by the test.

## Data Layer Testing

Mock-based tests are sufficient when data access is only a dependency of the behavior under test. Verify against the project's real database engine or its accepted equivalent when the subject is a query, repository implementation, schema constraint, or migration compatibility. Resolve the test environment from repository configuration; when no representative environment exists and adding one is outside the approved work, report the missing verification decision.

Cross-check data-access code against the schema source named in the Design Doc or repository configuration. Schema-source verification is required to prove table, column, type, constraint, or dialect compatibility; successful mocks prove behavior only at the mocked boundary.

## Verification Requirements

### Capability Probe Postconditions

A capability probe passes when it uses the consumer's boundary and asserts the exact property that consumer needs. Command success, import success, or object existence is setup evidence.

## Test Organization

Follow the repository's established test paths, runner routing, and naming. When establishing an approved new convention, separate test types only when their setup, runner, or environment differs.

## Regression Testing

- Add a regression test for every reproducible behavior bug fix. When executable reproduction is impossible, record the reason and the alternative static, contract, or environment evidence that prevents recurrence.
- Before behavior-preserving changes to uncharacterized legacy code, establish passing characterization evidence and rerun it after the change.

## References

- [references/frontend.md](references/frontend.md): read when writing, changing, or reviewing component, hook, or UI integration tests
- [references/e2e.md](references/e2e.md): read when writing, changing, or reviewing browser E2E tests

© shinpr · MIT · shinpr/claude-code-workflows

Similar skills

All skills for Testing and QA →

From the same set43

The whole set →
external-resource-context external-resource-context tracks access details for external API schemas, design files, IaC, and secret stores outside the repository. Prevents repeated discovery of environment assets. CX Codex +1 ★ 720repo stars task-decomposer task-decomposer turns each task in an approved Work Plan into a separate implementation file. Use it when the plan is ready to hand off for execution. CX Codex ★ 720repo stars acceptance-test-generator acceptance-test-generator — a subagent for Claude Code generates integration and E2E test skeletons from Design Doc acceptance criteria. Triggers when planning test suites or on requests mentioning test skeletons. CX Codex ★ 720repo stars requirement-analyzer requirement-analyzer inspects the codebase to collect scope and cost evidence before confirming new implementation requirements. CX Codex ★ 720repo stars llm-friendly-context llm-friendly-context rewrites prompts, handoffs and generated docs so the next agent can see the inputs, the steps and what counts as done. Useful whenever text goes to another model. CX Codex +1 ★ 720repo stars requirement-convergence requirement-convergence — a Claude Code skill that isolates a project outcome from proposed requirements and records user-stated exclusions. Runs at requirement intake before any system design begins. CX Codex +1 ★ 720repo stars work-planner The work-planner Claude Code subagent turns approved Design Docs into implementation plans with tasks, dependencies, and checks. It activates for work-plan or task-planning requests. CX Codex ★ 720repo stars typescript-rules Enforces React and TypeScript rules for frontend work: type safety, component structure, state ownership and error handling. CX Codex +1 ★ 720repo stars

Project sponsors

Companies that keep this analytics open