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

# Test Organization Standards

> This document defines the standards for organizing and naming tests in the Encore Health OS codebase.

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](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](TESTING_SETUP_AND_RUN.md#3-e2e-authentication).

**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 Type       | When to Use                                  | Example                          |
| --------------- | -------------------------------------------- | -------------------------------- |
| **RLS**         | Testing row-level security policies          | `hr-employees.rls.test.ts`       |
| **Unit**        | Testing isolated functions, hooks, utilities | `hr/useEmployees.test.ts`        |
| **Integration** | Testing cross-component workflows            | `hr/onboarding-workflow.test.ts` |
| **E2E**         | Testing complete user journeys               | `hr/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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

* [Test Templates](../../specs/_templates/tests/)
* [Testing Improvements](./TESTING_IMPROVEMENTS.md)
* [Test Utilities README](../../tests/utils/README.md)