---
name: designing-tests-049cf75af609
description: Designs and implements testing strategies for any codebase. Use when adding tests, improving coverage, setting up testing infrastructure, debugging test failures, or when asked about unit tests, integration tests, or E2E testing.
---

# Designing Tests

### When to Load

- **Trigger**: Adding tests, test strategy planning, improving coverage, setting up testing infrastructure
- **Skip**: Non-test code changes where testing is not part of the task

## Test Implementation Workflow

Copy this checklist and track progress:

```
Test Implementation Progress:
- [ ] Step 1: Identify what to test
- [ ] Step 2: Select appropriate test type
- [ ] Step 3: Write tests following templates
- [ ] Step 4: Run tests and verify passing
- [ ] Step 5: Check coverage meets targets
- [ ] Step 6: Fix any failing tests
```

## Testing Pyramid

Apply the testing pyramid for balanced coverage:

```
        /\
       /  \     E2E Tests (10%)
      /----\    - Critical user journeys
     /      \   - Slow but comprehensive
    /--------\  Integration Tests (20%)
   /          \ - Component interactions
  /------------\ - API contracts
 /              \ Unit Tests (70%)
/________________\ - Fast, isolated
                   - Business logic focus
```

## Framework Selection

### JavaScript/TypeScript

| Type        | Recommended     | Alternative         |
| ----------- | --------------- | ------------------- |
| Unit        | Vitest          | Jest                |
| Integration | Vitest + MSW    | Jest + SuperTest    |
| E2E         | Playwright      | Cypress             |
| Component   | Testing Library | Vitest Browser Mode |

### Python

| Type        | Recommended                 | Alternative       |
| ----------- | --------------------------- | ----------------- |
| Unit        | pytest                      | unittest          |
| Integration | pytest + httpx              | pytest + requests |
| E2E         | Playwright                  | Selenium          |
| API         | pytest + FastAPI TestClient | -                 |

### Go

| Type        | Recommended        |
| ----------- | ------------------ |
| Unit        | testing + testify  |
| Integration | testing + httptest |
| E2E         | testing + chromedp |

## Test Structure Templates

### Unit Test

```javascript
describe("[Unit] ComponentName", () => {
  describe("methodName", () => {
    it("should [expected behavior] when [condition]", () => {
      // Arrange
      const input = createTestInput();

      // Act
      const result = methodName(input);

      // Assert
      expect(result).toEqual(expectedOutput);
    });

    it("should throw error when [invalid condition]", () => {
      expect(() => methodName(invalidInput)).toThrow(ExpectedError);
    });
  });
});
```

### Integration Test

```javascript
describe("[Integration] API /users", () => {
  beforeAll(async () => {
    await setupTestDatabase();
  });

  afterAll(async () => {
    await teardownTestDatabase();
  });

  it("should create user and return 201", async () => {
    const response = await request(app)
      .post("/users")
      .send({ name: "Test", email: "test@example.com" });

    expect(response.status).toBe(201);
    expect(response.body.id).toBeDefined();
  });
});
```

### E2E Test

```javascript
import { test, expect } from "@playwright/test";

test.describe("[E2E] User Registration Flow", () => {
  test("should complete registration successfully", async ({ page }) => {
    await page.goto("/register");

    await page.getByTestId("email").fill("new@example.com");
    await page.getByTestId("password").fill("SecurePass123!");
    await page.getByTestId("submit").click();

    await expect(page.locator(".welcome-message")).toBeVisible();
    await expect(page).toHaveURL("/dashboard");
  });
});
```

## Coverage Strategy

### What to Cover

- ✅ Business logic (100%)
- ✅ Edge cases and error handling (90%+)
- ✅ API contracts (100%)
- ✅ Critical user paths (E2E)
- ⚠️ UI components (snapshot + interaction)
- ❌ Third-party library internals
- ❌ Simple getters/setters

### Coverage Thresholds

Jest config shown; the Vitest equivalent is `test.coverage.thresholds` in vitest.config.

```json
{
  "coverageThreshold": {
    "global": {
      "branches": 80,
      "functions": 80,
      "lines": 80,
      "statements": 80
    },
    "src/core/": {
      "branches": 95,
      "functions": 95
    }
  }
}
```

## Test Data Management

### Factories/Builders

```javascript
// factories/user.js
export const userFactory = (overrides = {}) => ({
  id: faker.string.uuid(),
  name: faker.person.fullName(),
  email: faker.internet.email(),
  createdAt: new Date(),
  ...overrides,
});

// Usage
const admin = userFactory({ role: "admin" });
```

### Fixtures

```javascript
// fixtures/users.json
{
  "validUser": { "name": "Test", "email": "test@example.com" },
  "invalidUser": { "name": "", "email": "invalid" }
}
```

## Mocking Strategy

### When to Mock

- ✅ External APIs and services
- ✅ Database in unit tests
- ✅ Time/Date for determinism
- ✅ Random values
- ❌ Internal modules (usually)
- ❌ The code under test

### Mock Examples

```javascript
// API mocking with MSW
import { http, HttpResponse } from "msw";

export const handlers = [
  http.get("/api/users", () => {
    return HttpResponse.json([{ id: 1, name: "John" }]);
  }),
];

// Time mocking
vi.useFakeTimers();
vi.setSystemTime(new Date("2024-01-01"));
```

## Test Validation Loop

After writing tests, run this validation:

```
Test Validation:
- [ ] All tests pass: `npm test`
- [ ] Coverage meets thresholds: `npm test -- --coverage`
- [ ] No flaky tests (run multiple times)
- [ ] Tests are independent (order doesn't matter)
- [ ] Test names clearly describe behavior
```

If any tests fail, fix them before proceeding. If coverage is below target, add more tests for uncovered code paths.

```bash
# Run tests
npm test

# Run with coverage
npm test -- --coverage

# Run specific test file
npm test -- path/to/test.spec.ts

# Run in watch mode during development
npm test -- --watch
```


---
Source attribution: CloudAI-X
Original project: https://github.com/CloudAI-X/claude-workflow-v2
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2026 Gabriel Moreira

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: CloudAI-X
Original project: https://github.com/CloudAI-X/claude-workflow-v2
Attribution basis: Upstream repository explicitly recorded in package mirror path

Fields of work: Development & Engineering, Product Management
Roles: Backend Developer, DevOps / SRE, Frontend Developer, Product Manager, QA / Test Engineer
Specialties: Backend, Cross Platform, Frontend, Testing
Tools: Playwright
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 178aa64c0bea58c4be4d10742b47cd8d9f82b6c23a7965366e6cb0d30815bdc3