# Test Organization

> **When to use**: Structuring test files, naming tests, grouping with `describe`, tagging, filtering, and deciding parallel vs serial execution.
> **Prerequisites**: [core/configuration.md](foundations/configuration.md)

## Quick Reference

| Concept | Rule |
|---|---|
| File suffix | `.spec.ts` / `.spec.js` — always |
| Grouping | By feature/domain, not by page or URL |
| Test names | `test('should ...')` or `test('user can ...')` — describe behavior |
| Nesting | Max 2 levels of `test.describe()` |
| Default execution | `fullyParallel: true` — tests run in parallel by default |
| Serial tests | Almost never use `test.describe.serial()` |
| Test dependencies | Avoid — each test sets up its own state |
| Tags | `@smoke`, `@regression`, `@slow` — filter with `--grep` |

## Patterns

### Pattern 1: Feature-Based File Structure

**Use when**: Any project — this is the default layout.
**Avoid when**: Never. This is always correct.

Group tests by feature or domain, not by page class or test type.

**Small project (< 20 tests):**

```
tests/
├── auth.spec.ts
├── dashboard.spec.ts
├── settings.spec.ts
└── checkout.spec.ts
playwright.config.ts
```

**Medium project (20–200 tests):**

```
tests/
├── auth/
│   ├── login.spec.ts
│   ├── signup.spec.ts
│   ├── password-reset.spec.ts
│   └── mfa.spec.ts
├── dashboard/
│   ├── widgets.spec.ts
│   ├── filters.spec.ts
│   └── export.spec.ts
├── checkout/
│   ├── cart.spec.ts
│   ├── payment.spec.ts
│   └── confirmation.spec.ts
├── settings/
│   ├── profile.spec.ts
│   └── notifications.spec.ts
└── fixtures/
    ├── auth.fixture.ts
    └── test-data.ts
playwright.config.ts
```

**Large project (200+ tests):**

```
tests/
├── e2e/
│   ├── auth/
│   │   ├── login.spec.ts
│   │   ├── signup.spec.ts
│   │   ├── password-reset.spec.ts
│   │   └── mfa.spec.ts
│   ├── checkout/
│   │   ├── cart.spec.ts
│   │   ├── payment.spec.ts
│   │   ├── promo-codes.spec.ts
│   │   └── confirmation.spec.ts
│   ├── admin/
│   │   ├── user-management.spec.ts
│   │   ├── reports.spec.ts
│   │   └── audit-log.spec.ts
│   └── inventory/
│       ├── product-list.spec.ts
│       ├── product-detail.spec.ts
│       └── stock-management.spec.ts
├── api/
│   ├── users.spec.ts
│   ├── orders.spec.ts
│   └── products.spec.ts
├── visual/
│   ├── homepage.spec.ts
│   └── product-page.spec.ts
├── fixtures/
│   ├── auth.fixture.ts
│   ├── db.fixture.ts
│   └── base.fixture.ts
├── page-objects/
│   ├── login.page.ts
│   ├── dashboard.page.ts
│   └── checkout.page.ts
└── helpers/
    ├── test-data.ts
    └── api-client.ts
playwright.config.ts
```

---

### Pattern 2: Naming Conventions

**Use when**: Writing any test or file.
**Avoid when**: Never.

**TypeScript:**

```typescript
// tests/checkout/cart.spec.ts
import { test, expect } from '@playwright/test';

// Good: group by feature, describe behavior
test.describe('Shopping Cart', () => {
  test('should add item to empty cart', async ({ page }) => {
    await page.goto('/products/widget-a');
    await page.getByRole('button', { name: 'Add to cart' }).click();
    await expect(page.getByTestId('cart-count')).toHaveText('1');
  });

  test('should update quantity when same item added twice', async ({ page }) => {
    await page.goto('/products/widget-a');
    await page.getByRole('button', { name: 'Add to cart' }).click();
    await page.getByRole('button', { name: 'Add to cart' }).click();
    await expect(page.getByTestId('cart-count')).toHaveText('2');
  });

  test('user can remove item from cart', async ({ page }) => {
    await page.goto('/cart');
    // ... setup item in cart via API or fixture
    await page.getByRole('button', { name: 'Remove' }).first().click();
    await expect(page.getByText('Your cart is empty')).toBeVisible();
  });
});
```

**JavaScript:**

```javascript
// tests/checkout/cart.spec.js
const { test, expect } = require('@playwright/test');

test.describe('Shopping Cart', () => {
  test('should add item to empty cart', async ({ page }) => {
    await page.goto('/products/widget-a');
    await page.getByRole('button', { name: 'Add to cart' }).click();
    await expect(page.getByTestId('cart-count')).toHaveText('1');
  });

  test('should update quantity when same item added twice', async ({ page }) => {
    await page.goto('/products/widget-a');
    await page.getByRole('button', { name: 'Add to cart' }).click();
    await page.getByRole('button', { name: 'Add to cart' }).click();
    await expect(page.getByTestId('cart-count')).toHaveText('2');
  });

  test('user can remove item from cart', async ({ page }) => {
    await page.goto('/cart');
    await page.getByRole('button', { name: 'Remove' }).first().click();
    await expect(page.getByText('Your cart is empty')).toBeVisible();
  });
});
```

**Naming rules:**

| Element | Convention | Example |
|---|---|---|
| File name | `kebab-case.spec.ts` | `password-reset.spec.ts` |
| `test.describe()` | Title Case, feature name | `'Password Reset'` |
| `test()` | Sentence starting with `should` or `user can` | `'should send reset email'` |
| Page objects | `PascalCase.page.ts` | `login.page.ts` / `LoginPage` |
| Fixtures | `kebab-case.fixture.ts` | `auth.fixture.ts` |

---

### Pattern 3: `test.describe()` Grouping

**Use when**: A file has multiple related tests that share context or setup.
**Avoid when**: A file has only 1–3 tests with no shared setup — skip the `describe` wrapper.

**TypeScript:**

```typescript
// tests/auth/login.spec.ts
import { test, expect } from '@playwright/test';

test.describe('Login', () => {
  // Shared setup for all tests in this describe block
  test.beforeEach(async ({ page }) => {
    await page.goto('/login');
  });

  test('should login with valid credentials', async ({ page }) => {
    await page.getByLabel('Email').fill('user@example.com');
    await page.getByLabel('Password').fill('securepass123');
    await page.getByRole('button', { name: 'Sign in' }).click();
    await expect(page).toHaveURL('/dashboard');
  });

  test('should show error for invalid password', async ({ page }) => {
    await page.getByLabel('Email').fill('user@example.com');
    await page.getByLabel('Password').fill('wrongpassword');
    await page.getByRole('button', { name: 'Sign in' }).click();
    await expect(page.getByRole('alert')).toHaveText('Invalid credentials');
  });

  // One level of nesting — acceptable
  test.describe('Rate Limiting', () => {
    test('should lock account after 5 failed attempts', async ({ page }) => {
      for (let i = 0; i < 5; i++) {
        await page.getByLabel('Email').fill('user@example.com');
        await page.getByLabel('Password').fill('wrong');
        await page.getByRole('button', { name: 'Sign in' }).click();
      }
      await expect(page.getByRole('alert')).toContainText('Account locked');
    });
  });
});
```

**JavaScript:**

```javascript
// tests/auth/login.spec.js
const { test, expect } = require('@playwright/test');

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

  test('should login with valid credentials', async ({ page }) => {
    await page.getByLabel('Email').fill('user@example.com');
    await page.getByLabel('Password').fill('securepass123');
    await page.getByRole('button', { name: 'Sign in' }).click();
    await expect(page).toHaveURL('/dashboard');
  });

  test('should show error for invalid password', async ({ page }) => {
    await page.getByLabel('Email').fill('user@example.com');
    await page.getByLabel('Password').fill('wrongpassword');
    await page.getByRole('button', { name: 'Sign in' }).click();
    await expect(page.getByRole('alert')).toHaveText('Invalid credentials');
  });

  test.describe('Rate Limiting', () => {
    test('should lock account after 5 failed attempts', async ({ page }) => {
      for (let i = 0; i < 5; i++) {
        await page.getByLabel('Email').fill('user@example.com');
        await page.getByLabel('Password').fill('wrong');
        await page.getByRole('button', { name: 'Sign in' }).click();
      }
      await expect(page.getByRole('alert')).toContainText('Account locked');
    });
  });
});
```

**Nesting limit: 2 levels max.** If you need a third level, split into a separate file.

---

### Pattern 4: Tags and Annotations

**Use when**: You need to categorize tests for selective runs (smoke suites, CI pipelines, skip known issues).
**Avoid when**: All tests always run together and you have < 20 tests.

**TypeScript:**

```typescript
// tests/checkout/payment.spec.ts
import { test, expect } from '@playwright/test';

// Tag in the test title — simplest approach
test('should process credit card payment @smoke', async ({ page }) => {
  await page.goto('/checkout');
  await page.getByLabel('Card number').fill('4242424242424242');
  await page.getByLabel('Expiry').fill('12/28');
  await page.getByLabel('CVC').fill('123');
  await page.getByRole('button', { name: 'Pay now' }).click();
  await expect(page.getByText('Payment successful')).toBeVisible();
});

test('should handle declined card @regression', async ({ page }) => {
  await page.goto('/checkout');
  await page.getByLabel('Card number').fill('4000000000000002');
  await page.getByLabel('Expiry').fill('12/28');
  await page.getByLabel('CVC').fill('123');
  await page.getByRole('button', { name: 'Pay now' }).click();
  await expect(page.getByRole('alert')).toContainText('Card declined');
});

// Tag via test.describe for group-level tagging
test.describe('Payment Edge Cases @regression', () => {
  test('should handle network timeout during payment', async ({ page }) => {
    await page.goto('/checkout');
    // ... test implementation
    await expect(page.getByText('Please try again')).toBeVisible();
  });
});

// Annotations for test lifecycle control
test('should render 3D Secure iframe @slow', async ({ page }) => {
  test.slow(); // Triples the default timeout
  await page.goto('/checkout/3ds');
  // ... long-running 3D Secure flow
  await expect(page.getByText('Verified')).toBeVisible();
});

test('should apply loyalty points discount', async ({ page }) => {
  test.skip(process.env.CI !== 'true', 'Only run in CI — needs loyalty service');
  await page.goto('/checkout');
  // ...
});

test('should handle Apple Pay on Safari', async ({ page, browserName }) => {
  test.skip(browserName !== 'webkit', 'Apple Pay only works in Safari');
  await page.goto('/checkout');
  // ...
});

test('should display PayPal button', async ({ page }) => {
  test.fixme(); // Known broken — tracked in JIRA-1234
  await page.goto('/checkout');
  await expect(page.getByRole('button', { name: 'PayPal' })).toBeVisible();
});

test('should fail when submitting empty card form', async ({ page }) => {
  test.fail(); // This test is expected to fail — documents known bug
  await page.goto('/checkout');
  await page.getByRole('button', { name: 'Pay now' }).click();
  // Bug: currently no validation shown — this assertion will fail
  await expect(page.getByRole('alert')).toBeVisible();
});
```

**JavaScript:**

```javascript
// tests/checkout/payment.spec.js
const { test, expect } = require('@playwright/test');

test('should process credit card payment @smoke', async ({ page }) => {
  await page.goto('/checkout');
  await page.getByLabel('Card number').fill('4242424242424242');
  await page.getByLabel('Expiry').fill('12/28');
  await page.getByLabel('CVC').fill('123');
  await page.getByRole('button', { name: 'Pay now' }).click();
  await expect(page.getByText('Payment successful')).toBeVisible();
});

test('should handle declined card @regression', async ({ page }) => {
  await page.goto('/checkout');
  await page.getByLabel('Card number').fill('4000000000000002');
  await page.getByLabel('Expiry').fill('12/28');
  await page.getByLabel('CVC').fill('123');
  await page.getByRole('button', { name: 'Pay now' }).click();
  await expect(page.getByRole('alert')).toContainText('Card declined');
});

test.describe('Payment Edge Cases @regression', () => {
  test('should handle network timeout during payment', async ({ page }) => {
    await page.goto('/checkout');
    await expect(page.getByText('Please try again')).toBeVisible();
  });
});

test('should render 3D Secure iframe @slow', async ({ page }) => {
  test.slow();
  await page.goto('/checkout/3ds');
  await expect(page.getByText('Verified')).toBeVisible();
});

test('should apply loyalty points discount', async ({ page }) => {
  test.skip(process.env.CI !== 'true', 'Only run in CI — needs loyalty service');
  await page.goto('/checkout');
});

test('should handle Apple Pay on Safari', async ({ page, browserName }) => {
  test.skip(browserName !== 'webkit', 'Apple Pay only works in Safari');
  await page.goto('/checkout');
});

test('should display PayPal button', async ({ page }) => {
  test.fixme(); // Known broken — tracked in JIRA-1234
  await page.goto('/checkout');
  await expect(page.getByRole('button', { name: 'PayPal' })).toBeVisible();
});

test('should fail when submitting empty card form', async ({ page }) => {
  test.fail();
  await page.goto('/checkout');
  await page.getByRole('button', { name: 'Pay now' }).click();
  await expect(page.getByRole('alert')).toBeVisible();
});
```

**Annotation cheat sheet:**

| Annotation | Effect | When to use |
|---|---|---|
| `test.skip()` | Skips the test entirely | Feature not available in this env/browser |
| `test.skip(condition, reason)` | Conditional skip | Browser-specific or env-specific tests |
| `test.fixme()` | Skips and marks as "needs fix" | Known bug, not yet fixed |
| `test.slow()` | Triples the timeout | Tests with inherently slow workflows |
| `test.fail()` | Expects the test to fail; fails if it passes | Documenting a known bug with a regression guard |
| `test.info().annotations` | Add custom annotations | Custom metadata for reports |

---

### Pattern 5: Test Filtering

**Use when**: Running a subset of tests from the CLI or CI.
**Avoid when**: Never — know these commands.

```bash
# By tag (in test title)
npx playwright test --grep @smoke
npx playwright test --grep @regression
npx playwright test --grep-invert @slow     # everything except @slow
npx playwright test -G @slow                # same — -G is the 1.61+ shorthand

# By file
npx playwright test tests/auth/
npx playwright test tests/checkout/payment.spec.ts

# By test name
npx playwright test --grep "should login"

# By project (from playwright.config)
npx playwright test --project=chromium
npx playwright test --project=mobile-safari

# Combine filters
npx playwright test --grep @smoke --project=chromium
npx playwright test tests/checkout/ --grep @smoke

# By line number — run a single test
npx playwright test tests/auth/login.spec.ts:15
```

**Using tags with `test.describe.configure()`:**

**TypeScript:**

```typescript
// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  projects: [
    {
      name: 'smoke',
      testMatch: '**/*.spec.ts',
      grep: /@smoke/,
    },
    {
      name: 'regression',
      testMatch: '**/*.spec.ts',
      grep: /@regression/,
    },
    {
      name: 'all',
      testMatch: '**/*.spec.ts',
      grepInvert: /@slow/,
    },
  ],
});
```

**JavaScript:**

```javascript
// playwright.config.js
const { defineConfig } = require('@playwright/test');

module.exports = defineConfig({
  projects: [
    {
      name: 'smoke',
      testMatch: '**/*.spec.js',
      grep: /@smoke/,
    },
    {
      name: 'regression',
      testMatch: '**/*.spec.js',
      grep: /@regression/,
    },
    {
      name: 'all',
      testMatch: '**/*.spec.js',
      grepInvert: /@slow/,
    },
  ],
});
```

---

### Pattern 6: Parallel vs Serial Execution

**Use when**: Deciding how tests run relative to each other.
**Avoid when**: You have < 5 tests (parallelism doesn't matter).

**Default: always parallel.** Set `fullyParallel: true` in config.

**TypeScript:**

```typescript
// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  fullyParallel: true, // All tests run in parallel by default
  workers: process.env.CI ? 1 : undefined, // Use all cores locally, 1 in CI (or adjust)
});
```

**JavaScript:**

```javascript
// playwright.config.js
const { defineConfig } = require('@playwright/test');

module.exports = defineConfig({
  fullyParallel: true,
  workers: process.env.CI ? 1 : undefined,
});
```

**Serial execution — use only when tests share external state you cannot isolate:**

**TypeScript:**

```typescript
// tests/onboarding/wizard.spec.ts
import { test, expect } from '@playwright/test';

// ONLY use serial when steps truly depend on prior state that cannot be set up independently
test.describe.serial('Onboarding Wizard', () => {
  test('step 1: user enters company name', async ({ page }) => {
    await page.goto('/onboarding');
    await page.getByLabel('Company name').fill('Acme Corp');
    await page.getByRole('button', { name: 'Next' }).click();
    await expect(page).toHaveURL('/onboarding/step-2');
  });

  test('step 2: user selects plan', async ({ page }) => {
    await page.goto('/onboarding/step-2');
    await page.getByRole('radio', { name: 'Pro plan' }).check();
    await page.getByRole('button', { name: 'Next' }).click();
    await expect(page).toHaveURL('/onboarding/step-3');
  });

  test('step 3: user confirms and completes', async ({ page }) => {
    await page.goto('/onboarding/step-3');
    await page.getByRole('button', { name: 'Complete setup' }).click();
    await expect(page.getByText('Welcome to Acme Corp')).toBeVisible();
  });
});
```

**JavaScript:**

```javascript
// tests/onboarding/wizard.spec.js
const { test, expect } = require('@playwright/test');

test.describe.serial('Onboarding Wizard', () => {
  test('step 1: user enters company name', async ({ page }) => {
    await page.goto('/onboarding');
    await page.getByLabel('Company name').fill('Acme Corp');
    await page.getByRole('button', { name: 'Next' }).click();
    await expect(page).toHaveURL('/onboarding/step-2');
  });

  test('step 2: user selects plan', async ({ page }) => {
    await page.goto('/onboarding/step-2');
    await page.getByRole('radio', { name: 'Pro plan' }).check();
    await page.getByRole('button', { name: 'Next' }).click();
    await expect(page).toHaveURL('/onboarding/step-3');
  });

  test('step 3: user confirms and completes', async ({ page }) => {
    await page.goto('/onboarding/step-3');
    await page.getByRole('button', { name: 'Complete setup' }).click();
    await expect(page.getByText('Welcome to Acme Corp')).toBeVisible();
  });
});
```

**Better alternative: test the full flow in one test with `test.step()`:**

**TypeScript:**

```typescript
// tests/onboarding/wizard.spec.ts
import { test, expect } from '@playwright/test';

test('user completes full onboarding wizard', async ({ page }) => {
  await test.step('enter company name', async () => {
    await page.goto('/onboarding');
    await page.getByLabel('Company name').fill('Acme Corp');
    await page.getByRole('button', { name: 'Next' }).click();
    await expect(page).toHaveURL('/onboarding/step-2');
  });

  await test.step('select plan', async () => {
    await page.getByRole('radio', { name: 'Pro plan' }).check();
    await page.getByRole('button', { name: 'Next' }).click();
    await expect(page).toHaveURL('/onboarding/step-3');
  });

  await test.step('confirm and complete', async () => {
    await page.getByRole('button', { name: 'Complete setup' }).click();
    await expect(page.getByText('Welcome to Acme Corp')).toBeVisible();
  });
});
```

**JavaScript:**

```javascript
// tests/onboarding/wizard.spec.js
const { test, expect } = require('@playwright/test');

test('user completes full onboarding wizard', async ({ page }) => {
  await test.step('enter company name', async () => {
    await page.goto('/onboarding');
    await page.getByLabel('Company name').fill('Acme Corp');
    await page.getByRole('button', { name: 'Next' }).click();
    await expect(page).toHaveURL('/onboarding/step-2');
  });

  await test.step('select plan', async () => {
    await page.getByRole('radio', { name: 'Pro plan' }).check();
    await page.getByRole('button', { name: 'Next' }).click();
    await expect(page).toHaveURL('/onboarding/step-3');
  });

  await test.step('confirm and complete', async () => {
    await page.getByRole('button', { name: 'Complete setup' }).click();
    await expect(page.getByText('Welcome to Acme Corp')).toBeVisible();
  });
});
```

---

### Pattern 7: Monorepo Testing

**Use when**: A single repository contains multiple apps or packages that each need E2E tests.
**Avoid when**: Single app repo.

**TypeScript:**

```typescript
// playwright.config.ts (root of monorepo)
import { defineConfig } from '@playwright/test';

export default defineConfig({
  projects: [
    {
      name: 'web-app',
      testDir: './apps/web/tests',
      use: {
        baseURL: 'http://localhost:3000',
      },
    },
    {
      name: 'admin-panel',
      testDir: './apps/admin/tests',
      use: {
        baseURL: 'http://localhost:3001',
      },
    },
    {
      name: 'marketing-site',
      testDir: './apps/marketing/tests',
      use: {
        baseURL: 'http://localhost:4000',
      },
    },
  ],
});
```

**JavaScript:**

```javascript
// playwright.config.js (root of monorepo)
const { defineConfig } = require('@playwright/test');

module.exports = defineConfig({
  projects: [
    {
      name: 'web-app',
      testDir: './apps/web/tests',
      use: {
        baseURL: 'http://localhost:3000',
      },
    },
    {
      name: 'admin-panel',
      testDir: './apps/admin/tests',
      use: {
        baseURL: 'http://localhost:3001',
      },
    },
    {
      name: 'marketing-site',
      testDir: './apps/marketing/tests',
      use: {
        baseURL: 'http://localhost:4000',
      },
    },
  ],
});
```

**Monorepo directory layout:**

```
monorepo/
├── apps/
│   ├── web/
│   │   ├── src/
│   │   └── tests/
│   │       ├── auth/
│   │       │   └── login.spec.ts
│   │       └── dashboard/
│   │           └── widgets.spec.ts
│   ├── admin/
│   │   ├── src/
│   │   └── tests/
│   │       └── user-management.spec.ts
│   └── marketing/
│       ├── src/
│       └── tests/
│           └── landing-page.spec.ts
├── packages/
│   └── shared-fixtures/
│       ├── auth.fixture.ts
│       └── index.ts
└── playwright.config.ts
```

Run only one app's tests:

```bash
npx playwright test --project=web-app
npx playwright test --project=admin-panel
```

## Decision Guide

```
How many tests do you have?
│
├── < 20 tests (small)
│   ├── Flat structure: all .spec.ts files in tests/
│   ├── No subdirectories needed
│   ├── Tags optional — just run everything
│   └── fullyParallel: true, single config project
│
├── 20–200 tests (medium)
│   ├── Feature subdirectories: tests/auth/, tests/checkout/
│   ├── Use @smoke tag for critical-path subset (< 15 min)
│   ├── Shared fixtures in tests/fixtures/
│   ├── Page objects in tests/page-objects/ (if you use them)
│   └── Consider separate projects for different browsers
│
└── 200+ tests (large)
    ├── Top-level split: tests/e2e/, tests/api/, tests/visual/
    ├── Feature subdirectories under each
    ├── @smoke, @regression, @slow tags — multiple CI pipelines
    ├── Sharding in CI for faster runs
    ├── Project-based filtering: smoke project, full project
    └── Shared fixtures as a package in monorepo
```

```
Should I use test.describe.serial()?
│
├── Can each test set up its own state via API/fixture?
│   └── YES → Do NOT use serial. Use independent parallel tests.
│
├── Is this a multi-step wizard where each step changes server state
│   that cannot be reset between tests?
│   └── Write it as ONE test with test.step() instead.
│
└── Is this genuinely stateful (e.g., database migration sequence)?
    └── Use serial as last resort. Add a comment explaining why.
```

## Anti-Patterns

### One giant test file

```typescript
// BAD: tests/all-tests.spec.ts with 80 tests and 2000+ lines
test.describe('Everything', () => {
  test('login works', async ({ page }) => { /* ... */ });
  test('signup works', async ({ page }) => { /* ... */ });
  test('cart works', async ({ page }) => { /* ... */ });
  // ... 77 more tests
});
```

**Fix:** Split by feature — one file per feature area, 5–15 tests per file.

---

### Meaningless test names

```typescript
// BAD
test('test1', async ({ page }) => { /* ... */ });
test('test2', async ({ page }) => { /* ... */ });
test('payment test', async ({ page }) => { /* ... */ });
test('it works', async ({ page }) => { /* ... */ });
```

**Fix:** Describe behavior. When a test fails, the name should tell you what broke.

```typescript
// GOOD
test('should reject expired credit card', async ({ page }) => { /* ... */ });
test('user can update shipping address during checkout', async ({ page }) => { /* ... */ });
```

---

### Deep describe nesting

```typescript
// BAD: 3+ levels deep — hard to read, hard to find tests in reports
test.describe('Auth', () => {
  test.describe('Login', () => {
    test.describe('With MFA', () => {
      test.describe('SMS', () => {
        test('should send code', async ({ page }) => { /* ... */ });
      });
    });
  });
});
```

**Fix:** Max 2 levels. Split deeper nesting into separate files.

```typescript
// GOOD: tests/auth/login-mfa-sms.spec.ts
test.describe('Login with SMS MFA', () => {
  test('should send verification code', async ({ page }) => { /* ... */ });
  test('should reject invalid code', async ({ page }) => { /* ... */ });
});
```

---

### Using `test.describe.serial()` as the default

```typescript
// BAD: serial for no reason — kills parallelism, creates hidden dependencies
test.describe.serial('User Profile', () => {
  test('should display profile page', async ({ page }) => { /* ... */ });
  test('should update display name', async ({ page }) => { /* ... */ });
  test('should upload avatar', async ({ page }) => { /* ... */ });
});
```

**Fix:** Each test should be independent. Use `beforeEach` or fixtures to set up state.

```typescript
// GOOD
test.describe('User Profile', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/profile');
  });

  test('should display profile page', async ({ page }) => { /* ... */ });
  test('should update display name', async ({ page }) => { /* ... */ });
  test('should upload avatar', async ({ page }) => { /* ... */ });
});
```

---

### Relying on test execution order

```typescript
// BAD: test 2 depends on test 1 creating data
test('should create a product', async ({ page }) => {
  // creates "Widget X" in the database
});

test('should edit the product', async ({ page }) => {
  // assumes "Widget X" exists — breaks if run alone or in parallel
});
```

**Fix:** Each test creates its own data via API calls or fixtures.

```typescript
// GOOD
test('should edit a product', async ({ page, request }) => {
  // Set up test data independently
  const response = await request.post('/api/products', {
    data: { name: 'Widget X', price: 9.99 },
  });
  const product = await response.json();

  await page.goto(`/products/${product.id}/edit`);
  await page.getByLabel('Name').fill('Widget X Updated');
  await page.getByRole('button', { name: 'Save' }).click();
  await expect(page.getByText('Widget X Updated')).toBeVisible();
});
```

## Troubleshooting

| Problem | Cause | Fix |
|---|---|---|
| Tests pass alone but fail together | Shared state between tests (cookies, DB rows, global variables) | Isolate each test — use fixtures for setup/teardown |
| `--grep @smoke` matches nothing | Tag not in test title string | Verify the tag appears literally in `test('... @smoke', ...)` |
| Serial tests cascade-fail | One test fails, all subsequent tests skip | Rewrite as independent tests or use `test.step()` in a single test |
| Tests run slower than expected | `fullyParallel` not set | Add `fullyParallel: true` in `playwright.config` |
| Wrong tests run in CI | `testMatch` or `testDir` misconfigured | Check `playwright.config` — print resolved config with `npx playwright test --list` |
| Monorepo tests pick up wrong files | Default `testDir` is `.` | Set explicit `testDir` per project |

## Related

- [core/configuration.md](foundations/configuration.md) — `testMatch`, `testDir`, `fullyParallel`, `workers`
- [core/fixtures-and-hooks.md](foundations/fixtures-and-hooks.md) — shared setup via fixtures instead of `beforeAll`
- [core/test-architecture.md](decisions/test-architecture.md) — when to write E2E vs API vs component tests
- [ci/parallel-and-sharding.md](infrastructure/parallel-and-sharding.md) — CI sharding for large suites
- [ci/projects-and-dependencies.md](infrastructure/projects-and-dependencies.md) — multi-project config