Test Engineer Pro

A comprehensive test engineering agent specializing in testing strategies, automation, and quality assurance across all application layers, with deep expertise in test pyramid design, framework configuration, and CI/CD integration.

When to Use This Agent

Choose Test Engineer Pro when:

• Designing comprehensive testing strategies for new or existing projects
• Setting up testing infrastructure across multiple layers (unit, integration, E2E)
• Writing tests that cover complex business logic with many edge cases
• Implementing test patterns like contract testing, snapshot testing, or property-based testing
• Troubleshooting test reliability issues and optimizing test suite performance

Consider alternatives when:

• Automating manual test workflows (use Expert Test Automator)
• Designing QA processes and metrics (use Expert QA Bot)
• Testing specific browser interactions (use Specialist Playwright Ally)

Quick Start

Copy
# .claude/agents/test-engineer-pro.yml
name: Test Engineer Pro
description: Comprehensive testing strategy and implementation
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep

Example invocation:

claude "Create a comprehensive test suite for the payment processing module covering unit tests, integration tests with Stripe mock, and edge cases for currency conversion, refunds, and partial payments"

Core Concepts

Test Pyramid Implementation

Layer	Ratio	Focus	Speed Target
Unit	70%	Pure functions, hooks, utilities	<10ms each
Integration	20%	Service + DB, API + middleware	<1s each
E2E	10%	Critical user journeys	<30s each

Advanced Testing Patterns

Copy
// Property-based testing with fast-check
import { fc } from '@fast-check/vitest';

describe('currency conversion', () => {
  // Property: converting A→B→A should return original amount (±rounding)
  fc.test(
    'roundtrip conversion preserves value within rounding tolerance',
    [fc.double({ min: 0.01, max: 100000, noNaN: true })],
    (amount) => {
      const usdToEur = convert(amount, 'USD', 'EUR');
      const backToUsd = convert(usdToEur, 'EUR', 'USD');
      expect(Math.abs(backToUsd - amount)).toBeLessThan(0.02);
    }
  );
});

// Contract testing for API boundaries
describe('Payment API contract', () => {
  it('POST /payments matches the OpenAPI schema', async () => {
    const response = await request(app)
      .post('/api/payments')
      .send({ amount: 1000, currency: 'usd', customerId: 'cus_123' });

    expect(response.status).toBe(201);
    expect(response.body).toMatchSchema(paymentResponseSchema);
  });
});

// Snapshot testing for serialization stability
describe('Invoice PDF generation', () => {
  it('generates consistent invoice structure', () => {
    const invoice = generateInvoice(sampleOrder);
    expect(invoice.sections).toMatchSnapshot();
  });
});

Test Data Management

Copy
// test/factories/index.ts — Centralized test data
import { faker } from '@faker-js/faker';

export const factories = {
  user: (overrides: Partial<User> = {}): User => ({
    id: faker.string.uuid(),
    email: faker.internet.email(),
    name: faker.person.fullName(),
    role: 'customer',
    createdAt: faker.date.recent(),
    ...overrides,
  }),

  order: (overrides: Partial<Order> = {}): Order => ({
    id: faker.string.uuid(),
    userId: faker.string.uuid(),
    items: [factories.orderItem()],
    status: 'pending',
    total: 0, // Computed below
    createdAt: faker.date.recent(),
    ...overrides,
  }),

  orderItem: (overrides: Partial<OrderItem> = {}): OrderItem => ({
    productId: faker.string.uuid(),
    name: faker.commerce.productName(),
    quantity: faker.number.int({ min: 1, max: 5 }),
    price: parseFloat(faker.commerce.price({ min: 5, max: 200 })),
    ...overrides,
  }),
};

// Usage in tests
const user = factories.user({ role: 'admin' });
const order = factories.order({ userId: user.id, status: 'paid' });

Configuration

Parameter	Description	Default
framework	Test framework (vitest, jest, pytest, go-test)	Auto-detect
coverage_target	Line coverage threshold	80
testing_patterns	Patterns to apply (property, contract, snapshot)	["unit", "integration"]
mock_strategy	Mocking approach (auto, manual, DI)	auto
data_strategy	Test data approach (factories, fixtures, seeds)	factories
ci_integration	CI provider for pipeline configuration	Auto-detect

Best Practices

1. Use the test as documentation — name tests as complete behavioral specifications. Test names should read as sentences that describe what the system does: "should reject payment when card is expired" not "test payment validation." These names appear in test reports and serve as living documentation. A new developer reading test names should understand the system's behavior without reading implementation code.

2. Apply property-based testing for functions with mathematical or invariant properties. When a function should always satisfy a property (sorted output is always in order, encoding then decoding returns the original, conversion is reversible), use property-based testing to verify the invariant across hundreds of random inputs. This catches edge cases that hand-picked test data misses.

3. Mock at the boundary, not in the middle. Mock external I/O: HTTP calls, database queries, file system operations, and message queues. Do not mock internal functions, private methods, or intermediate layers. Internal mocks create tests that are tightly coupled to implementation details. When you refactor internals, boundary mocks remain stable while internal mocks break.

4. Keep test setup visible in the test, not hidden in beforeEach. When a test's setup is 10 lines in beforeEach and the actual test is 3 lines, a reader cannot understand the test without scrolling up. Use factory functions called within each test for clarity. Reserve beforeEach for mechanical cleanup (mock restoration, DOM cleanup) that is the same for every test. Each test should tell its own complete story.

5. Write tests for the bug before fixing it. When a bug is reported, write a test that reproduces the exact failure condition before writing the fix. This ensures the fix actually addresses the bug (the test goes from red to green) and prevents the bug from recurring (the test catches future regressions). Bugs without reproduction tests have a high recurrence rate.

Common Issues

Tests are brittle and break on every refactor. Tests that assert on internal state, mock internal functions, or verify method call order break whenever the implementation changes, even when behavior is preserved. Refactor tests to assert on outputs and observable side effects. Replace expect(mockInternalFn).toHaveBeenCalledWith(...) with expect(result).toEqual(...). Behavioral tests survive refactoring.

Integration tests are slow because each test sets up the full database. Spinning up a fresh database per test ensures isolation but adds seconds per test. Instead, run each test in a database transaction that rolls back after the test completes. This provides isolation without the setup cost. For tests that need committed data (testing transaction behavior), use a shared database with cleanup in afterEach.

Snapshot tests are updated without reviewing the diff. When a snapshot test fails, developers often run --update-snapshot without examining what changed. This turns snapshot tests into approval stamps rather than regression detectors. Keep snapshots small and focused (one component per snapshot, not an entire page). Review snapshot diffs in PRs as carefully as code changes. If a snapshot is too large to review, it is too large.