test-levels

name	test-levels
description	This skill explains the 3 test levels (Unit, Integration, E2E) using the "Building a Car" analogy and provides guidance on when to use each type. Includes project-specific Playwright examples.

Test Levels Guide

Explains test types & guides test selection using car analogy.

When to Use

Invoke when:

• Explaining test concepts to team members
• Deciding which test type to write
• Reviewing test coverage strategy
• Onboarding new developers to testing

The 3 Test Levels

1. Unit Test (Test Case)

The specific instruction.

Single fn/component tested in isolation. No external deps (DB, API, browser).

Aspect	Description
Analogy	"Check if left turn signal blinks when I push lever down"
Scope	Tiny detail - one fn, one input/output
Speed	Fast (ms)
Location	tests/unit/

When to write:

• Pure functions (formatters, validators, utils)
• Data transformations
• Business logic w/o side effects

Project example:

// tests/unit/utils/formatters.spec.ts
import {expect, test} from 'next/experimental/testmode/playwright';
import {leadingZero, formatCurrency} from '@/app/_utils/formatters';

test.describe('formatters', () => {
    test('leadingZero adds zero to single-digit numbers', () => {
        expect(leadingZero(7)).toBe('07');
        expect(leadingZero(10)).toBe('10');
    });

    test('formatCurrency formats correctly', () => {
        const result = formatCurrency({value: 1234.56, locale: 'en', currency: 'USD'});
        expect(result).toBe('1,234.56 $');
    });
});

---

2. Integration Test

The handshake.

Tests if 2+ parts communicate correctly. Focuses on connections, not full system.

Aspect	Description
Analogy	"Does engine make wheels turn?" (Engine → Transmission)
Scope	Connections between components
Speed	Medium (100ms-few seconds)
Location	tests/integration/

When to write:

• Validators w/ schemas (Zod)
• API route handlers
• Service-to-service communication
• DB queries w/ mocked data

Project example:

// tests/integration/validators/offer.spec.ts
import {expect, test} from 'next/experimental/testmode/playwright';
import {mockLoggedUser} from '../../common';
import {validateCustomerStatus} from '@/app/_lib/validator';

test.beforeEach(async ({context}) => {
    await mockLoggedUser(context);
});

test.describe('validate customer status', () => {
    const validData = {
        offerId: '670e80f0a65da593d265088a',
        status: 'viewing',
    };

    test('returns success for valid data', async () => {
        const result = validateCustomerStatus(validData);
        expect(result.success).toBe(true);
        expect(result.data).toEqual(validData);
    });

    test('returns error for invalid offerId', async () => {
        const result = validateCustomerStatus({...validData, offerId: ''});
        expect(result.success).toBe(false);
        (result.?.[]?.).();
    });
});

---

3. E2E Test (End-to-End)

The real user journey.

Full system test: browser, DB, network, 3rd-party services. Exactly as user experiences.

Aspect	Description
Analogy	"Start car, drive to store, park, turn off"
Scope	Full user flow
Speed	Slow (seconds-minutes)
Location	tests/pages/

When to write:

• Critical user flows (login, checkout, payment)
• Multi-page journeys
• Features requiring browser interaction
• Smoke tests for deployment

Project example:

// tests/pages/start.spec.ts
import {expect, test} from 'next/experimental/testmode/playwright';
import {mockLoggedUser, resetAPIEndpointsMock} from '../common';

test.beforeEach(async ({context}) => {
    await mockLoggedUser(context);
});

test.afterEach(async ({next, context}) => {
    await resetAPIEndpointsMock(next);
    await context.clearCookies();
});

test('start page renders correctly', async ({page}) => {
    test.setTimeout(120000);

    await page.goto('http://localhost:3000/start', {
        timeout: 90000,
        waitUntil: 'domcontentloaded'
    });

    await expect(page).toHaveURL('http://localhost:3000/start');
    await expect(page.getByTestId('pageHeader')).toHaveClass('drop-shadow-font');
    await expect(page.getByTestId('subTotal')).toContainText('Sub total');
    await (page.()).();
});

---

Quick Decision Guide

Question	Test Type
"Does this fn return correct value?"	Unit
"Do these 2 parts work together?"	Integration
"Does full flow work for user?"	E2E

Test Pyramid

        /\
       /E2E\         Few (slow, expensive)
      /------\
     /Integr- \      Some (medium)
    /  ation   \
   /------------\
  /    Unit      \   Many (fast, cheap)
 /________________\

Rule: More unit tests, fewer E2E tests. Unit tests catch bugs early & run fast.

---

Project Structure

tests/
├── unit/              # Pure fn tests (no browser)
│   └── utils/         # Utility fn tests
├── integration/       # Component interaction tests
│   ├── validators/    # Schema validation tests
│   └── lib/           # Library fn tests
├── pages/             # E2E browser tests
│   ├── start.spec.ts
│   ├── payment.spec.ts
│   └── confirm.spec.ts
├── common.ts          # Shared test utilities
├── mock/              # Mock data & helpers
└── seed.spec.ts       # DB seed for tests

---

Commands

# Run all tests (headed mode)
npm run test

# Run specific test file
npm run test tests/unit/utils/formatters.spec.ts

# Run tests in UI mode
npm run test:ui

# Show test report
npm run test:report

---

Best Practices

1. Name tests clearly: should [action] when [condition]
2. One assertion focus: Test one behavior per test
3. Use test.describe: Group related tests
4. Clean up: Use afterEach for state reset
5. Mock external deps: Use mockLoggedUser, resetAPIEndpointsMock
6. Set timeouts: E2E tests need longer timeouts (120s)
7. Use data-testid: For reliable element selection

---

Summary Table

Level	Question	Scope	Speed	Location
Unit	"Does this fn work?"	Single fn	Fast	tests/unit/
Integration	"Do parts connect?"	Connections	Medium	tests/integration/
E2E	"Does flow work?"	Full system	Slow	tests/pages/