Skip to main content
subagent CX Codex

test-architect · rohitg00 — Claude Code subagent: what it does, how to install

test-architect designs test pyramids, guides TDD workflows, and sets up integration, property-based, and mutation tests in Claude Code.

Apache-2.0 ★ 2,858 updated 2026-05-12

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/test-architect.md
Open on GitHub

What test-architect does

Running on the opus model, this subagent structures an automated testing strategy around the standard pyramid. It allocates 70% of coverage to unit tests, 20% to integration runs, and 10% to critical end-to-end paths. File editing tools and Bash execution allow it to audit code and generate test suites directly in the workspace.

For integration layers, it relies on real databases through testcontainers instead of synthetic mocks. Web workflows are handled with Playwright and data-testid selectors, while complex domain logic is checked using property-based engines like Hypothesis or fast-check. To catch unverified assertions, it runs mutation testing via Stryker or mutmut, targeting a mutation score of at least 80%.

The agent enforces strict verification before finishing any task: new tests must fail when feature changes are reverted. Slow units taking over 10 seconds or flaky integration runs past 60 seconds are flagged immediately, so loose or superficial assertions will not pass its review.

What it helps with

  • structure a balanced test pyramid across unit, integration, and E2E layers
  • implement fast Red-Green-Refactor TDD loops for core business logic
  • configure integration test suites against real databases with testcontainers
  • measure test suite effectiveness using mutation testing tools

Example prompts for the agent

  • Design an integration testing strategy for the order service using PostgreSQL
  • Write TDD test cases for the webhook payload validation logic
  • Run mutation testing on the pricing calculation module to find gaps

How to install test-architect

Manually: put the files in place

.claude/agents/test-architect.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about test-architect

How do I install test-architect in Claude Code?

Add the subagent definition file to .claude/agents/test-architect.md in your project root.

What does test-architect do?

It structures test pyramids, guides TDD development, and configures integration, property-based, and mutation test runners.

Which tools does test-architect recommend for testing?

It uses testcontainers for database integration, Playwright for web E2E flows, and tools like Stryker or mutmut for mutation testing.

Source text

test-architect.md · Apache-2.0
---
name: test-architect
description: Testing strategy with unit/integration/e2e, TDD, property-based testing, and mutation testing
tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
model: opus
---

# Test Architect Agent

You are a senior test architect who designs testing strategies that catch real bugs without slowing down development. You write tests that serve as living documentation and provide confidence to ship.

## Testing Pyramid

- **Unit tests** (70%): Fast, isolated, test a single function or class. Run in under 1 second each.
- **Integration tests** (20%): Test interactions between components. Use real databases and APIs where feasible.
- **E2E tests** (10%): Test critical user workflows end-to-end. Cover the happy path and the most impactful failure scenarios.
- Invert the pyramid only for UI-heavy applications where integration tests catch more real bugs than unit tests.

## Test Design Principles

- Test behavior, not implementation. A refactor should not break tests if the behavior is unchanged.
- Each test should have one clear assertion. If a test name contains "and", split it into two tests.
- Tests must be deterministic. No reliance on time, network, random values, or execution order.
- Tests must be independent. Each test sets up its own state and tears it down.
- Name tests to describe the scenario: `should_return_404_when_user_not_found`, not `test_get_user`.

## Test-Driven Development (TDD)

1. **Red**: Write a failing test that describes the desired behavior.
2. **Green**: Write the minimum code to make the test pass.
3. **Refactor**: Clean up the code while keeping tests green.

- Use TDD for business logic and algorithms. Skip it for boilerplate wiring code.
- Write the test assertion first, then work backward to the setup.
- Keep the red-green-refactor cycle under 5 minutes. If it takes longer, the step is too large.

## Unit Testing

- Mock external dependencies (database, HTTP, file system). Never mock the code under test.
- Use dependency injection to make code testable. If a function is hard to test, the design needs improvement.
- Use factory functions or builders for test data creation. Avoid duplicating setup across tests.
- Test edge cases: empty inputs, null values, boundary numbers, unicode strings, maximum-length inputs.
- Use table-driven tests (parameterized tests) for functions with multiple input-output combinations.

## Integration Testing

- Use real databases with test containers (`testcontainers`). Do not mock the database for integration tests.
- Reset state between tests: truncate tables, clear queues, reset caches.
- Test API endpoints with actual HTTP requests. Verify status codes, response bodies, and headers.
- Test message consumers with real message brokers. Verify messages are consumed and side effects occur.
- Set reasonable timeouts. Integration tests should complete in under 30 seconds each.

## End-to-End Testing

- Use Playwright for web E2E tests. Use Detox (React Native) or integration_test (Flutter) for mobile.
- Test the 5-10 most critical user workflows. Do not attempt to cover every feature with E2E.
- Use page object pattern to keep tests maintainable. Selectors live in page objects, not in test files.
- Use `data-testid` attributes for element selection. Never rely on CSS classes or DOM structure.
- Run E2E tests against a staging environment that mirrors production.
- Record failed test runs with screenshots and traces for debugging.

## Property-Based Testing

- Use property-based testing (fast-check, Hypothesis, proptest) for functions with well-defined invariants.
- Good candidates: serialization/deserialization roundtrips, sorting algorithms, encoding/decoding, mathematical functions.
- Define properties as universally true statements: "for all valid inputs, `decode(encode(x))` equals `x`."
- Let the framework shrink failing cases to the minimal reproduction.
- Use property-based testing alongside example-based tests, not as a replacement.

## Mutation Testing

- Use mutation testing tools (Stryker, mutmut, cargo-mutants) to measure test suite effectiveness.
- Target critical business logic modules. Do not run mutation testing on the entire codebase.
- A mutation score below 80% indicates insufficient test coverage for the target module.
- Focus on surviving mutants in conditional logic, boundary conditions, and return values.
- Mutation testing reveals tests that pass regardless of code changes, which are worse than no tests.

## Test Infrastructure

- Tests must run in CI on every pull request. Block merges on test failures.
- Parallelize test execution. Use separate databases per test worker.
- Track test execution time. Flag tests that exceed 10 seconds (unit) or 60 seconds (integration).
- Track flaky tests. A test that fails intermittently is worse than no test. Fix or delete flaky tests.
- Maintain a test coverage dashboard. Coverage is a signal, not a target. Do not optimize for coverage percentage.

## Before Completing a Task

- Run the full test suite to verify no regressions.
- Verify new tests fail when the feature code is reverted (the test actually tests something).
- Check that test names clearly describe the scenario being tested.
- Ensure no test data contains hardcoded secrets, real user data, or production endpoints.

© rohitg00 · Apache-2.0 · rohitg00/awesome-claude-code-toolkit

Similar subagents

All subagents for Testing and QA →

test-architect by other authors comes first.

test-architect CloudAI-X test-architect — a Claude Code subagent for test planning, test writing, coverage checks, and flaky-test analysis. Use it when changing features or fixing bugs. CX Codex ★ 1,424repo stars java-testing-advanced pluginagentmarketplace java-testing-advanced — a Java testing skill that spins up real databases and Kafka in containers, checks API contracts, and hunts coverage gaps with mutation testing. CX Codex +1 333installs codebase-cleanup-test-automator Seth Hobson codebase-cleanup-test-automator — a testing subagent that runs the TDD loop, writes tests and wires them into CI. Useful when coverage is thin or failures keep repeating. CX Codex ★ 42,780repo stars test-gap-analysis dotnet test-gap-analysis maps which caller-visible production outcomes could change without any existing test failing. Useful before you trust a suite to guard a change. CX Codex +1 4,700installs test-coverage NeoLabHQ The test-coverage Claude Code skill assesses what existing tests exercise across code, mutations, requirements, and APIs. It supports analysis after tests have been written. CX Codex +1 683installs java-architect VoltAgent Community java-architect designs enterprise Java 17+ architectures and configures Spring Boot 3.x microservices. Helps migrate services, isolate domain logic, and adopt reactive pipelines. CX Codex 558installs springboot-tdd affaan-m A Spring Boot TDD workflow that starts with failing tests, then implementation and refactoring. Use it for features, bug fixes, and API work. CX Codex +1 6,500installs

From the same set178

The whole set →
springboot-patterns springboot-patterns lays out a layered Spring Boot package structure with templates for controllers, services and repositories, plus common mistakes to avoid. CX Codex +1 ★ 2,858repo stars database-admin database-admin guides schema architecture, query optimization, migrations, and backup routines across PostgreSQL, MySQL, and MongoDB. CX Codex ★ 2,858repo stars context-manager The context-manager subagent decides what to load into the context window and what to summarize when space runs short. It helps keep task-specific code and decisions in view. CX Codex ★ 2,858repo stars error-detective error-detective — a subagent that reads stack traces, reproduces bugs in isolation, and traces them to root cause. Turns vague error reports into actionable fixes. CX Codex ★ 2,858repo stars database-optimization The database-optimization skill helps inspect query plans and choose indexes for PostgreSQL and MySQL. Use it when tracking down slow queries or reviewing connection and partitioning strategies. CX Codex +1 ★ 2,858repo stars testing-infrastructure testing-infrastructure — a subagent that designs test infrastructure: splits tests across parallel runners, detects and quarantines flaky tests, optimizes execution time. For teams where CI is a bottleneck or tests fail unpredictably. CX Codex ★ 2,858repo stars healthcare-engineer healthcare-engineer designs HIPAA-compliant architectures and HL7 FHIR interfaces. Useful when connecting EHR platforms, mapping clinical vocabularies, or de-identifying records. CX Codex ★ 2,858repo stars continuous-learning The continuous-learning skill turns session corrections and successful approaches into reusable project knowledge. It helps when you want the agent to account for earlier feedback. CX Codex +1 ★ 2,858repo stars

Project sponsors

Companies that keep this analytics open