claude-skills-reference/engineering-team/senior-qa/references/qa_best_practices.md

# 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](#writing-testable-code)
- [Test Naming Conventions](#test-naming-conventions)
- [Arrange-Act-Assert Pattern](#arrange-act-assert-pattern)
- [Test Isolation Principles](#test-isolation-principles)
- [Handling Flaky Tests](#handling-flaky-tests)
- [Code Review for Testability](#code-review-for-testability)
- [Test Maintenance Strategies](#test-maintenance-strategies)
- [Debugging Failed Tests](#debugging-failed-tests)
- [Quality Metrics and KPIs](#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:**

```typescript
// 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:**

```typescript
// 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):**

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

**Pure (Easy to Test):**

```typescript
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):**

```typescript
// 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):**

```typescript
// 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

| Pattern | Testability | Example |
|---------|-------------|---------|
| Props over context | High | `<Button disabled={!valid}>` |
| Callbacks over side effects | High | `onSubmit={handleSubmit}` |
| Controlled components | High | `<Input value={value} onChange={...}>` |
| Render props | Medium | `<DataProvider render={data => ...}>` |
| Internal state | Low | `const [x, setX] = useState()` |
| Global state | Low | `useGlobalStore()` |

---

## Test Naming Conventions

Good test names document expected behavior and help diagnose failures.

### Naming Patterns

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

```typescript
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]**

```typescript
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]**

```typescript
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

```typescript
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

| Bad | Good | Why |
|-----|------|-----|
| `it('works')` | `it('returns sum of two numbers')` | Describes behavior |
| `it('test 1')` | `it('handles empty array')` | Specific scenario |
| `it('should do stuff')` | `it('should validate email format')` | Clear expectation |
| Duplicating code in name | Describing behavior | Readable output |

---

## Arrange-Act-Assert Pattern

The AAA pattern structures tests into three clear phases.

### Structure

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

```typescript
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

| Aspect | Solution |
|--------|----------|
| Global state | Reset in beforeEach |
| Timers | jest.useFakeTimers() + jest.useRealTimers() |
| DOM | RTL's cleanup (automatic) |
| Database | Truncate tables or use transactions |
| API mocks | server.resetHandlers() |
| File system | Use temp directories, clean up in afterEach |
| Environment vars | Restore in afterEach |

---

## Handling Flaky Tests

Flaky tests pass and fail intermittently without code changes.

### Common Causes and Fixes

**1. Timing Issues**

```typescript
// 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**

```typescript
// 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**

```typescript
// 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**

```typescript
// 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

```javascript
// 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

```typescript
// 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:**
```typescript
// 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:**

```typescript
// __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:**

```typescript
// 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**

```typescript
// 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**

```typescript
// 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

```typescript
/**
 * @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:**
```bash
# 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:**
```bash
node --inspect-brk node_modules/.bin/jest --runInBand
# Open chrome://inspect in Chrome
```

**Verbose output:**
```bash
npx jest --verbose --no-coverage
```

### React Testing Library Debugging

```typescript
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

```bash
# 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:**
```typescript
test('debug this', async ({ page }) => {
  await page.goto('/');
  await page.pause(); // Opens inspector
  await page.click('button');
});
```

### Common Failure Patterns

| Symptom | Likely Cause | Debug Approach |
|---------|--------------|----------------|
| "Unable to find element" | Wrong query or element not rendered | `screen.debug()`, check async |
| "Expected X, received Y" | Logic error or stale mock | Log intermediate values |
| "Timeout exceeded" | Slow async or missing await | Increase timeout, check promises |
| "Cannot read property of undefined" | Missing mock or setup | Check beforeEach, mock returns |
| Passes locally, fails in CI | Environment difference | Check env vars, timing |

### Investigating Flaky Failures

```typescript
// 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:**

| Metric | Target | Measurement |
|--------|--------|-------------|
| Line coverage | 80% | `jest --coverage` |
| Branch coverage | 75% | `jest --coverage` |
| Function coverage | 80% | `jest --coverage` |
| Critical path coverage | 95% | Custom tracking |

**Test Suite Health:**

| Metric | Target | Measurement |
|--------|--------|-------------|
| Test pass rate | 100% | CI reports |
| Flaky test rate | <1% | Track retries |
| Test execution time | <5 min | CI timing |
| Tests per component | ≥3 | Test count / components |

**Defect Metrics:**

| Metric | Target | Measurement |
|--------|--------|-------------|
| Defects found in testing | >70% | Bug tracking |
| Defects escaped to prod | <10% | Production bugs |
| Regression rate | <5% | Bugs reintroduced |
| Mean time to detect | <1 day | Bug timestamps |

### Dashboard Example

```typescript
// 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

```yaml
# .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:

```typescript
// 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