Senior Qa

Senior QA Engineer

Test automation, coverage analysis, and quality assurance patterns for React and Next.js applications. Generates Jest + React Testing Library unit test stubs, analyzes Istanbul/LCOV coverage for gaps, and scaffolds Playwright E2E suites for App Router and Pages Router projects.

Core Capabilities

• Unit test generation — scan React/TypeScript components and emit Jest + RTL stubs (render, interaction, state, optional jest-axe a11y).
• Coverage analysis — parse Istanbul/LCOV reports, identify gaps by severity, flag critical business-logic paths, and emit text/HTML/JSON recommendations.
• E2E scaffolding — detect Next.js routes (dynamic segments, route groups, auth pages) and generate Playwright specs, Page Object Models, fixtures, and config.
• Test strategy — the testing pyramid, coverage targets by code type, and test organization patterns.
• Automation patterns — Page Object Model, data factories, MSW mocking, fixtures, and custom render utilities.
• Quality practices — testable code design, AAA structure, test isolation, flaky-test elimination, and quality metrics.

When to Use

• Setting up unit tests for new or existing React components.
• Improving test coverage or preparing for release.
• Setting up Playwright E2E tests for a Next.js project.
• Configuring Jest thresholds or improving overall test quality.

Clarify First

Before generating tests, confirm these inputs. If any is unknown or vague, ASK — do not assume:

• [ ] Test layer — unit (Jest+RTL) vs E2E (Playwright) (selects test_suite_generator vs e2e_test_scaffolder)
• [ ] Source path — the components or Next.js routes to generate tests from (the scaffolder's input)
• [ ] Coverage focus — happy path only vs interaction/state/a11y (jest-axe) (sets which test stubs are emitted)

Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.

Tools

References

Load the reference that matches the task — keep this file lean and pull detail on demand:

• [references/qa-workflows-and-tools.md](references/qa-workflows-and-tools.md) — quick start, the three tool overviews with sample output, the unit-test/coverage/E2E workflows, common pattern snippets (RTL queries, async, MSW, Playwright locators, jest thresholds), common commands, troubleshooting table, and success criteria. Read when running a workflow.
• [references/tool-cli-reference.md](references/tool-cli-reference.md) — full flag tables, examples, output formats, and generated artifacts for all three scripts. Read before running the scripts.
• [references/testing_strategies.md](references/testing_strategies.md) — the testing pyramid, testing types, coverage targets and thresholds, and test organization patterns. Read when designing test strategy.
• [references/test_automation_patterns.md](references/test_automation_patterns.md) — Page Object Model, data factories, fixture management, mocking strategies (MSW), and custom test utilities. Read when writing test code.
• [references/qa_best_practices.md](references/qa_best_practices.md) — writing testable code, naming conventions, AAA pattern, test isolation, flaky-test debugging, and quality metrics. Read when improving test quality.

Scope & Limitations

This skill covers:

• Unit test stub generation for React/TypeScript functional and class components using Jest and React Testing Library.
• Coverage analysis and gap identification from Istanbul JSON and LCOV report formats.
• E2E test scaffolding for Next.js App Router and Pages Router projects using Playwright.
• Accessibility test generation via jest-axe integration.

This skill does NOT cover:

• Backend API testing (see senior-backend for Express/Node.js testing patterns).
• Performance or load testing (see senior-devops for infrastructure and performance tooling).
• Visual regression testing or screenshot comparison workflows.
• Mobile-native testing (React Native, Flutter) -- this skill targets web browser-based testing only.

Integration Points

Senior QA Testing Engineer Skill

Production-ready quality assurance and test automation skill for React/Next.js applications.

Tech Stack Focus

Quick Start

# Generate component tests
python scripts/test_suite_generator.py src/components --include-a11y

# Analyze coverage gaps
python scripts/coverage_analyzer.py coverage/coverage-final.json --threshold 80 --strict

# Scaffold E2E tests for Next.js
python scripts/e2e_test_scaffolder.py src/app --page-objects

Scripts

test_suite_generator.py

Scans React/TypeScript components and generates Jest + React Testing Library test stubs.

Features:

• Detects functional, class, memo, and forwardRef components
• Generates render, interaction, and accessibility tests
• Identifies props requiring mock data
• Optional --include-a11y for jest-axe assertions

Usage:

python scripts/test_suite_generator.py <component-dir> [options]

Options:
  --scan-only       List components without generating tests
  --include-a11y    Add accessibility test assertions
  --output DIR      Output directory for test files

coverage_analyzer.py

Parses Istanbul JSON or LCOV coverage reports and identifies testing gaps.

Features:

• Calculates line, branch, function, and statement coverage
• Identifies critical untested paths (auth, payment, API routes)
• Generates text and HTML reports
• Threshold enforcement with --strict flag

Usage:

python scripts/coverage_analyzer.py <coverage-file> [options]

Options:
  --threshold N     Minimum coverage percentage (default: 80)
  --strict          Exit with error if below threshold
  --format FORMAT   Output format: text, json, html
  --output FILE     Output file path

e2e_test_scaffolder.py

Scans Next.js App Router or Pages Router directories and generates Playwright tests.

Features:

• Detects routes, dynamic parameters, and layouts
• Generates test files per route with navigation and content checks
• Optional Page Object Model class generation
• Generates playwright.config.ts and auth fixtures

Usage:

python scripts/e2e_test_scaffolder.py <app-dir> [options]

Options:
  --page-objects    Generate Page Object Model classes
  --output DIR      Output directory for E2E tests
  --base-url URL    Base URL for tests (default: http://localhost:3000)

References

testing_strategies.md (650 lines)

Comprehensive testing strategy guide covering:

• Test pyramid and distribution (70% unit, 20% integration, 10% E2E)
• Coverage targets by project type
• Testing types (unit, integration, E2E, visual, accessibility)
• CI/CD integration patterns
• Testing decision framework

test_automation_patterns.md (1010 lines)

React/Next.js test automation patterns:

• Page Object Model implementation for Playwright
• Test data factories and builder patterns
• Fixture management (Playwright and Jest)
• Mocking strategies (MSW, Jest module mocking)
• Custom test utilities (renderWithProviders)
• Async testing patterns
• Snapshot testing guidelines

qa_best_practices.md (965 lines)

Quality assurance best practices:

• Writing testable React code
• Test naming conventions (Describe-It pattern)
• Arrange-Act-Assert structure
• Test isolation principles
• Handling flaky tests
• Debugging failed tests
• Quality metrics and KPIs

Workflows

Workflow 1: New Component Testing

1. Create component in src/components/ 2. Run test_suite_generator.py to generate test stub 3. Fill in test assertions based on component behavior 4. Run npm test to verify tests pass 5. Check coverage with coverage_analyzer.py

Workflow 2: E2E Test Setup

1. Run e2e_test_scaffolder.py on your Next.js app directory 2. Review generated tests in e2e/ directory 3. Customize Page Objects for complex interactions 4. Run npx playwright test to execute 5. Configure CI/CD with generated playwright.config.ts

Workflow 3: Coverage Gap Analysis

1. Run tests with coverage: npm test -- --coverage 2. Analyze with coverage_analyzer.py --strict --threshold 80 3. Review critical untested paths in report 4. Prioritize tests for auth, payment, and API routes 5. Re-run analysis to verify improvement

Test Pyramid Targets

Coverage Targets

CI/CD Integration

# .github/workflows/test.yml
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install dependencies
        run: npm ci
      - name: Run unit tests
        run: npm test -- --coverage
      - name: Run E2E tests
        run: npx playwright test
      - name: Upload coverage
        uses: codecov/codecov-action@v4

Related Skills

• senior-frontend - React/Next.js component development
• senior-fullstack - Full application architecture
• senior-devops - CI/CD pipeline setup
• code-reviewer - Code review with testing focus

---

Version: 2.0.0 Last Updated: January 2026 Tech Focus: React 18+, Next.js 14+, Jest 29+, Playwright 1.40+

QA Best Practices for React and Next.js

Guidelines for writing maintainable tests, debugging failures, and measuring test quality.

---

Table of Contents

• Writing Testable Code
• Test Naming Conventions
• Arrange-Act-Assert Pattern
• Test Isolation Principles
• Handling Flaky Tests
• Code Review for Testability
• Test Maintenance Strategies
• Debugging Failed Tests
• Quality Metrics and KPIs

---

Writing Testable Code

Testable code is easy to understand, has clear boundaries, and minimizes dependencies.

Dependency Injection

Instead of creating dependencies inside functions, pass them as parameters.

Hard to Test:

// src/services/userService.ts
import { prisma } from '../lib/prisma';
import { sendEmail } from '../lib/email';

export async function createUser(data: UserInput) {
  const user = await prisma.user.create({ data });
  await sendEmail(user.email, 'Welcome!');
  return user;
}

Easy to Test:

// src/services/userService.ts
export function createUserService(
  db: PrismaClient,
  emailService: EmailService
) {
  return {
    async createUser(data: UserInput) {
      const user = await db.user.create({ data });
      await emailService.send(user.email, 'Welcome!');
      return user;
    },
  };
}

// Usage in app
const userService = createUserService(prisma, emailService);

// Usage in tests
const mockDb = { user: { create: jest.fn() } };
const mockEmail = { send: jest.fn() };
const testService = createUserService(mockDb, mockEmail);

Pure Functions

Pure functions are deterministic and have no side effects, making them trivial to test.

Impure (Hard to Test):

function formatTimestamp() {
  const now = new Date();
  return `${now.getFullYear()}-${now.getMonth() + 1}-${now.getDate()}`;
}

Pure (Easy to Test):

function formatTimestamp(date: Date): string {
  return `${date.getFullYear()}-${date.getMonth() + 1}-${date.getDate()}`;
}

// Test
expect(formatTimestamp(new Date('2024-03-15'))).toBe('2024-3-15');

Separation of Concerns

Separate business logic from UI and I/O operations.

Mixed Concerns (Hard to Test):

// Component with embedded business logic
function CheckoutForm() {
  const [total, setTotal] = useState(0);

  const handleSubmit = async (items: CartItem[]) => {
    // Business logic mixed with UI
    let sum = 0;
    for (const item of items) {
      sum += item.price * item.quantity;
      if (item.category === 'electronics') {
        sum *= 0.9; // 10% discount
      }
    }
    const tax = sum * 0.08;
    const finalTotal = sum + tax;

    // API call
    await fetch('/api/orders', {
      method: 'POST',
      body: JSON.stringify({ items, total: finalTotal }),
    });

    setTotal(finalTotal);
  };

  return <form onSubmit={handleSubmit}>...</form>;
}

Separated Concerns (Easy to Test):

// Pure business logic (easy to unit test)
export function calculateOrderTotal(items: CartItem[]): number {
  return items.reduce((sum, item) => {
    const subtotal = item.price * item.quantity;
    const discount = item.category === 'electronics' ? 0.9 : 1;
    return sum + subtotal * discount;
  }, 0);
}

export function calculateTax(subtotal: number, rate = 0.08): number {
  return subtotal * rate;
}

// Custom hook for order logic (testable with renderHook)
export function useCheckout() {
  const [total, setTotal] = useState(0);
  const mutation = useMutation(createOrder);

  const checkout = async (items: CartItem[]) => {
    const subtotal = calculateOrderTotal(items);
    const tax = calculateTax(subtotal);
    const finalTotal = subtotal + tax;

    await mutation.mutateAsync({ items, total: finalTotal });
    setTotal(finalTotal);
  };

  return { checkout, total, isLoading: mutation.isLoading };
}

// Component (integration testable)
function CheckoutForm() {
  const { checkout, total, isLoading } = useCheckout();
  return <form onSubmit={() => checkout(items)}>...</form>;
}

Component Design for Testability

---

Test Naming Conventions

Good test names document expected behavior and help diagnose failures.

Naming Patterns

Pattern 1: should [expected behavior] when [condition]

describe('LoginForm', () => {
  it('should display error message when credentials are invalid', () => {});
  it('should redirect to dashboard when login succeeds', () => {});
  it('should disable submit button when form is submitting', () => {});
});

Pattern 2: [method/action] [expected result]

describe('calculateDiscount', () => {
  it('returns 0 for orders under $50', () => {});
  it('returns 10% for orders $50-$99', () => {});
  it('returns 20% for orders $100+', () => {});
});

Pattern 3: given [context], when [action], then [result]

describe('ShoppingCart', () => {
  it('given an empty cart, when adding an item, then cart count is 1', () => {});
  it('given items in cart, when removing all, then cart is empty', () => {});
});

Describe Block Organization

describe('UserService', () => {
  describe('createUser', () => {
    describe('with valid input', () => {
      it('creates user in database', () => {});
      it('sends welcome email', () => {});
      it('returns user with id', () => {});
    });

    describe('with invalid input', () => {
      it('throws ValidationError for missing email', () => {});
      it('throws ValidationError for invalid email format', () => {});
      it('throws ConflictError for duplicate email', () => {});
    });
  });

  describe('deleteUser', () => {
    it('removes user from database', () => {});
    it('throws NotFoundError for non-existent user', () => {});
  });
});

Anti-patterns to Avoid

---

Arrange-Act-Assert Pattern

The AAA pattern structures tests into three clear phases.

Structure

it('calculates total with discount', () => {
  // Arrange - Set up test data and conditions
  const items = [
    { name: 'Widget', price: 100, quantity: 2 },
    { name: 'Gadget', price: 50, quantity: 1 },
  ];
  const discountRate = 0.1;

  // Act - Execute the code being tested
  const result = calculateTotal(items, discountRate);

  // Assert - Verify the outcome
  expect(result).toBe(225); // (200 + 50) * 0.9
});

Async Example

it('fetches user profile', async () => {
  // Arrange
  const userId = '123';
  server.use(
    rest.get('/api/users/:id', (req, res, ctx) =>
      res(ctx.json({ id: userId, name: 'John' }))
    )
  );

  // Act
  render(<UserProfile userId={userId} />);

  // Assert
  await expect(screen.findByText('John')).resolves.toBeInTheDocument();
});

Component Testing Example

it('submits form with user input', async () => {
  // Arrange
  const user = userEvent.setup();
  const onSubmit = jest.fn();
  render(<ContactForm onSubmit={onSubmit} />);

  // Act
  await user.type(screen.getByLabelText('Name'), 'John Doe');
  await user.type(screen.getByLabelText('Email'), 'john@example.com');
  await user.type(screen.getByLabelText('Message'), 'Hello!');
  await user.click(screen.getByRole('button', { name: 'Send' }));

  // Assert
  expect(onSubmit).toHaveBeenCalledWith({
    name: 'John Doe',
    email: 'john@example.com',
    message: 'Hello!',
  });
});

Guidelines

1. One Act per test - Test one behavior at a time 2. Multiple assertions OK - If they verify the same behavior 3. Avoid logic in tests - No if/else, loops in test code 4. Setup in Arrange, not beforeEach - Unless truly shared

---

Test Isolation Principles

Isolated tests are independent, repeatable, and can run in any order.

State Isolation

describe('CartService', () => {
  let cartService: CartService;

  // Fresh instance for each test
  beforeEach(() => {
    cartService = new CartService();
  });

  it('adds item to empty cart', () => {
    cartService.addItem({ id: '1', quantity: 1 });
    expect(cartService.getItems()).toHaveLength(1);
  });

  it('starts with empty cart', () => {
    // Not affected by previous test
    expect(cartService.getItems()).toHaveLength(0);
  });
});

Database Isolation

describe('UserRepository', () => {
  beforeAll(async () => {
    // Connect to test database
    await db.connect(process.env.TEST_DATABASE_URL);
  });

  beforeEach(async () => {
    // Clean database before each test
    await db.query('TRUNCATE users CASCADE');
  });

  afterAll(async () => {
    await db.disconnect();
  });

  it('creates user', async () => {
    const user = await userRepo.create({ email: 'test@example.com' });
    expect(user.id).toBeDefined();
  });
});

API Mocking Isolation

describe('ProductList', () => {
  // Reset handlers after each test
  afterEach(() => server.resetHandlers());

  it('shows products from API', async () => {
    // Default handler returns products
    render(<ProductList />);
    await expect(screen.findByText('Widget')).resolves.toBeInTheDocument();
  });

  it('shows error on API failure', async () => {
    // Override handler for this test only
    server.use(
      rest.get('/api/products', (req, res, ctx) =>
        res(ctx.status(500))
      )
    );

    render(<ProductList />);
    await expect(screen.findByText('Error')).resolves.toBeInTheDocument();
  });

  it('shows products again', async () => {
    // Back to default handler (server.resetHandlers ran)
    render(<ProductList />);
    await expect(screen.findByText('Widget')).resolves.toBeInTheDocument();
  });
});

Isolation Checklist

---

Handling Flaky Tests

Flaky tests pass and fail intermittently without code changes.

Common Causes and Fixes

1. Timing Issues

// Flaky - race condition
it('shows loading then data', () => {
  render(<UserProfile />);
  expect(screen.getByText('Loading')).toBeInTheDocument();
  expect(screen.getByText('John')).toBeInTheDocument(); // May fail
});

// Fixed - proper async handling
it('shows loading then data', async () => {
  render(<UserProfile />);
  expect(screen.getByText('Loading')).toBeInTheDocument();
  await waitFor(() => {
    expect(screen.getByText('John')).toBeInTheDocument();
  });
});

2. Non-deterministic Data

// Flaky - random data
it('sorts users alphabetically', () => {
  const users = [createUser(), createUser(), createUser()];
  // Names are random, order unpredictable
});

// Fixed - deterministic data
it('sorts users alphabetically', () => {
  const users = [
    createUser({ name: 'Charlie' }),
    createUser({ name: 'Alice' }),
    createUser({ name: 'Bob' }),
  ];
  const sorted = sortUsers(users);
  expect(sorted.map(u => u.name)).toEqual(['Alice', 'Bob', 'Charlie']);
});

3. Test Order Dependencies

// Flaky - relies on previous test
describe('Counter', () => {
  const counter = new Counter(); // Shared instance!

  it('increments', () => {
    counter.increment();
    expect(counter.value).toBe(1);
  });

  it('starts at zero', () => {
    expect(counter.value).toBe(0); // Fails! Value is 1
  });
});

// Fixed - fresh instance per test
describe('Counter', () => {
  let counter: Counter;

  beforeEach(() => {
    counter = new Counter();
  });

  it('increments', () => {
    counter.increment();
    expect(counter.value).toBe(1);
  });

  it('starts at zero', () => {
    expect(counter.value).toBe(0); // Passes
  });
});

4. Network/External Dependencies

// Flaky - real network call
it('fetches data', async () => {
  const data = await fetch('https://api.example.com/data');
  expect(data).toBeDefined();
});

// Fixed - mock the network
it('fetches data', async () => {
  server.use(
    rest.get('https://api.example.com/data', (req, res, ctx) =>
      res(ctx.json({ value: 42 }))
    )
  );

  const data = await fetchData();
  expect(data.value).toBe(42);
});

Flaky Test Detection

// jest.config.js
module.exports = {
  // Run each test multiple times to detect flakiness
  testEnvironment: 'jsdom',

  // Add reporters to track flaky tests
  reporters: [
    'default',
    ['jest-junit', { outputDirectory: './reports' }],
  ],
};

// Run tests multiple times
// npx jest --runInBand --testTimeout=10000 --repeat=5

Quarantine Strategy

1. Identify - Track tests that fail randomly 2. Quarantine - Move to separate suite, run separately 3. Fix - Investigate and fix root cause 4. Restore - Move back to main suite

// Temporarily skip flaky test
it.skip('flaky test to fix', () => {
  // TODO: Fix timing issue in #123
});

// Or run only when investigating
it.todo('investigate flaky behavior');

---

Code Review for Testability

Questions to ask during code review to ensure testable code.

Testability Checklist

Functions and Methods:

• [ ] Does it have a single responsibility?
• [ ] Are dependencies injected?
• [ ] Can it be tested without mocking internals?
• [ ] Does it return a value or have observable side effects?

Components:

• [ ] Are props descriptive and minimal?
• [ ] Can behavior be triggered via user events?
• [ ] Are loading/error states exposed?
• [ ] Can it be rendered without a full app context?

State Management:

• [ ] Is state minimal and derived where possible?
• [ ] Can state changes be triggered and observed?
• [ ] Are side effects separated from reducers?

Review Comments

Before:

// Hard to test - embedded dependency
function processPayment(order: Order) {
  const stripe = new Stripe(process.env.STRIPE_KEY);
  return stripe.charges.create({
    amount: order.total,
    currency: 'usd',
  });
}

Review Comment:

Consider injecting the payment processor to improve testability:

```typescript

function processPayment(order: Order, processor: PaymentProcessor) {

return processor.charge(order.total, 'usd');

}

```

This allows testing with a mock processor without hitting Stripe's API.

---

Test Maintenance Strategies

Keep tests maintainable as the codebase evolves.

Reducing Duplication

Use helpers for common assertions:

// __tests__/helpers/assertions.ts
export function expectLoadingState(container: HTMLElement) {
  expect(within(container).getByRole('progressbar')).toBeInTheDocument();
}

export function expectErrorState(container: HTMLElement, message: string) {
  expect(within(container).getByRole('alert')).toHaveTextContent(message);
}

// Usage
it('shows loading state', () => {
  render(<DataList />);
  expectLoadingState(screen.getByTestId('data-list'));
});

Use factory functions:

// Instead of repeating setup
function renderWithUser(ui: ReactElement, user = createUser()) {
  return {
    user,
    ...render(<AuthProvider user={user}>{ui}</AuthProvider>),
  };
}

Updating Tests When Code Changes

Scenario: Renaming a prop

// Old component
<Button onClick={handleClick} />

// New component
<Button onPress={handleClick} />

// Find and update all tests
// grep -r "onClick" __tests__/ --include="*.test.tsx"

Scenario: Changing API response shape

// Update factory first
export function createUserResponse(overrides = {}) {
  return {
    user: {  // New nested structure
      id: '1',
      name: 'Test User',
      ...overrides,
    },
  };
}

// Tests automatically get new shape

When to Delete Tests

• Redundant coverage - Multiple tests testing the same thing
• Testing implementation - Tests that break on refactor
• Obsolete features - Tests for removed functionality
• Flaky beyond repair - Tests that can't be stabilized

Test Documentation

/**
 * @group integration
 * @requires database
 *
 * Tests for the order processing workflow.
 * These tests require a running PostgreSQL instance.
 *
 * Setup: docker-compose up -d postgres
 */
describe('OrderProcessor', () => {
  /**
   * Verifies that orders with backordered items
   * are split into separate fulfillment batches.
   *
   * Related: JIRA-1234
   */
  it('splits orders with backordered items', () => {});
});

---

Debugging Failed Tests

Techniques for investigating test failures.

Jest Debugging

Run single test:

# By name pattern
npx jest -t "should validate email"

# By file
npx jest src/utils/__tests__/validation.test.ts

# Watch mode for iteration
npx jest --watch

Debug with Node inspector:

node --inspect-brk node_modules/.bin/jest --runInBand
# Open chrome://inspect in Chrome

Verbose output:

npx jest --verbose --no-coverage

React Testing Library Debugging

it('renders user profile', async () => {
  render(<UserProfile userId="123" />);

  // Print current DOM
  screen.debug();

  // Print specific element
  screen.debug(screen.getByRole('heading'));

  // Log accessible roles
  screen.logTestingPlaygroundURL(); // Opens interactive playground

  // Check what queries would match
  const element = screen.getByRole('button');
  console.log(prettyDOM(element));
});

Playwright Debugging

# Debug mode - opens browser with inspector
npx playwright test --debug

# UI mode - visual test runner
npx playwright test --ui

# Headed mode - see browser
npx playwright test --headed

# Trace viewer after failure
npx playwright show-trace trace.zip

Pause in test:

test('debug this', async ({ page }) => {
  await page.goto('/');
  await page.pause(); // Opens inspector
  await page.click('button');
});

Common Failure Patterns

Investigating Flaky Failures

// Add logging for intermittent failures
it('processes order', async () => {
  console.log('Test started at', Date.now());

  const order = await createOrder();
  console.log('Order created:', order.id);

  const result = await processOrder(order);
  console.log('Process result:', result);

  expect(result.status).toBe('completed');
});

---

Quality Metrics and KPIs

Measure test suite effectiveness and track quality improvements.

Key Metrics

Coverage Metrics:

Test Suite Health:

Defect Metrics:

Dashboard Example

// scripts/test-metrics.ts
import { readCoverageReport } from './utils';

const coverage = readCoverageReport('./coverage/coverage-summary.json');
const testResults = readTestReport('./reports/jest-results.json');

const metrics = {
  coverage: {
    lines: coverage.total.lines.pct,
    branches: coverage.total.branches.pct,
    functions: coverage.total.functions.pct,
  },
  tests: {
    total: testResults.numTotalTests,
    passed: testResults.numPassedTests,
    failed: testResults.numFailedTests,
    passRate: (testResults.numPassedTests / testResults.numTotalTests) * 100,
  },
  execution: {
    duration: testResults.testResults.reduce((sum, r) => sum + r.duration, 0),
  },
};

console.log('Test Metrics:', JSON.stringify(metrics, null, 2));

CI Quality Gates

# .github/workflows/quality.yml
name: Quality Gates

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4

      - run: npm ci
      - run: npm test -- --coverage

      # Coverage gate
      - name: Check coverage
        run: |
          coverage=$(jq '.total.lines.pct' coverage/coverage-summary.json)
          if (( $(echo "$coverage < 80" | bc -l) )); then
            echo "Coverage $coverage% is below 80% threshold"
            exit 1
          fi

      # Test count gate
      - name: Check test count
        run: |
          tests=$(jq '.numTotalTests' reports/test-results.json)
          if [ "$tests" -lt 100 ]; then
            echo "Test count $tests is below minimum of 100"
            exit 1
          fi

Trend Tracking

Track metrics over time to identify trends:

// Weekly metrics collection
{
  "week": "2024-W03",
  "coverage": {
    "lines": 82.4,
    "branches": 76.1,
    "trend": "+1.2%"  // vs previous week
  },
  "tests": {
    "total": 487,
    "new": 23,
    "removed": 5
  },
  "execution": {
    "avgDuration": 245,  // seconds
    "trend": "-12s"
  },
  "flaky": {
    "count": 3,
    "rate": 0.6
  }
}

---

Summary

1. Write testable code - Inject dependencies, use pure functions, separate concerns 2. Name tests clearly - Describe behavior, not implementation 3. Follow AAA pattern - Arrange, Act, Assert for clear structure 4. Isolate tests - Fresh state, reset mocks, no dependencies between tests 5. Fix flaky tests - Handle timing, use deterministic data, mock externals 6. Review for testability - Check during code review, not after 7. Maintain tests - Reduce duplication, update with code changes 8. Debug systematically - Use debug tools, log strategically 9. Measure quality - Track coverage, pass rate, execution time

QA Workflows and Tools

Read this when generating tests, analyzing coverage, scaffolding E2E suites, or looking up the common test patterns and commands — the quick start, tool overviews, step-by-step workflows, pattern snippets, troubleshooting, and success criteria.

Quick Start

# Generate Jest test stubs for React components
python scripts/test_suite_generator.py src/components/ --output __tests__/

# Analyze test coverage from Jest/Istanbul reports
python scripts/coverage_analyzer.py coverage/coverage-final.json --threshold 80

# Scaffold Playwright E2E tests for Next.js routes
python scripts/e2e_test_scaffolder.py src/app/ --output e2e/

---

Tools Overview

1. Test Suite Generator

Scans React/TypeScript components and generates Jest + React Testing Library test stubs with proper structure.

Input: Source directory containing React components Output: Test files with describe blocks, render tests, interaction tests

Usage:

# Basic usage - scan components and generate tests
python scripts/test_suite_generator.py src/components/ --output __tests__/

# Output:
# Scanning: src/components/
# Found 24 React components
#
# Generated tests:
#   __tests__/Button.test.tsx (render, click handler, disabled state)
#   __tests__/Modal.test.tsx (render, open/close, keyboard events)
#   __tests__/Form.test.tsx (render, validation, submission)
#   ...
#
# Summary: 24 test files, 87 test cases

# Include accessibility tests
python scripts/test_suite_generator.py src/ --output __tests__/ --include-a11y

# Generate with custom template
python scripts/test_suite_generator.py src/ --template custom-template.tsx

Supported Patterns:

• Functional components with hooks
• Components with Context providers
• Components with data fetching
• Form components with validation

---

2. Coverage Analyzer

Parses Jest/Istanbul coverage reports and identifies gaps, uncovered branches, and provides actionable recommendations.

Input: Coverage report (JSON or LCOV format) Output: Coverage analysis with recommendations

Usage:

# Analyze coverage report
python scripts/coverage_analyzer.py coverage/coverage-final.json

# Output:
# === Coverage Analysis Report ===
# Overall: 72.4% (target: 80%)
#
# BY TYPE:
#   Statements: 74.2%
#   Branches: 68.1%
#   Functions: 71.8%
#   Lines: 73.5%
#
# CRITICAL GAPS (uncovered business logic):
#   src/services/payment.ts:45-67 - Payment processing
#   src/hooks/useAuth.ts:23-41 - Authentication flow
#
# RECOMMENDATIONS:
#   1. Add tests for payment service error handling
#   2. Cover authentication edge cases
#   3. Test form validation branches
#
# Files below threshold (80%):
#   src/components/Checkout.tsx: 45%
#   src/services/api.ts: 62%

# Enforce threshold (exit 1 if below)
python scripts/coverage_analyzer.py coverage/ --threshold 80 --strict

# Generate HTML report
python scripts/coverage_analyzer.py coverage/ --format html --output report.html

---

3. E2E Test Scaffolder

Scans Next.js pages/app directory and generates Playwright test files with common interactions.

Input: Next.js pages or app directory Output: Playwright test files organized by route

Usage:

# Scaffold E2E tests for Next.js App Router
python scripts/e2e_test_scaffolder.py src/app/ --output e2e/

# Output:
# Scanning: src/app/
# Found 12 routes
#
# Generated E2E tests:
#   e2e/home.spec.ts (navigation, hero section)
#   e2e/auth/login.spec.ts (form submission, validation)
#   e2e/auth/register.spec.ts (registration flow)
#   e2e/dashboard.spec.ts (authenticated routes)
#   e2e/products/[id].spec.ts (dynamic routes)
#   ...
#
# Generated: playwright.config.ts
# Generated: e2e/fixtures/auth.ts

# Include Page Object Model classes
python scripts/e2e_test_scaffolder.py src/app/ --output e2e/ --include-pom

# Generate for specific routes
python scripts/e2e_test_scaffolder.py src/app/ --routes "/login,/dashboard,/checkout"

---

QA Workflows

Unit Test Generation Workflow

Use when setting up tests for new or existing React components.

Step 1: Scan project for untested components

python scripts/test_suite_generator.py src/components/ --scan-only

Step 2: Generate test stubs

python scripts/test_suite_generator.py src/components/ --output __tests__/

Step 3: Review and customize generated tests

// __tests__/Button.test.tsx (generated)
import { render, screen, fireEvent } from '@testing-library/react';
import { Button } from '../src/components/Button';

describe('Button', () => {
  it('renders with label', () => {
    render(<Button>Click me</Button>);
    expect(screen.getByRole('button', { name: /click me/i })).toBeInTheDocument();
  });

  it('calls onClick when clicked', () => {
    const handleClick = jest.fn();
    render(<Button onClick={handleClick}>Click</Button>);
    fireEvent.click(screen.getByRole('button'));
    expect(handleClick).toHaveBeenCalledTimes(1);
  });

  // TODO: Add your specific test cases
});

Step 4: Run tests and check coverage

npm test -- --coverage
python scripts/coverage_analyzer.py coverage/coverage-final.json

---

Coverage Analysis Workflow

Use when improving test coverage or preparing for release.

Step 1: Generate coverage report

npm test -- --coverage --coverageReporters=json

Step 2: Analyze coverage gaps

python scripts/coverage_analyzer.py coverage/coverage-final.json --threshold 80

Step 3: Identify critical paths

python scripts/coverage_analyzer.py coverage/ --critical-paths

Step 4: Generate missing test stubs

python scripts/test_suite_generator.py src/ --uncovered-only --output __tests__/

Step 5: Verify improvement

npm test -- --coverage
python scripts/coverage_analyzer.py coverage/ --compare previous-coverage.json

---

E2E Test Setup Workflow

Use when setting up Playwright for a Next.js project.

Step 1: Initialize Playwright (if not installed)

npm init playwright@latest

Step 2: Scaffold E2E tests from routes

python scripts/e2e_test_scaffolder.py src/app/ --output e2e/

Step 3: Configure authentication fixtures

// e2e/fixtures/auth.ts (generated)
import { test as base } from '@playwright/test';

export const test = base.extend({
  authenticatedPage: async ({ page }, use) => {
    await page.goto('/login');
    await page.fill('[name="email"]', 'test@example.com');
    await page.fill('[name="password"]', 'password');
    await page.click('button[type="submit"]');
    await page.waitForURL('/dashboard');
    await use(page);
  },
});

Step 4: Run E2E tests

npx playwright test
npx playwright show-report

Step 5: Add to CI pipeline

# .github/workflows/e2e.yml
- name: Run E2E tests
  run: npx playwright test
- name: Upload report
  uses: actions/upload-artifact@v3
  with:
    name: playwright-report
    path: playwright-report/

---

Common Patterns Quick Reference

React Testing Library Queries

// Preferred (accessible)
screen.getByRole('button', { name: /submit/i })
screen.getByLabelText(/email/i)
screen.getByPlaceholderText(/search/i)

// Fallback
screen.getByTestId('custom-element')

Async Testing

// Wait for element
await screen.findByText(/loaded/i);

// Wait for removal
await waitForElementToBeRemoved(() => screen.queryByText(/loading/i));

// Wait for condition
await waitFor(() => {
  expect(mockFn).toHaveBeenCalled();
});

Mocking with MSW

import { rest } from 'msw';
import { setupServer } from 'msw/node';

const server = setupServer(
  rest.get('/api/users', (req, res, ctx) => {
    return res(ctx.json([{ id: 1, name: 'John' }]));
  })
);

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

Playwright Locators

// Preferred
page.getByRole('button', { name: 'Submit' })
page.getByLabel('Email')
page.getByText('Welcome')

// Chaining
page.getByRole('listitem').filter({ hasText: 'Product' })

Coverage Thresholds (jest.config.js)

module.exports = {
  coverageThreshold: {
    global: {
      branches: 80,
      functions: 80,
      lines: 80,
      statements: 80,
    },
  },
};

---

Common Commands

# Jest
npm test                           # Run all tests
npm test -- --watch                # Watch mode
npm test -- --coverage             # With coverage
npm test -- Button.test.tsx        # Single file

# Playwright
npx playwright test                # Run all E2E tests
npx playwright test --ui           # UI mode
npx playwright test --debug        # Debug mode
npx playwright codegen             # Generate tests

# Coverage
npm test -- --coverage --coverageReporters=lcov,json
python scripts/coverage_analyzer.py coverage/coverage-final.json

---

Troubleshooting

---

Success Criteria

• Code coverage above 80% across statements, branches, functions, and lines for all non-trivial source files.
• Zero critical coverage gaps in authentication, payment, and security modules as reported by coverage_analyzer.py --critical-paths.
• 100% of React components have at least a render test confirming they mount without crashing.
• All E2E tests pass on Chromium, Firefox, and WebKit in CI before merge to main.
• Branch coverage above 75% for service layers, API handlers, and middleware modules.
• No flaky tests -- every test in the suite produces deterministic results across 3 consecutive CI runs.
• Test generation covers all detected routes -- the E2E scaffolder accounts for every page route in the Next.js application, including dynamic segments.

Test Automation Patterns for React and Next.js

Reusable patterns for structuring test code, mocking dependencies, and handling async operations.

---

Table of Contents

• Page Object Model for React
• Test Data Factories
• Fixture Management
• Mocking Strategies
• Custom Test Utilities
• Async Testing Patterns
• Snapshot Testing Guidelines

---

Page Object Model for React

The Page Object Model (POM) encapsulates page interactions into reusable classes, reducing test maintenance.

Playwright Page Objects

// e2e/pages/LoginPage.ts
import { Page, Locator, expect } from '@playwright/test';

export class LoginPage {
  readonly page: Page;
  readonly emailInput: Locator;
  readonly passwordInput: Locator;
  readonly submitButton: Locator;
  readonly errorMessage: Locator;

  constructor(page: Page) {
    this.page = page;
    this.emailInput = page.getByLabel('Email');
    this.passwordInput = page.getByLabel('Password');
    this.submitButton = page.getByRole('button', { name: 'Sign in' });
    this.errorMessage = page.getByRole('alert');
  }

  async goto() {
    await this.page.goto('/login');
  }

  async login(email: string, password: string) {
    await this.emailInput.fill(email);
    await this.passwordInput.fill(password);
    await this.submitButton.click();
  }

  async expectError(message: string) {
    await expect(this.errorMessage).toContainText(message);
  }

  async expectRedirectToDashboard() {
    await expect(this.page).toHaveURL('/dashboard');
  }
}

Usage in Tests:

// e2e/auth.spec.ts
import { test, expect } from '@playwright/test';
import { LoginPage } from './pages/LoginPage';

test.describe('Authentication', () => {
  let loginPage: LoginPage;

  test.beforeEach(async ({ page }) => {
    loginPage = new LoginPage(page);
    await loginPage.goto();
  });

  test('successful login redirects to dashboard', async () => {
    await loginPage.login('user@example.com', 'password123');
    await loginPage.expectRedirectToDashboard();
  });

  test('invalid credentials show error', async () => {
    await loginPage.login('user@example.com', 'wrongpassword');
    await loginPage.expectError('Invalid credentials');
  });
});

Component Object Model (React Testing Library)

// __tests__/objects/LoginFormObject.ts
import { screen, fireEvent, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';

export class LoginFormObject {
  get emailInput() {
    return screen.getByLabelText(/email/i);
  }

  get passwordInput() {
    return screen.getByLabelText(/password/i);
  }

  get submitButton() {
    return screen.getByRole('button', { name: /sign in/i });
  }

  get errorMessage() {
    return screen.queryByRole('alert');
  }

  async fillEmail(email: string) {
    await userEvent.type(this.emailInput, email);
  }

  async fillPassword(password: string) {
    await userEvent.type(this.passwordInput, password);
  }

  async submit() {
    await userEvent.click(this.submitButton);
  }

  async login(email: string, password: string) {
    await this.fillEmail(email);
    await this.fillPassword(password);
    await this.submit();
  }

  async expectError(message: string) {
    await waitFor(() => {
      expect(this.errorMessage).toHaveTextContent(message);
    });
  }
}

When to Use POM

---

Test Data Factories

Factories create test data with sensible defaults, reducing boilerplate and improving maintainability.

Basic Factory Pattern

// __tests__/factories/userFactory.ts
interface User {
  id: string;
  email: string;
  name: string;
  role: 'admin' | 'user' | 'guest';
  createdAt: Date;
  preferences: {
    theme: 'light' | 'dark';
    notifications: boolean;
  };
}

let idCounter = 0;

export function createUser(overrides: Partial<User> = {}): User {
  return {
    id: `user-${++idCounter}`,
    email: `user${idCounter}@example.com`,
    name: `Test User ${idCounter}`,
    role: 'user',
    createdAt: new Date('2024-01-01'),
    preferences: {
      theme: 'light',
      notifications: true,
    },
    ...overrides,
    // Deep merge preferences if provided
    preferences: {
      theme: 'light',
      notifications: true,
      ...overrides.preferences,
    },
  };
}

// Specialized builders
export function createAdmin(overrides: Partial<User> = {}): User {
  return createUser({ role: 'admin', ...overrides });
}

export function createGuest(overrides: Partial<User> = {}): User {
  return createUser({
    role: 'guest',
    name: 'Guest',
    email: '',
    ...overrides,
  });
}

Builder Pattern for Complex Objects

// __tests__/factories/orderBuilder.ts
interface OrderItem {
  productId: string;
  quantity: number;
  price: number;
}

interface Order {
  id: string;
  userId: string;
  items: OrderItem[];
  status: 'pending' | 'processing' | 'shipped' | 'delivered';
  total: number;
  shippingAddress: Address;
  createdAt: Date;
}

export class OrderBuilder {
  private order: Partial<Order> = {};
  private items: OrderItem[] = [];

  withId(id: string): this {
    this.order.id = id;
    return this;
  }

  forUser(userId: string): this {
    this.order.userId = userId;
    return this;
  }

  withItem(productId: string, quantity: number, price: number): this {
    this.items.push({ productId, quantity, price });
    return this;
  }

  withStatus(status: Order['status']): this {
    this.order.status = status;
    return this;
  }

  shippedTo(address: Address): this {
    this.order.shippingAddress = address;
    return this;
  }

  build(): Order {
    const total = this.items.reduce(
      (sum, item) => sum + item.price * item.quantity,
      0
    );

    return {
      id: this.order.id || `order-${Date.now()}`,
      userId: this.order.userId || 'user-1',
      items: this.items,
      status: this.order.status || 'pending',
      total,
      shippingAddress: this.order.shippingAddress || createAddress(),
      createdAt: new Date(),
    };
  }
}

// Usage
const order = new OrderBuilder()
  .forUser('user-123')
  .withItem('product-1', 2, 29.99)
  .withItem('product-2', 1, 49.99)
  .withStatus('processing')
  .build();

Factory with Faker

// __tests__/factories/productFactory.ts
import { faker } from '@faker-js/faker';

interface Product {
  id: string;
  name: string;
  description: string;
  price: number;
  category: string;
  inStock: boolean;
  imageUrl: string;
}

export function createProduct(overrides: Partial<Product> = {}): Product {
  return {
    id: faker.string.uuid(),
    name: faker.commerce.productName(),
    description: faker.commerce.productDescription(),
    price: parseFloat(faker.commerce.price({ min: 10, max: 500 })),
    category: faker.commerce.department(),
    inStock: faker.datatype.boolean({ probability: 0.8 }),
    imageUrl: faker.image.url(),
    ...overrides,
  };
}

export function createProducts(count: number): Product[] {
  return Array.from({ length: count }, () => createProduct());
}

---

Fixture Management

Fixtures provide consistent test data and setup across test suites.

Playwright Fixtures

// e2e/fixtures/auth.ts
import { test as base, Page } from '@playwright/test';
import { createUser } from '../factories/userFactory';

interface AuthFixtures {
  authenticatedPage: Page;
  adminPage: Page;
  testUser: ReturnType<typeof createUser>;
}

export const test = base.extend<AuthFixtures>({
  testUser: async ({}, use) => {
    const user = createUser();
    await use(user);
  },

  authenticatedPage: async ({ page, testUser }, use) => {
    // Login via API to skip UI
    await page.request.post('/api/auth/login', {
      data: {
        email: testUser.email,
        password: 'testpassword',
      },
    });

    // Get session cookie
    const cookies = await page.context().cookies();
    await page.context().addCookies(cookies);

    await use(page);
  },

  adminPage: async ({ page }, use) => {
    const admin = createUser({ role: 'admin' });

    await page.request.post('/api/auth/login', {
      data: {
        email: admin.email,
        password: 'adminpassword',
      },
    });

    await use(page);
  },
});

export { expect } from '@playwright/test';

Using Custom Fixtures:

// e2e/dashboard.spec.ts
import { test, expect } from './fixtures/auth';

test('dashboard shows user name', async ({ authenticatedPage, testUser }) => {
  await authenticatedPage.goto('/dashboard');
  await expect(authenticatedPage.getByText(testUser.name)).toBeVisible();
});

test('admin sees admin panel', async ({ adminPage }) => {
  await adminPage.goto('/dashboard');
  await expect(adminPage.getByText('Admin Panel')).toBeVisible();
});

Jest Test Setup

// jest.setup.ts
import '@testing-library/jest-dom';
import { server } from './__tests__/mocks/server';

// Start MSW server before all tests
beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));

// Reset handlers after each test
afterEach(() => server.resetHandlers());

// Clean up after all tests
afterAll(() => server.close());

// Mock window.matchMedia
Object.defineProperty(window, 'matchMedia', {
  writable: true,
  value: jest.fn().mockImplementation(query => ({
    matches: false,
    media: query,
    onchange: null,
    addListener: jest.fn(),
    removeListener: jest.fn(),
    addEventListener: jest.fn(),
    removeEventListener: jest.fn(),
    dispatchEvent: jest.fn(),
  })),
});

// Mock IntersectionObserver
global.IntersectionObserver = class IntersectionObserver {
  constructor() {}
  observe() {}
  unobserve() {}
  disconnect() {}
};

Shared Test Data Files

// __tests__/fixtures/products.json
{
  "products": [
    {
      "id": "prod-1",
      "name": "Widget Pro",
      "price": 29.99,
      "category": "Electronics"
    },
    {
      "id": "prod-2",
      "name": "Gadget Plus",
      "price": 49.99,
      "category": "Electronics"
    }
  ]
}

// __tests__/fixtures/index.ts
import productsData from './products.json';
import usersData from './users.json';

export const fixtures = {
  products: productsData.products,
  users: usersData.users,
};

---

Mocking Strategies

MSW (Mock Service Worker) for API Mocking

MSW intercepts network requests at the service worker level, working in both browser and Node.

Handler Setup:

// __tests__/mocks/handlers.ts
import { rest } from 'msw';
import { createUser } from '../factories/userFactory';
import { createProduct } from '../factories/productFactory';

export const handlers = [
  // GET /api/users/:id
  rest.get('/api/users/:id', (req, res, ctx) => {
    const { id } = req.params;
    const user = createUser({ id: id as string });
    return res(ctx.json(user));
  }),

  // GET /api/products
  rest.get('/api/products', (req, res, ctx) => {
    const category = req.url.searchParams.get('category');
    const products = Array.from({ length: 10 }, () => createProduct());
    const filtered = category
      ? products.filter(p => p.category === category)
      : products;
    return res(ctx.json(filtered));
  }),

  // POST /api/orders
  rest.post('/api/orders', async (req, res, ctx) => {
    const body = await req.json();
    return res(
      ctx.status(201),
      ctx.json({
        id: `order-${Date.now()}`,
        ...body,
        status: 'pending',
      })
    );
  }),

  // Error simulation
  rest.get('/api/error', (req, res, ctx) => {
    return res(
      ctx.status(500),
      ctx.json({ error: 'Internal Server Error' })
    );
  }),
];

Server Setup:

// __tests__/mocks/server.ts
import { setupServer } from 'msw/node';
import { handlers } from './handlers';

export const server = setupServer(...handlers);

Overriding Handlers in Tests:

// __tests__/components/ProductList.test.tsx
import { render, screen, waitFor } from '@testing-library/react';
import { rest } from 'msw';
import { server } from '../mocks/server';
import { ProductList } from '../../src/components/ProductList';

describe('ProductList', () => {
  it('shows loading state', () => {
    render(<ProductList />);
    expect(screen.getByText('Loading...')).toBeInTheDocument();
  });

  it('renders products', async () => {
    render(<ProductList />);
    await waitFor(() => {
      expect(screen.getAllByTestId('product-card')).toHaveLength(10);
    });
  });

  it('shows error state on API failure', async () => {
    server.use(
      rest.get('/api/products', (req, res, ctx) => {
        return res(ctx.status(500));
      })
    );

    render(<ProductList />);
    await waitFor(() => {
      expect(screen.getByText(/error loading products/i)).toBeInTheDocument();
    });
  });

  it('shows empty state when no products', async () => {
    server.use(
      rest.get('/api/products', (req, res, ctx) => {
        return res(ctx.json([]));
      })
    );

    render(<ProductList />);
    await waitFor(() => {
      expect(screen.getByText('No products found')).toBeInTheDocument();
    });
  });
});

Jest Module Mocking

// Mocking a module
jest.mock('../../src/services/analytics', () => ({
  trackEvent: jest.fn(),
  trackPageView: jest.fn(),
  setUser: jest.fn(),
}));

// Mocking with implementation
jest.mock('next/router', () => ({
  useRouter: jest.fn().mockReturnValue({
    pathname: '/test',
    push: jest.fn(),
    replace: jest.fn(),
    query: {},
  }),
}));

// Partial mock (keep some real implementations)
jest.mock('../../src/utils/helpers', () => ({
  ...jest.requireActual('../../src/utils/helpers'),
  sendEmail: jest.fn().mockResolvedValue({ success: true }),
}));

Mocking Hooks

// __tests__/hooks/useAuth.test.tsx
import { renderHook, act } from '@testing-library/react';
import { useAuth } from '../../src/hooks/useAuth';
import * as authService from '../../src/services/auth';

jest.mock('../../src/services/auth');

const mockAuthService = authService as jest.Mocked<typeof authService>;

describe('useAuth', () => {
  beforeEach(() => {
    jest.clearAllMocks();
  });

  it('logs in user successfully', async () => {
    const mockUser = { id: '1', email: 'test@example.com' };
    mockAuthService.login.mockResolvedValue(mockUser);

    const { result } = renderHook(() => useAuth());

    await act(async () => {
      await result.current.login('test@example.com', 'password');
    });

    expect(result.current.user).toEqual(mockUser);
    expect(result.current.isAuthenticated).toBe(true);
  });

  it('handles login error', async () => {
    mockAuthService.login.mockRejectedValue(new Error('Invalid credentials'));

    const { result } = renderHook(() => useAuth());

    await act(async () => {
      try {
        await result.current.login('test@example.com', 'wrong');
      } catch (e) {
        // Expected
      }
    });

    expect(result.current.user).toBeNull();
    expect(result.current.error).toBe('Invalid credentials');
  });
});

---

Custom Test Utilities

Render with Providers

// __tests__/utils/renderWithProviders.tsx
import React, { ReactElement } from 'react';
import { render, RenderOptions } from '@testing-library/react';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ThemeProvider } from '../../src/contexts/ThemeContext';
import { AuthProvider } from '../../src/contexts/AuthContext';

interface ExtendedRenderOptions extends Omit<RenderOptions, 'wrapper'> {
  initialUser?: User | null;
  theme?: 'light' | 'dark';
}

export function renderWithProviders(
  ui: ReactElement,
  {
    initialUser = null,
    theme = 'light',
    ...renderOptions
  }: ExtendedRenderOptions = {}
) {
  const queryClient = new QueryClient({
    defaultOptions: {
      queries: {
        retry: false, // Disable retries in tests
      },
    },
  });

  function Wrapper({ children }: { children: React.ReactNode }) {
    return (
      <QueryClientProvider client={queryClient}>
        <AuthProvider initialUser={initialUser}>
          <ThemeProvider initialTheme={theme}>
            {children}
          </ThemeProvider>
        </AuthProvider>
      </QueryClientProvider>
    );
  }

  return {
    ...render(ui, { wrapper: Wrapper, ...renderOptions }),
    queryClient,
  };
}

// Re-export everything from RTL
export * from '@testing-library/react';
export { renderWithProviders as render };

Usage:

// __tests__/components/Dashboard.test.tsx
import { render, screen } from '../utils/renderWithProviders';
import { Dashboard } from '../../src/components/Dashboard';
import { createUser } from '../factories/userFactory';

describe('Dashboard', () => {
  it('shows user greeting when authenticated', () => {
    const user = createUser({ name: 'John Doe' });
    render(<Dashboard />, { initialUser: user });
    expect(screen.getByText('Hello, John Doe')).toBeInTheDocument();
  });

  it('shows login prompt when not authenticated', () => {
    render(<Dashboard />, { initialUser: null });
    expect(screen.getByText('Please log in')).toBeInTheDocument();
  });

  it('applies dark theme', () => {
    render(<Dashboard />, { theme: 'dark' });
    expect(document.body).toHaveClass('dark');
  });
});

Custom Matchers

// __tests__/utils/customMatchers.ts
import { expect } from '@playwright/test';

expect.extend({
  async toHaveLoadedSuccessfully(page) {
    const hasNoErrors = await page.evaluate(() => {
      return !document.querySelector('[data-error]');
    });
    const isLoaded = await page.evaluate(() => {
      return document.readyState === 'complete';
    });

    return {
      pass: hasNoErrors && isLoaded,
      message: () =>
        hasNoErrors
          ? 'Page loaded with errors'
          : 'Page did not finish loading',
    };
  },

  toBeWithinRange(received, floor, ceiling) {
    const pass = received >= floor && received <= ceiling;
    return {
      pass,
      message: () =>
        `expected ${received} ${pass ? 'not ' : ''}to be within range ${floor} - ${ceiling}`,
    };
  },
});

// Type declarations
declare global {
  namespace PlaywrightTest {
    interface Matchers<R> {
      toHaveLoadedSuccessfully(): Promise<R>;
    }
  }
}

---

Async Testing Patterns

Waiting for Elements

// Preferred: Use findBy* (waits automatically)
const element = await screen.findByText('Loaded');

// Wait for element to appear
await waitFor(() => {
  expect(screen.getByText('Loaded')).toBeInTheDocument();
});

// Wait for element to disappear
await waitForElementToBeRemoved(() => screen.queryByText('Loading...'));

// Wait with custom timeout
await waitFor(
  () => {
    expect(mockFn).toHaveBeenCalled();
  },
  { timeout: 5000 }
);

Testing Async State Changes

// __tests__/components/AsyncButton.test.tsx
import { render, screen, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { AsyncButton } from '../../src/components/AsyncButton';

describe('AsyncButton', () => {
  it('shows loading state during async operation', async () => {
    const user = userEvent.setup();
    const onClickMock = jest.fn().mockImplementation(
      () => new Promise(resolve => setTimeout(resolve, 100))
    );

    render(<AsyncButton onClick={onClickMock}>Submit</AsyncButton>);

    // Initial state
    expect(screen.getByRole('button')).toHaveTextContent('Submit');
    expect(screen.getByRole('button')).not.toBeDisabled();

    // Click and verify loading state
    await user.click(screen.getByRole('button'));
    expect(screen.getByRole('button')).toHaveTextContent('Loading...');
    expect(screen.getByRole('button')).toBeDisabled();

    // Wait for completion
    await waitFor(() => {
      expect(screen.getByRole('button')).toHaveTextContent('Submit');
      expect(screen.getByRole('button')).not.toBeDisabled();
    });
  });
});

Testing Debounced/Throttled Functions

// __tests__/components/SearchInput.test.tsx
import { render, screen, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { SearchInput } from '../../src/components/SearchInput';

// Use fake timers for debounce testing
jest.useFakeTimers();

describe('SearchInput', () => {
  it('debounces search calls', async () => {
    const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime });
    const onSearchMock = jest.fn();

    render(<SearchInput onSearch={onSearchMock} debounceMs={300} />);

    // Type quickly
    await user.type(screen.getByRole('textbox'), 'test');

    // No calls yet (debouncing)
    expect(onSearchMock).not.toHaveBeenCalled();

    // Advance timers past debounce threshold
    jest.advanceTimersByTime(300);

    // Now it should be called once with final value
    expect(onSearchMock).toHaveBeenCalledTimes(1);
    expect(onSearchMock).toHaveBeenCalledWith('test');
  });
});

Playwright Async Patterns

// e2e/async-patterns.spec.ts
import { test, expect } from '@playwright/test';

test('waits for API response', async ({ page }) => {
  // Wait for specific response
  const responsePromise = page.waitForResponse('/api/data');
  await page.click('button.load-data');
  const response = await responsePromise;
  expect(response.status()).toBe(200);
});

test('waits for navigation', async ({ page }) => {
  await page.goto('/');
  await Promise.all([
    page.waitForURL('/dashboard'),
    page.click('a.dashboard-link'),
  ]);
});

test('waits for network idle', async ({ page }) => {
  await page.goto('/', { waitUntil: 'networkidle' });
});

test('retries assertion until pass', async ({ page }) => {
  // Auto-retrying assertion
  await expect(page.locator('.counter')).toHaveText('10', { timeout: 5000 });
});

---

Snapshot Testing Guidelines

When to Use Snapshots

Component Snapshots

// __tests__/components/Button.test.tsx
import { render } from '@testing-library/react';
import { Button } from '../../src/components/Button';

describe('Button snapshots', () => {
  it('renders primary variant', () => {
    const { container } = render(
      <Button variant="primary">Click me</Button>
    );
    expect(container.firstChild).toMatchSnapshot();
  });

  it('renders secondary variant', () => {
    const { container } = render(
      <Button variant="secondary">Click me</Button>
    );
    expect(container.firstChild).toMatchSnapshot();
  });

  it('renders disabled state', () => {
    const { container } = render(
      <Button disabled>Click me</Button>
    );
    expect(container.firstChild).toMatchSnapshot();
  });
});

Inline Snapshots

// Good for small, stable outputs
it('formats date correctly', () => {
  const result = formatDate(new Date('2024-01-15'));
  expect(result).toMatchInlineSnapshot(`"January 15, 2024"`);
});

it('generates expected error message', () => {
  const error = new ValidationError('email', 'Invalid format');
  expect(error.message).toMatchInlineSnapshot(
    `"Validation failed for 'email': Invalid format"`
  );
});

Snapshot Best Practices

1. Keep snapshots small - Snapshot specific elements, not entire pages 2. Use inline snapshots for small outputs - Easier to review in code 3. Review snapshot changes carefully - Don't blindly update 4. Avoid snapshots for dynamic content - Filter out timestamps, IDs 5. Combine with other assertions - Snapshots complement, not replace

// Filtering dynamic content from snapshots
it('renders user card', () => {
  const { container } = render(<UserCard user={mockUser} />);

  // Remove dynamic elements before snapshot
  const card = container.firstChild;
  const timestamp = card.querySelector('.timestamp');
  timestamp?.remove();

  expect(card).toMatchSnapshot();
});

---

Summary

1. Use Page Objects for complex, reusable page interactions 2. Build factories for consistent test data creation 3. Leverage MSW for realistic API mocking 4. Create custom render utilities for provider wrapping 5. Master async patterns to avoid flaky tests 6. Use snapshots wisely for stable, static content only

Testing Strategies for React and Next.js Applications

Comprehensive guide to test architecture, coverage targets, and CI/CD integration patterns.

---

Table of Contents

• The Testing Pyramid
• Testing Types Deep Dive
• Coverage Targets and Thresholds
• Test Organization Patterns
• CI/CD Integration Strategies
• Testing Decision Framework

---

The Testing Pyramid

The testing pyramid guides how to distribute testing effort across different test types for optimal ROI.

Classic Pyramid Structure

        /\
       /  \      E2E Tests (5-10%)
      /----\     - User journey validation
     /      \    - Critical path coverage
    /--------\   Integration Tests (20-30%)
   /          \  - Component interactions
  /            \ - API integration
 /--------------\ Unit Tests (60-70%)
/                \ - Individual functions
------------------  - Isolated components

React/Next.js Adapted Pyramid

For frontend applications, the pyramid shifts slightly:

Why This Distribution?

Unit tests are fast and cheap:

• Execute in milliseconds
• Pinpoint failures precisely
• Easy to maintain
• Run on every commit

Integration tests balance coverage and cost:

• Test realistic scenarios
• Catch component interaction bugs
• Moderate execution time
• Run on every PR

E2E tests are expensive but essential:

• Validate real user experience
• Catch deployment issues
• Slow and brittle
• Run on staging/production

---

Testing Types Deep Dive

Unit Testing

Purpose: Verify individual units of code work correctly in isolation.

What to Unit Test:

• Pure utility functions
• Custom hooks (with renderHook)
• Individual component rendering
• State reducers
• Validation logic
• Data transformers

Example: Testing a Pure Function

// utils/formatPrice.ts
export function formatPrice(cents: number, currency = 'USD'): string {
  const formatter = new Intl.NumberFormat('en-US', {
    style: 'currency',
    currency,
  });
  return formatter.format(cents / 100);
}

// utils/formatPrice.test.ts
describe('formatPrice', () => {
  it('formats cents to USD by default', () => {
    expect(formatPrice(1999)).toBe('$19.99');
  });

  it('handles zero', () => {
    expect(formatPrice(0)).toBe('$0.00');
  });

  it('supports different currencies', () => {
    expect(formatPrice(1999, 'EUR')).toContain('€');
  });

  it('handles large numbers', () => {
    expect(formatPrice(100000000)).toBe('$1,000,000.00');
  });
});

Example: Testing a Custom Hook

// hooks/useCounter.ts
export function useCounter(initial = 0) {
  const [count, setCount] = useState(initial);
  const increment = () => setCount(c => c + 1);
  const decrement = () => setCount(c => c - 1);
  const reset = () => setCount(initial);
  return { count, increment, decrement, reset };
}

// hooks/useCounter.test.ts
import { renderHook, act } from '@testing-library/react';
import { useCounter } from './useCounter';

describe('useCounter', () => {
  it('starts with initial value', () => {
    const { result } = renderHook(() => useCounter(5));
    expect(result.current.count).toBe(5);
  });

  it('increments count', () => {
    const { result } = renderHook(() => useCounter(0));
    act(() => result.current.increment());
    expect(result.current.count).toBe(1);
  });

  it('decrements count', () => {
    const { result } = renderHook(() => useCounter(5));
    act(() => result.current.decrement());
    expect(result.current.count).toBe(4);
  });

  it('resets to initial value', () => {
    const { result } = renderHook(() => useCounter(10));
    act(() => result.current.increment());
    act(() => result.current.reset());
    expect(result.current.count).toBe(10);
  });
});

Integration Testing

Purpose: Verify multiple units work together correctly.

What to Integration Test:

• Component trees with multiple children
• Components with context providers
• Form submission flows
• API call and response handling
• State management interactions
• Router-dependent components

Example: Testing Component with API Call

// components/UserProfile.tsx
export function UserProfile({ userId }: { userId: string }) {
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    fetch(`/api/users/${userId}`)
      .then(res => res.json())
      .then(data => setUser(data))
      .catch(err => setError(err.message))
      .finally(() => setLoading(false));
  }, [userId]);

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;
  return <div>{user?.name}</div>;
}

// components/UserProfile.test.tsx
import { render, screen, waitFor } from '@testing-library/react';
import { rest } from 'msw';
import { setupServer } from 'msw/node';
import { UserProfile } from './UserProfile';

const server = setupServer(
  rest.get('/api/users/:id', (req, res, ctx) => {
    return res(ctx.json({ id: req.params.id, name: 'John Doe' }));
  })
);

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

describe('UserProfile', () => {
  it('shows loading state initially', () => {
    render(<UserProfile userId="123" />);
    expect(screen.getByText('Loading...')).toBeInTheDocument();
  });

  it('displays user name after loading', async () => {
    render(<UserProfile userId="123" />);
    await waitFor(() => {
      expect(screen.getByText('John Doe')).toBeInTheDocument();
    });
  });

  it('displays error on API failure', async () => {
    server.use(
      rest.get('/api/users/:id', (req, res, ctx) => {
        return res(ctx.status(500));
      })
    );
    render(<UserProfile userId="123" />);
    await waitFor(() => {
      expect(screen.getByText(/Error/)).toBeInTheDocument();
    });
  });
});

End-to-End Testing

Purpose: Verify complete user flows work in a real browser environment.

What to E2E Test:

• Critical business flows (checkout, signup, login)
• Cross-page navigation sequences
• Authentication flows
• Third-party integrations
• Payment processing
• Form wizards

Example: Testing Checkout Flow

// e2e/checkout.spec.ts
import { test, expect } from '@playwright/test';

test.describe('Checkout Flow', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/');
  });

  test('completes purchase successfully', async ({ page }) => {
    // Add product to cart
    await page.goto('/products/widget-pro');
    await page.getByRole('button', { name: 'Add to Cart' }).click();

    // Verify cart updated
    await expect(page.getByTestId('cart-count')).toHaveText('1');

    // Go to checkout
    await page.getByRole('link', { name: 'Checkout' }).click();

    // Fill shipping info
    await page.getByLabel('Email').fill('test@example.com');
    await page.getByLabel('Address').fill('123 Test St');
    await page.getByLabel('City').fill('Test City');
    await page.getByLabel('Zip').fill('12345');

    // Fill payment info (test card)
    await page.getByLabel('Card Number').fill('4242424242424242');
    await page.getByLabel('Expiry').fill('12/25');
    await page.getByLabel('CVC').fill('123');

    // Submit order
    await page.getByRole('button', { name: 'Place Order' }).click();

    // Verify confirmation
    await expect(page).toHaveURL(/\/orders\/\w+/);
    await expect(page.getByText('Order Confirmed')).toBeVisible();
  });

  test('shows validation errors for invalid input', async ({ page }) => {
    await page.goto('/checkout');
    await page.getByRole('button', { name: 'Place Order' }).click();

    await expect(page.getByText('Email is required')).toBeVisible();
    await expect(page.getByText('Address is required')).toBeVisible();
  });
});

Visual Regression Testing

Purpose: Catch unintended visual changes to UI components.

Tools: Playwright visual comparisons, Percy, Chromatic

Example: Visual Snapshot Test

// e2e/visual/components.spec.ts
import { test, expect } from '@playwright/test';

test.describe('Visual Regression', () => {
  test('button variants render correctly', async ({ page }) => {
    await page.goto('/storybook/button');
    await expect(page).toHaveScreenshot('button-variants.png');
  });

  test('responsive header', async ({ page }) => {
    // Desktop
    await page.setViewportSize({ width: 1280, height: 720 });
    await page.goto('/');
    await expect(page.locator('header')).toHaveScreenshot('header-desktop.png');

    // Mobile
    await page.setViewportSize({ width: 375, height: 667 });
    await expect(page.locator('header')).toHaveScreenshot('header-mobile.png');
  });
});

Accessibility Testing

Purpose: Ensure application is usable by people with disabilities.

Tools: jest-axe, @axe-core/playwright

Example: Automated A11y Testing

// Unit/Integration level with jest-axe
import { render } from '@testing-library/react';
import { axe, toHaveNoViolations } from 'jest-axe';
import { Button } from './Button';

expect.extend(toHaveNoViolations);

describe('Button accessibility', () => {
  it('has no accessibility violations', async () => {
    const { container } = render(<Button>Click me</Button>);
    const results = await axe(container);
    expect(results).toHaveNoViolations();
  });
});

// E2E level with Playwright + Axe
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test('homepage has no a11y violations', async ({ page }) => {
  await page.goto('/');
  const results = await new AxeBuilder({ page }).analyze();
  expect(results.violations).toEqual([]);
});

---

Coverage Targets and Thresholds

Recommended Thresholds by Project Type

Coverage by Code Type

High Coverage Priority (80%+):

• Business logic
• State management
• API handlers
• Form validation
• Authentication/authorization
• Payment processing

Medium Coverage Priority (60-80%):

• UI components
• Utility functions
• Data transformers
• Custom hooks

Lower Coverage Priority (40-60%):

• Static pages
• Simple wrappers
• Configuration files
• Types/interfaces

Jest Coverage Configuration

// jest.config.js
module.exports = {
  collectCoverageFrom: [
    'src/**/*.{ts,tsx}',
    '!src/**/*.d.ts',
    '!src/**/*.stories.{ts,tsx}',
    '!src/**/index.{ts,tsx}', // barrel files
    '!src/types/**',
  ],
  coverageThreshold: {
    global: {
      statements: 80,
      branches: 75,
      functions: 80,
      lines: 80,
    },
    // Higher thresholds for critical paths
    './src/services/payment/': {
      statements: 95,
      branches: 90,
      functions: 95,
      lines: 95,
    },
    './src/services/auth/': {
      statements: 90,
      branches: 85,
      functions: 90,
      lines: 90,
    },
  },
  coverageReporters: ['text', 'lcov', 'html', 'json'],
};

---

Test Organization Patterns

Co-located Tests (Recommended for React)

src/
├── components/
│   ├── Button/
│   │   ├── Button.tsx
│   │   ├── Button.test.tsx      # Unit tests
│   │   ├── Button.stories.tsx   # Storybook
│   │   └── index.ts
│   └── Form/
│       ├── Form.tsx
│       ├── Form.test.tsx
│       └── Form.integration.test.tsx  # Integration tests
├── hooks/
│   ├── useAuth.ts
│   └── useAuth.test.ts
└── utils/
    ├── formatters.ts
    └── formatters.test.ts

Separate Test Directory

src/
├── components/
├── hooks/
└── utils/

__tests__/
├── unit/
│   ├── components/
│   ├── hooks/
│   └── utils/
├── integration/
│   └── flows/
└── fixtures/
    ├── users.json
    └── products.json

e2e/
├── specs/
│   ├── auth.spec.ts
│   └── checkout.spec.ts
├── fixtures/
│   └── auth.ts
└── pages/      # Page Object Models
    ├── LoginPage.ts
    └── CheckoutPage.ts

Test File Naming Conventions

---

CI/CD Integration Strategies

Pipeline Stages

# .github/workflows/test.yml
name: Test Pipeline

on:
  push:
    branches: [main, dev]
  pull_request:
    branches: [main, dev]

jobs:
  unit:
    name: Unit Tests
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - run: npm ci
      - run: npm run test:unit -- --coverage
      - uses: codecov/codecov-action@v4
        with:
          files: coverage/lcov.info
          fail_ci_if_error: true

  integration:
    name: Integration Tests
    runs-on: ubuntu-latest
    needs: unit
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - run: npm ci
      - run: npm run test:integration

  e2e:
    name: E2E Tests
    runs-on: ubuntu-latest
    needs: integration
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npm run build
      - run: npm run test:e2e
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: playwright-report
          path: playwright-report/

Test Splitting for Speed

# Run E2E tests in parallel across multiple machines
e2e:
  strategy:
    matrix:
      shard: [1, 2, 3, 4]
  steps:
    - run: npx playwright test --shard=${{ matrix.shard }}/4

PR Gating Rules

---

Testing Decision Framework

When to Write Which Test

Is it a pure function with no side effects?
├── Yes → Unit test
└── No
    ├── Does it make API calls or use context?
    │   ├── Yes → Integration test with mocking
    │   └── No
    │       ├── Is it a critical user flow?
    │       │   ├── Yes → E2E test
    │       │   └── No → Integration test
    └── Is it UI-focused with many visual states?
        ├── Yes → Storybook + Visual test
        └── No → Component unit test

Test ROI Matrix

When NOT to Test

• Generated code (GraphQL types, Prisma client)
• Third-party library internals
• Implementation details (internal state, private methods)
• Simple pass-through wrappers
• Type definitions

Red Flags in Testing Strategy

---

Summary

1. Follow the pyramid: 60% unit, 30% integration, 10% E2E 2. Set thresholds by risk: Higher coverage for critical paths 3. Co-locate tests: Keep tests close to source code 4. Automate in CI: Run tests on every PR, gate merges on failure 5. Decide wisely: Not everything needs every type of test

Tool CLI Reference

Read this when running test_suite_generator.py, coverage_analyzer.py, or e2e_test_scaffolder.py — full flag tables, usage examples, output formats, and generated artifacts.

1. test_suite_generator.py

Purpose: Scans React/TypeScript source directories for components and generates Jest + React Testing Library test stubs with render tests, prop tests, interaction tests, state tests, and optional accessibility tests.

Usage:

python scripts/test_suite_generator.py <source> [options]

Flags:

Example:

python scripts/test_suite_generator.py src/components/ \
  --output __tests__/ \
  --include-a11y \
  --verbose

# Scanning: src/components/
# Found 24 React components
#   Button.test.tsx (4 test cases)
#   Modal.test.tsx (3 test cases)
#   ...
# Summary: 24 test files, 87 test cases

Output Formats:

• Default (text): Human-readable summary printed to stdout listing each generated file and test case count.
• JSON (`--json`): Structured object with status, components (array of detected component metadata), generated_files (array of output paths), and summary (totals).

---

2. coverage_analyzer.py

Purpose: Parses Jest/Istanbul coverage reports (JSON or LCOV format), identifies coverage gaps by severity, flags critical business-logic paths, and generates actionable recommendations in text, HTML, or JSON format.

Usage:

python scripts/coverage_analyzer.py <coverage> [options]

Flags:

Example:

python scripts/coverage_analyzer.py coverage/coverage-final.json \
  --threshold 80 \
  --strict \
  --format html \
  --output report.html

# Analyzing coverage from: coverage/coverage-final.json
# Found coverage data for 42 files
# Report written to: report.html

Output Formats:

• Text (`--format text`): Structured report with overall percentages, threshold pass/fail, critical gaps, files below threshold, and prioritized recommendations.
• HTML (`--format html`): Styled HTML report with color-coded coverage stats, gap severity table, and per-file breakdown. Suitable for CI artifact upload.
• JSON (`--json`): Summary object with status (pass/fail), threshold, coverage (statement/branch/function/line percentages), files_analyzed, files_below_threshold, total_gaps, and critical_gaps.

---

3. e2e_test_scaffolder.py

Purpose: Scans Next.js App Router or Pages Router directories, detects routes (including dynamic segments, route groups, and authenticated pages), and generates Playwright test files with navigation, form, auth, and interaction test stubs. Optionally generates Page Object Model classes and Playwright configuration.

Usage:

python scripts/e2e_test_scaffolder.py <source> [options]

Flags:

Example:

python scripts/e2e_test_scaffolder.py src/app/ \
  --output e2e/ \
  --include-pom \
  --routes "/login,/dashboard,/checkout"

# Scanning: src/app/
# Found 3 routes
#   auth-login.spec.ts
#   pages/AuthLoginPage.ts
#   dashboard.spec.ts
#   pages/DashboardPage.ts
#   checkout.spec.ts
#   pages/CheckoutPage.ts
#   fixtures/auth.ts
#
# Summary: 3 routes, 8 files generated

Output Formats:

• Default (text): Human-readable list of generated files and a route/file count summary.
• JSON (`--json`): Structured object with status, routes (array of route metadata including path, type, params, form/auth detection), generated_files (array with type, route, and path), and summary (totals and configuration flags).

Generated Artifacts:

• <route>.spec.ts -- Playwright test file per route with contextual test cases.
• pages/<RouteName>Page.ts -- Page Object Model class (when --include-pom is set).
• playwright.config.ts -- Multi-browser configuration with dev server integration (generated once if not already present).
• fixtures/auth.ts -- Authentication fixture with UI and API login patterns (generated once if not already present).