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)

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)

# 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.

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 for the full form-field contract.

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

equa-server Testing

Integration Tests (Mocha)

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

Integration tests require a running PostgreSQL database. Start the Docker container first: docker-compose up -d

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

equabot-gateway Testing

Unit Tests (Vitest)

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

# 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%

# Run with coverage report
pnpm test:coverage

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

equa-patternlib Testing

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

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:

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):

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):

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):

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:

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.

Platform Architecture

Compliance & Security

Feature Specifications

Releases

Developer Onboarding

Business

Reference & Templates

Testing Guide

Testing Guide

Testing at a Glance

equa-web Testing

Unit Tests (Jest 29 + React Testing Library)

E2E Tests (Playwright)

equa-server Testing

Integration Tests (Mocha)

equabot-gateway Testing

Unit Tests (Vitest)

E2E and Live Tests

Coverage Requirements

equa-patternlib Testing

command-center-so Testing

Writing a New Test

Naming Convention

Minimal Test Examples

E2E Setup

Coverage

​Testing Guide

​Testing at a Glance

​equa-web Testing

​Unit Tests (Jest 29 + React Testing Library)

​E2E Tests (Playwright)

​equa-server Testing

​Integration Tests (Mocha)

​equabot-gateway Testing

​Unit Tests (Vitest)

​E2E and Live Tests

​Coverage Requirements

​equa-patternlib Testing

​command-center-so Testing

​Writing a New Test

​Naming Convention

​Minimal Test Examples

​E2E Setup

​Coverage

Testing Guide

Testing at a Glance

equa-web Testing

Unit Tests (Jest 29 + React Testing Library)

E2E Tests (Playwright)

equa-server Testing

Integration Tests (Mocha)

equabot-gateway Testing

Unit Tests (Vitest)

E2E and Live Tests

Coverage Requirements

equa-patternlib Testing

command-center-so Testing

Writing a New Test

Naming Convention

Minimal Test Examples

E2E Setup

Coverage