> ## Documentation Index
> Fetch the complete documentation index at: https://docs.equa.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Testing Guide

> How to run and write tests across all Equa repositories

# Testing Guide

> **Last Verified:** 2026-04-11 (PR #465 Jest 29 + React Testing Library migration; PR #515 auth form locators)

Each Equa repository uses a different testing framework. This guide covers how to run tests, how to write new ones, and what coverage is expected.

## Testing at a Glance

| Repository        | Unit Framework                     | E2E Framework       | Coverage Tool   | Run Command     |
| ----------------- | ---------------------------------- | ------------------- | --------------- | --------------- |
| equa-web          | Jest 29 + React Testing Library 14 | Playwright 1.58     | Jest built-in   | `yarn test`     |
| equa-server       | Mocha + NYC                        | --                  | NYC (Istanbul)  | `yarn test:api` |
| equabot-gateway   | Vitest                             | Vitest (e2e config) | V8 (via Vitest) | `pnpm test`     |
| equa-patternlib   | Vitest + Testing Library           | --                  | V8 (via Vitest) | `yarn test`     |
| command-center-so | tsx (built-in)                     | Playwright 1.58     | --              | `npm test`      |

## equa-web Testing

### Unit Tests (Jest 29 + React Testing Library)

```bash theme={null}
cd ~/Documents/repos/equa-web
yarn test
```

* **Framework:** Jest 29 with @testing-library/react 14 for React component testing (migrated from Enzyme in PR #465)
* **Config:** `jest.setup.js` in project root
* **Test environment:** jsdom
* **Test files:** `*.test.js`, `*.test.ts`, `*.test.tsx`
* **Location:** Colocated with source (e.g., `src/shared/components/button/button.test.js`)
* **Test count:** 52 tests passing

Source: `equa-web/package.json` scripts and Jest config

### E2E Tests (Playwright)

```bash theme={null}
# Run all E2E tests
yarn test:e2e

# Run with browser UI for debugging
yarn test:e2e:ui

# Run in headed mode (visible browser)
yarn test:e2e:headed
```

* **Framework:** Playwright 1.58
* **Config:** `playwright.config.ts`
* **Test directory:** `e2e/`
* **Base URL:** `http://localhost:8080`
* **Key test files:** `e2e/google-auth-smoke.spec.ts`, `e2e/auth-modal-security.spec.ts`, `e2e/agreements.spec.ts`, `e2e/regression-fixed-issues.spec.ts`, `e2e/visual-regression.spec.ts`

The webpack dev server starts automatically when running E2E tests.

<Warning>
  **Auth form locators (PR #515):** The login and registration forms render `<input type="text">`, **not** `<input type="email">`. Selectors that target `input[type="email"]` will silently time out (30s) because the locator never matches. Use `input[name="usernameOrEmail"]` for the login field and `input[name="email"]` for the registration email field. See [Spec 001 §2.6](/specs/001-authentication/spec#26-auth-form-fields-frontend) for the full form-field contract.
</Warning>

Source: `equa-web/package.json` scripts; `.github/workflows/e2e-tests.yml`

## equa-server Testing

### Integration Tests (Mocha)

```bash theme={null}
cd ~/Documents/repos/equa-server
yarn test:api
```

* **Framework:** Mocha with TypeScript support
* **Config:** `modules/api/test/.mocharc.js`
* **Coverage:** NYC (Istanbul)
* **Test location:** `modules/api/test/`

**Test directory structure:**

```
modules/api/test/
├── integration/
│   ├── local/        # Tests that run against local DB
│   └── external/     # Tests against external services
├── unit/             # Unit tests (validation, hashing, etc.)
└── fixtures/         # Test data and setup helpers
```

<Warning>
  Integration tests require a running PostgreSQL database. Start the Docker container first: `docker-compose up -d`
</Warning>

Source: `equa-server/package.json` scripts; `modules/api/test/` directory structure

## equabot-gateway Testing

### Unit Tests (Vitest)

```bash theme={null}
cd ~/Documents/repos/equabot
pnpm test
```

* **Framework:** Vitest
* **Config:** `vitest.config.ts`
* **Test files:** Colocated `*.test.ts` next to source files
* **Workers:** 4-16 locally, 2-3 in CI

### E2E and Live Tests

```bash theme={null}
# E2E tests
pnpm test:e2e

# Live tests (requires real API keys)
EQUABOT_LIVE_TEST=1 pnpm test:live

# All tests including Docker suites
pnpm test:all
```

### Coverage Requirements

equabot-gateway is the only repo with **enforced coverage thresholds**:

| Metric     | Threshold |
| ---------- | --------- |
| Lines      | 70%       |
| Functions  | 70%       |
| Statements | 70%       |
| Branches   | 55%       |

```bash theme={null}
# Run with coverage report
pnpm test:coverage
```

Source: `equabot-gateway/vitest.config.ts` coverage configuration

## equa-patternlib Testing

```bash theme={null}
cd ~/Documents/repos/equa-patternlib-nextjs
yarn test

# With watch mode
yarn test:watch

# With coverage
yarn test:coverage
```

* **Framework:** Vitest with Testing Library
* **Config:** `vitest.config.js`
* **Environment:** jsdom (for React component testing)
* **Test files:** Colocated `*.test.tsx` next to components

Source: `equa-patternlib-nextjs/package.json` scripts

## command-center-so Testing

```bash theme={null}
cd ~/Documents/repos/command-center-so
npm test
```

* **Framework:** tsx built-in test runner (Node.js `--test`)
* **Test location:** `test/` directory
* **Test files:** `*.test.ts`

E2E tests use Playwright:

```bash theme={null}
npx playwright test
```

Source: `command-center-so/package.json` scripts

## Writing a New Test

### Naming Convention

| Repository        | Pattern                   | Location                      |
| ----------------- | ------------------------- | ----------------------------- |
| equa-web          | `*.test.ts`, `*.test.tsx` | Colocated with source         |
| equa-server       | `*.test.ts`               | `modules/api/test/` directory |
| equabot-gateway   | `*.test.ts`               | Colocated with source         |
| equa-patternlib   | `*.test.tsx`              | Colocated with source         |
| command-center-so | `*.test.ts`               | `test/` directory             |

### Minimal Test Examples

**Vitest (equabot-gateway, equa-patternlib):**

```typescript theme={null}
import { describe, it, expect } from 'vitest';
import { formatTimestamp } from './format-timestamp';

describe('formatTimestamp', () => {
  it('formats ISO date string', () => {
    expect(formatTimestamp('2026-02-21T10:00:00Z')).toBe('Feb 21, 2026');
  });
});
```

**Jest + React Testing Library (equa-web):**

```typescript theme={null}
import React from 'react';
import { render, screen } from '@testing-library/react';
import { Button } from './Button';

describe('Button', () => {
  it('renders children', () => {
    render(<Button>Click me</Button>);
    expect(screen.getByText('Click me')).toBeInTheDocument();
  });
});
```

**Mocha (equa-server):**

```typescript theme={null}
import { expect } from 'chai';
import { validateEmail } from '../src/validation';

describe('validateEmail', () => {
  it('accepts valid email', () => {
    expect(validateEmail('user@example.com')).to.be.true;
  });
});
```

## E2E Setup

Before running Playwright E2E tests for the first time, install browsers:

```bash theme={null}
npx playwright install
```

This downloads Chromium, Firefox, and WebKit. Required for both equa-web and command-center-so.

**Common Playwright commands:**

| Command                        | What It Does                  |
| ------------------------------ | ----------------------------- |
| `npx playwright test`          | Run all tests headless        |
| `npx playwright test --headed` | Run with visible browser      |
| `npx playwright test --ui`     | Open interactive test runner  |
| `npx playwright test --debug`  | Run with Playwright Inspector |
| `npx playwright show-report`   | View HTML test report         |

## Coverage

| Repository        | Enforced? | Thresholds                                   | Command                          |
| ----------------- | --------- | -------------------------------------------- | -------------------------------- |
| equabot-gateway   | Yes       | 70% lines/functions/statements, 55% branches | `pnpm test:coverage`             |
| equa-web          | No        | --                                           | `yarn test --coverage`           |
| equa-server       | No        | --                                           | `yarn test:api` (NYC integrated) |
| equa-patternlib   | No        | --                                           | `yarn test:coverage`             |
| command-center-so | No        | --                                           | --                               |

Only equabot-gateway will fail CI if coverage drops below thresholds. Other repos generate coverage reports but do not enforce minimums.