Skip to main content

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.

This document defines the standards for organizing and naming tests in the Encore Health OS codebase. Spec traceability: For which tests cover which specs, see SPEC_TEST_COVERAGE.md. Any test that implements scenarios from a feature spec MUST include an @spec CORE-## tag in the file header (e.g. @spec FA-20).

​
Directory Structure

All tests are organized in the tests/ directory by test type: 
tests/
├── rls/                    # Row-Level Security tests
│   ├── pf-organizations.rls.test.ts
│   ├── hr-employees.rls.test.ts
│   └── fa-journal-entries.rls.test.ts
│
├── unit/                   # Unit tests (hooks, utilities, business logic)
│   ├── pf/
│   │   ├── formatting-utilities.test.ts
│   │   └── dashboard-preferences.test.tsx
│   ├── hr/
│   │   ├── useEmployees.test.ts
│   │   └── onboarding-wizard-steps.test.tsx
│   └── fa/
│       └── journal-entries.test.ts
│
├── integration/            # Integration tests (cross-component workflows)
│   ├── pf/
│   ├── hr/
│   │   └── onboarding-workflow.test.ts
│   └── fa/
│       └── budget-template-workflow.test.ts
│
├── e2e/                    # End-to-end tests (Playwright)
│   ├── auth/
│   │   └── authentication-flow.test.ts
│   ├── hr/
│   │   └── employee-management.spec.ts
│   └── fa/
│       └── financial-transactions.spec.ts
│
└── utils/                  # Test utilities and helpers
    ├── providers.tsx      # Unified test providers
    ├── test-query-client.tsx
    ├── test-data-factory.ts
    └── cleanup/            # Module-specific cleanup
        ├── pf-cleanup.ts
        ├── hr-cleanup.ts
        └── index.ts

​
Naming Conventions

​
RLS Tests

Pattern: {core}-{table}.rls.test.ts Examples:
  • pf-organizations.rls.test.ts
  • hr-employees.rls.test.ts
  • fa-journal-entries.rls.test.ts
  • fw-forms.rls.test.ts
Rules:
  • Always use .rls.test.ts suffix
  • Include core prefix (pf, hr, fa, fw, etc.)
  • Use table name (singular or plural as in database)
  • Flat structure (no subdirectories)

​
Unit Tests

Pattern: {core}/{feature}.test.ts or {core}/{feature}.test.tsx Examples:
  • pf/formatting-utilities.test.ts
  • hr/useEmployees.test.ts
  • hr/onboarding-wizard-steps.test.tsx
  • fa/journal-entries.test.ts
Rules:
  • Use .test.ts or .test.tsx suffix
  • Organize by module in subdirectories
  • Use descriptive feature/hook/utility name
  • Use .tsx for component tests

​
Integration Tests

Pattern: {core}/{workflow}-workflow.test.ts or {core}/{feature}-integration.test.ts Examples:
  • hr/onboarding-workflow.test.ts
  • fa/budget-template-workflow.test.ts
  • fw/form-submission-workflow.test.ts
  • pf/permissions-system.test.tsx
Rules:
  • Use -workflow.test.ts suffix for workflow tests
  • Use -integration.test.ts suffix for feature integration tests
  • Organize by module in subdirectories
  • Describe the complete workflow being tested

​
E2E Tests

Pattern: {core}/{feature}.spec.ts Authentication: Specs that hit authenticated routes must use the shared auth fixture or the chromium-authenticated project. See TESTING_SETUP_AND_RUN.md. Examples:
  • auth/authentication-flow.test.ts
  • hr/employee-management.spec.ts
  • fa/financial-transactions.spec.ts
  • platform/search-filter-sort.spec.ts
Rules:
  • Use .spec.ts suffix (Playwright convention)
  • Organize by module in subdirectories
  • Use descriptive feature name
  • Focus on critical user journeys

​
Test File Organization Rules

​
When to Use Each Test Type

Test TypeWhen to UseExample
RLSTesting row-level security policieshr-employees.rls.test.ts
UnitTesting isolated functions, hooks, utilitieshr/useEmployees.test.ts
IntegrationTesting cross-component workflowshr/onboarding-workflow.test.ts
E2ETesting complete user journeyshr/employee-management.spec.ts

​
Co-location vs Centralization

Current Standard: Centralized
  • All tests go in tests/ directory
  • Tests are organized by type (rls, unit, integration, e2e)
  • Module organization within each type
Exception: Some platform utilities have co-located tests in src/__tests__/:
  • src/platform/wizards/utils/__tests__/
  • src/platform/navigation/__tests__/
Rule: New tests should use centralized tests/ directory unless there’s a specific reason for co-location.

​
Module Organization

​
Core Modules

Tests are organized by core module:
  • pf/ - Platform Foundation
  • hr/ - Human Resources
  • fa/ - Finance & Accounting
  • fw/ - Forms & Workflow
  • rh/ - Recovery Housing
  • fm/ - Facilities Management
  • it/ - IT Asset Management
  • ce/ - Community Engagement
  • lo/ - Leadership Operating System
  • gr/ - Governance & Compliance

​
Special Categories

Some test types have special categories:
  • e2e/auth/ - Authentication flows
  • e2e/security/ - Security tests
  • e2e/performance/ - Performance tests
  • e2e/visual/ - Visual regression tests

​
Test Structure Standards

​
RLS Test Structure

import { describeWithSupabase, itWithSupabase } from '@/tests/setup';
import { createMultiTenantScenario } from '@/tests/utils/rls-test-helpers';

describeWithSupabase('RLS: {table_name}', () => {
  let scenario: Awaited<ReturnType<typeof createMultiTenantScenario>>;
  
  beforeAll(async () => {
    scenario = await createMultiTenantScenario();
  });
  
  describe('Read Access', () => {
    itWithSupabase('org1 admin can only see their own organization', async () => {
      // Test logic
    });
  });
  
  // ... more test cases
});

​
Unit Test Structure

import { describe, it, expect } from 'vitest';
import { renderHook } from '@testing-library/react';
import { wrapper } from '@/tests/utils/providers';
import { useMyHook } from '@/cores/{core}/hooks/useMyHook';

describe('useMyHook', () => {
  it('should fetch data successfully', async () => {
    const { result } = renderHook(() => useMyHook(), { wrapper });
    // Test logic
  });
});

​
Integration Test Structure

import { describe, it, expect } from 'vitest';
import { render, screen } from '@testing-library/react';
import { TestProviders } from '@/tests/utils/providers';
import { MyWorkflowComponent } from '@/cores/{core}/components/MyWorkflowComponent';

describe('{Workflow} Workflow', () => {
  it('should complete workflow successfully', async () => {
    render(
      <TestProviders>
        <MyWorkflowComponent />
      </TestProviders>
    );
    // Test workflow steps
  });
});

​
Migration Checklist

When reorganizing existing tests:
  • Move RLS tests to flat tests/rls/ structure
  • Ensure all RLS tests use {core}-{table}.rls.test.ts naming
  • Organize unit tests by module in tests/unit/{core}/
  • Organize integration tests by module in tests/integration/{core}/
  • Organize E2E tests by module in tests/e2e/{core}/
  • Update imports to use new locations
  • Update test scripts if needed
  • Verify all tests still run

​
References