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

# Testing Documentation

> Version: 1.1.0 Last Updated: 2026-04-01

**Version:** 1.1.0\
**Last Updated:** 2026-04-01

Testing documentation for the Encore Health OS Platform.

**Canonical setup and commands:** [TESTING\_SETUP\_AND\_RUN.md](./TESTING_SETUP_AND_RUN.md) (environment, Playwright, RLS, CI parity). This README is an index; when anything disagrees, prefer that file.

***

## Overview

Testing is a critical part of our development process, especially given:

* Multi-tenant architecture requiring strict data isolation
* Healthcare-grade security and compliance requirements
* Financial accuracy requirements
* Complex business workflows

***

## Test Pyramid

```
        /\
       /  \      E2E Tests (20%)
      /----\     Critical user journeys
     /      \    
    /--------\   Integration Tests (50%)
   /  UNIT   \   RLS policies, API endpoints
  /____________\ Unit Tests (30%)
                 Business logic, utilities
```

### Unit Tests (30%)

* Pure business logic functions
* Validation schemas
* Utility functions
* React component logic (hooks)

**Location:** `/tests/unit/`\
**Framework:** Vitest\
**Coverage Target:** 80%+

### Integration Tests (50%)

* **RLS policies** (critical!) - Tenant isolation verification
* Database functions
* API endpoints
* Cross-module integrations
* Edge function behavior

**Location:** `/tests/rls/`, `/tests/integration/`\
**Framework:** Vitest + Supabase Test Client\
**Coverage Target:** 95%+ for RLS, 70%+ for integration

### E2E Tests (20%)

* Critical user journeys
* Authentication flows
* Multi-tenant isolation scenarios
* Compliance workflows
* Payment processing (when implemented)

**Location:** `/tests/e2e/`\
**Framework:** Playwright (see [TESTING\_SETUP\_AND\_RUN.md](./TESTING_SETUP_AND_RUN.md) for install, auth storage, and per-core scripts)\
**Coverage Target:** Critical paths only

***

## Current Test Coverage

### Platform Foundation (PF)

* ✅ PF-01: Organizations & Sites RLS
* ✅ PF-02: User Roles RLS
* ✅ PF-04: Audit Logs RLS
* ✅ PF-06: Profiles RLS
* ✅ PF-11: Document Management RLS
* ✅ PF-12: Reporting Engine RLS

### Forms & Workflow (FW)

* ✅ FW-01: Forms RLS
* ✅ FW-01: Form Fields RLS
* ✅ FW-01: Form Permissions RLS
* ✅ FW-01: Form Versions RLS
* ✅ FW-03: Automation Rules RLS
* ✅ FW-15: Lookup Field Validation (Unit, RLS, Integration)

### Workforce & HRIS (HR)

* ✅ HR-01: Employees RLS
* ✅ HR-01: Departments RLS
* ✅ HR-01: Positions RLS
* ✅ HR-01: Teams RLS
* ✅ HR-02: Credential Types RLS
* ✅ HR-02: Employee Credentials RLS
* ✅ HR-02: Credential Requirements RLS
* ✅ HR-02: Credential Alerts RLS
* ✅ HR-03: Onboarding Templates RLS
* ✅ HR-03: Onboarding Instances RLS
* ✅ HR-03: Onboarding Tasks RLS
* ✅ HR-03: Offboarding Instances RLS
* ✅ HR-03: Offboarding Checklist Items RLS
* ✅ HR-04: Shifts RLS
* ✅ HR-04: Shift Templates RLS
* ✅ HR-04: Shift Assignments RLS
* ✅ HR-04: Shift Swap Requests RLS
* ✅ HR-04: Availability Preferences RLS
* ✅ HR-05: Time Punches RLS
* ✅ HR-05: Timesheets RLS
* ✅ HR-05: Timesheet Entries RLS

### Custom Fields

* ✅ Custom fields JSONB integration tests

***

## Running Tests

### All Tests

```bash theme={null}
npm test
```

### RLS Tests Only

```bash theme={null}
npm run test:rls
```

### Integration Tests Only

```bash theme={null}
npm run test:integration
```

### Unit Tests Only

```bash theme={null}
npm run test:unit
```

### Watch Mode (Development)

```bash theme={null}
npm run test:watch
```

### Coverage Report

```bash theme={null}
npm run test:coverage
```

***

## Test Organization

### File Naming Conventions

**RLS Tests:**

```
tests/rls/{core}-{table-name}.test.ts
Example: tests/rls/hr-employees.test.ts
```

**Integration Tests:**

```
tests/integration/{feature-name}.test.ts
Example: tests/integration/custom-fields.test.ts
```

**Unit Tests:**

```
tests/unit/{module-name}.test.ts
Example: tests/unit/validation.test.ts
```

***

## RLS Testing Pattern

Every business table MUST have RLS tests verifying:

1. ✅ Users can only see data from their organization
2. ✅ Users cannot see data from other organizations
3. ✅ Role-based access is enforced correctly
4. ✅ Insert, update, delete operations respect RLS

**Example:**

```typescript theme={null}
describe('hr_employees RLS', () => {
  it('prevents cross-organization access', async () => {
    // Org 1 user should NOT see Org 2 data
    const { data, error } = await org1Client
      .from('hr_employees')
      .select('*');
    
    expect(data.every(emp => emp.organization_id === org1.id)).toBe(true);
  });
});
```

See `/tests/rls/` for RLS test examples.

***

## Test Data Strategy

### Principles

1. **Synthetic Data Only** - No real PHI, PII, or production data
2. **Deterministic** - Tests should produce same results every run
3. **Isolated** - Each test creates and cleans up its own data
4. **Realistic** - Data should reflect real-world scenarios

### Test Data Factory

**Location:** `/tests/utils/test-data-factory.ts`

**Usage:**

```typescript theme={null}
import { createTestOrganization, createTestEmployee } from '@/tests/utils/test-data-factory';

const org = await createTestOrganization();
const employee = await createTestEmployee(org.id);
```

**Status:** 📋 Planned - Will be expanded as testing matures

***

## Documents in This Directory

### TestSprite (AI autonomous testing)

**File:** [TESTSPRITE\_SETUP.md](TESTSPRITE_SETUP.md)\
**Purpose:** Run TestSprite via Cursor MCP for AI-generated frontend E2E and backend API tests. Requires TestSprite account and API key; see doc for setup and "Can you test this project with TestSprite?" workflow. Before running tests, see **Ensure everything is running** in [TESTSPRITE\_SETUP.md](TESTSPRITE_SETUP.md).

### Wizard Migration Browser Test Log

**File:** [wizard-migration-browser-test-log.md](../archive/testing/wizard-migration-browser-test-log.md)\
**Purpose:** Verify all wizard and multipage flows use WizardShell, DialogWizardShell, or ModuleWizardRenderer per WIZARD\_UX\_STANDARD. Code verification completed; browser results table to be filled when tests are run (cursor-ide-browser MCP or manual).

### E2E Test Scenarios

**File:** `E2E_TEST_SCENARIOS.md`\
**Status:** 📋 Placeholder\
**Purpose:** Critical user journeys and E2E test scenarios

**Planned Sections:**

* Authentication flows
* Employee onboarding workflow
* Shift scheduling workflow
* Time tracking workflow
* Form submission workflow
* Cross-module integration scenarios

### Test Data Strategy

**File:** `TEST_DATA_STRATEGY.md`\
**Status:** 📋 Placeholder\
**Purpose:** Test data generation, seeding, and cleanup strategies

**Planned Sections:**

* Synthetic data generation rules
* Test data factories
* Seed data management
* Data cleanup strategies
* PHI/PII compliance in tests

***

## CI/CD Integration

### Pre-Commit

* Linting (ESLint)
* Type checking (TypeScript)
* Unit tests (fast)

### Pull Request

* All tests (unit + integration + RLS)
* Coverage report
* Security scan

### Main Branch

* Full test suite
* Performance benchmarks
* Integration with staging environment

***

## Test Requirements by Risk Level

### Critical (MUST have tests)

* Multi-tenant data isolation (RLS)
* Financial calculations
* Clinical data handling (future)
* Authentication & authorization
* Data migrations

### High (SHOULD have tests)

* Business logic functions
* API endpoints
* Database functions
* Cross-module integrations

### Medium (NICE to have tests)

* UI component logic
* Utility functions
* Edge cases

***

## Performance Testing

**Status:** 📋 Planned

**Targets (p95):**

* API response time: \< 500ms
* Database queries: \< 200ms
* Page load time: \< 3s

**Tools:**

* k6 (load testing)
* Lighthouse (frontend performance)

***

## Security Testing

**Status:** 📋 Planned

**Requirements:**

* RLS policy verification (✅ In progress)
* SQL injection testing
* XSS prevention testing
* CSRF protection testing
* Authentication bypass testing
* Secrets exposure scanning

***

## References

* `/tests/SETUP.md` - Test environment setup
* `/tests/README.md` - This file
* `/constitution.md` - Testing requirements (Section 5.4)
* `/docs/architecture/index.md` - Architecture overview

***

**Maintained by:** Platform Engineering Team\
**Questions?** See `/tests/SETUP.md` or raise in #engineering Slack