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

# Test Coverage

> Complete inventory of every test — what it proves, how to run it

# Test Coverage

> Verified snapshot: `634` Vitest cases (`634 passed`, `0 skipped`) and `93` Playwright executions (`31` specs x `3` browsers). Playwright static skip directives remain blocked in `apps/terra/tests`.

```bash theme={null}
# Run everything
pnpm --dir apps/terra test

# List Playwright inventory
pnpm --dir apps/terra exec playwright test --list
```

***

## Summary

| Area                        | Current state          | Notes                                                                                              |
| --------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------- |
| Unit + Integration (Vitest) | 634 passing, 0 skipped | Duplicate-form and notification trend suites are now active and stable                             |
| E2E policy                  | Enforced               | `check-terra-skipped-tests.mjs` blocks `test.skip/describe.skip/it.skip` in Terra Playwright specs |
| E2E inventory               | 31 specs x 3 browsers  | 93 total listed runs in current Playwright config                                                  |
| CI hard gates               | Enabled                | CI enforces no-skipped Playwright specs and runs Chromium status smoke tests                       |

***

## Auth & Permissions (71 cases)

<Accordion title="Auth Guards — 25 cases">
  `src/lib/__tests__/auth-guards.test.ts`

  ```bash theme={null}
  pnpm --dir apps/terra test -- -t "Auth Guards"
  ```

  Covers `requireAdmin`, `requireSuperAdmin`, `requireFormAccess`, `requireFormViewAccess` and their result-based variants (`checkAdmin`, `checkFormAccess`), plus `withAdminAuth` / `withFormAuth` wrapper decorators. Proves missing sessions, wrong roles, and nonexistent forms are all caught.
</Accordion>

<Accordion title="Team Permissions — 12 cases">
  `src/app/actions/__tests__/team-permissions.test.ts`

  ```bash theme={null}
  pnpm --dir apps/terra test -- -t "Team Permissions"
  ```

  Covers `canEditForm`, `canViewForm`, `canManageTeam`. Proves the critical invariant: global `viewer` overrides form `owner`. Also covers migration backwards compat and global `editor` override.
</Accordion>

<Accordion title="Permission System — 28 cases">
  `src/app/actions/__tests__/permissions.test.ts`

  ```bash theme={null}
  pnpm --dir apps/terra test -- -t "Permission System"
  ```

  Broader RBAC coverage: `isSuperAdmin`, `getUserFormRole`, cross-form access denial, privilege escalation prevention, last-owner protection, scope enforcement.
</Accordion>

<Accordion title="Submission Management — 3 cases">
  `src/app/actions/__tests__/submission-management.test.ts`

  ```bash theme={null}
  pnpm --dir apps/terra test -- -t "submission-management"
  ```

  Scoped users with no forms see nothing. Viewers cannot bulk-modify. Editors can.
</Accordion>

<Accordion title="System Auth — 3 cases">
  `src/app/actions/__tests__/system-auth.test.ts`

  ```bash theme={null}
  pnpm --dir apps/terra test -- -t "system action authorization"
  ```

  Non-admins blocked from user list, admin invites, and role changes.
</Accordion>

***

## Data Protection (61 cases)

<Accordion title="Encryption — 32 cases">
  `src/lib/__tests__/encryption.test.ts`

  ```bash theme={null}
  pnpm --dir apps/terra test -- -t "Encryption Module"
  ```

  Round-trip encryption, random IV, special chars, unicode, bank data, Plaid data, submission-level PII, confirmation field stripping, masking, error handling on malformed ciphertext.
</Accordion>

<Accordion title="Audit Logging — 29 cases">
  `src/lib/__tests__/audit.test.ts`

  ```bash theme={null}
  pnpm --dir apps/terra test -- -t "Audit Module"
  ```

  IP anonymization, session handling, change tracking, failure recording, all action types (form CRUD, publish, team, status, sync), entity and user activity queries.
</Accordion>

***

## Input Validation (123 cases)

<Accordion title="Security Utilities — 72 cases">
  `src/lib/__tests__/security.test.ts`

  ```bash theme={null}
  pnpm --dir apps/terra test -- -t "Path Traversal"
  pnpm --dir apps/terra test -- -t "Open Redirect"
  pnpm --dir apps/terra test -- -t "File Upload Security"
  ```

  Path traversal (10+ vectors), filename cleaning, safe storage paths, open redirect prevention, external URL validation, same-origin enforcement, file type/MIME/size validation, embedded script detection, TOCTOU prevention, full upload flow integration.
</Accordion>

<Accordion title="File Operations — 15 cases">
  `src/app/actions/__tests__/files-security.test.ts`

  ```bash theme={null}
  pnpm --dir apps/terra test -- -t "File Security"
  ```

  Delete/URL authorization, cross-form access blocked, path traversal on operations, null bytes, empty paths, super\_admin bypass.
</Accordion>

<Accordion title="Import Security — 11 cases">
  `src/app/actions/__tests__/import-security.test.ts`

  ```bash theme={null}
  pnpm --dir apps/terra test -- -t "Import Security"
  ```

  User impersonation prevention, session-only user ID, job isolation, image count limit, PDF size/type validation.
</Accordion>

<Accordion title="Rate Limiting — 25 cases">
  `src/lib/__tests__/rate-limit.test.ts`

  ```bash theme={null}
  pnpm --dir apps/terra test -- -t "Rate Limiting"
  ```

  Limit values, fail-open/closed behavior, IP extraction from proxy headers, enumeration prevention (status \< submissions), header formatting.
</Accordion>

***

## Integrations (66 cases)

<Accordion title="Webhooks — 29 cases">
  `src/app/actions/__tests__/webhooks.test.ts` + `src/lib/__tests__/webhook-security.test.ts`

  ```bash theme={null}
  pnpm --dir apps/terra test -- -t "Webhook"
  pnpm --dir apps/terra test -- -t "webhook-security"
  ```

  Auth on all operations, URL validation, secret generation/regeneration, HMAC consistency, unsigned blocked in prod, timestamp freshness, fire-and-forget failure handling.
</Accordion>

<Accordion title="Airtable Sync — 16 cases">
  `src/app/actions/__tests__/airtable-status-sync.test.ts`

  ```bash theme={null}
  pnpm --dir apps/terra test -- -t "Airtable Status Sync"
  ```

  Connection/disabled/unmapped skip, status validation, no-delete safety, sync loop prevention, change source tracking.
</Accordion>

<Accordion title="Async Queue — 21 cases">
  `src/lib/__tests__/async-queue.test.ts`

  ```bash theme={null}
  pnpm --dir apps/terra test -- -t "Async Queue"
  ```

  Enqueue/complete/fail/claim/retry/cancel, operation types, backoff formula, error handling, complex payloads.
</Accordion>

***

## Notifications (35 cases)

<Accordion title="Notification Events — 35 cases (running)">
  `src/app/actions/__tests__/notifications.test.ts`

  ```bash theme={null}
  pnpm --dir apps/terra test -- -t "Notification"
  ```

  Event retrieval, filtering, pagination, stats math, error categorization, and 7-day/30-day trend calculations are all running with deterministic time-mocking.
</Accordion>

<Accordion title="Provider Tests — 7 cases">
  `src/app/actions/__tests__/notification-test.test.ts`

  Admin-only enforcement, missing config handling, provider status.
</Accordion>

<Accordion title="Form Settings — 6 cases">
  `src/app/actions/__tests__/form-notification-settings.test.ts`

  Auth enforcement, get/save settings, insert vs update path, null handling.
</Accordion>

***

## Form Engine (95 cases)

<Accordion title="Form Renderer — 10 cases">
  `src/components/engine/__tests__/form-renderer.test.tsx`

  ```bash theme={null}
  pnpm --dir apps/terra test -- -t "FormRenderer"
  ```

  Renders all fields, required indicators, read-only mode, field visibility, conditional rendering.
</Accordion>

<Accordion title="Renderer — 15 cases">
  `src/components/engine/renderer.test.tsx`

  ```bash theme={null}
  pnpm --dir apps/terra test -- -t "Renderer"
  ```

  Core form rendering engine: page navigation, field rendering, validation, submission flow.
</Accordion>

<Accordion title="Field Key Generation — 26 cases">
  `src/lib/__tests__/field-key.test.ts`

  ```bash theme={null}
  pnpm --dir apps/terra test -- -t "field key"
  ```

  Human-readable key generation from labels, uniqueness, special character handling, collision avoidance.
</Accordion>

<Accordion title="Text Field — 13 cases">
  `src/components/engine/fields/__tests__/text-field.test.tsx`

  Text input rendering, validation, placeholder behavior, character limits, input masking.
</Accordion>

<Accordion title="Choice Field — 11 cases">
  `src/components/engine/fields/__tests__/choice-field.test.tsx`

  Radio/checkbox/dropdown rendering, selection behavior, multi-select, "other" option handling.
</Accordion>

<Accordion title="Form Submission Integration — 10 cases">
  `src/components/engine/__tests__/form-submission-integration.test.tsx`

  End-to-end form fill and submit flow, validation errors, success confirmation.
</Accordion>

<Accordion title="Form Duplication — 10 cases (running)">
  `src/app/actions/__tests__/duplicate-form.test.ts`

  Covers copy schema behavior, draft reset, unique slug generation, branding/language copy, and alert/domain stripping with stable Supabase mocks.
</Accordion>

***

## Form Import (50 cases)

<Accordion title="HTML Extractor — 10 cases">
  `src/lib/form-import/__tests__/html-extractor.test.ts`

  Extracts text/email inputs, select/dropdown fields, textareas. Skips hidden inputs and submit buttons.
</Accordion>

<Accordion title="Element Validation — 16 cases">
  `src/lib/form-import/__tests__/element-validation.test.ts`

  Validates extracted form elements: required fields, types, labels, options, nested structures.
</Accordion>

<Accordion title="JSON Extraction — 12 cases">
  `src/lib/form-import/__tests__/json-extraction.test.ts`

  Parses AI-generated JSON into form schema, handles malformed input, edge cases.
</Accordion>

<Accordion title="PDF Processing — 7 cases">
  `src/lib/form-import/__tests__/pdf-normalization.test.ts` (6 cases)
  `src/lib/form-import/__tests__/pdf-preprocessor.test.ts` (1 case)

  PDF text extraction, normalization, layout detection.
</Accordion>

<Accordion title="Image Import & Metrics — 5 cases">
  `src/lib/form-import/__tests__/image-import.test.ts` (1 case)
  `src/lib/form-import/__tests__/import-metrics.test.ts` (2 cases)
  `src/lib/form-import/__tests__/import-review.test.ts` (2 cases)

  Image-to-form conversion, import quality metrics, review workflow.
</Accordion>

***

## E2E Tests (31 specs, 93 browser executions)

<Info>
  Terra Playwright specs no longer rely on static `test.skip/describe.skip`. CI
  blocks new skipped directives and runs public status smoke checks in Chromium.
</Info>

<Accordion title="Status Lookup — 19 cases (running)">
  `tests/status-lookup.spec.ts`

  Page loads, heading visible, search form present, empty submit blocked, uppercase input accepted, validation flows.
</Accordion>

<Accordion title="Form Submission — deterministic fixture handling">
  `tests/submission.spec.ts`

  Validation errors on empty form and successful submit flow. CI fails fast when required fixtures are missing; local runs can opt into explicit fixture bypass for exploratory work.
</Accordion>

<Accordion title="Example — 2 cases (running)">
  `tests/example.spec.ts`

  Playwright default example tests.
</Accordion>

***

<CardGroup cols={2}>
  <Card title="Known Gaps" icon="triangle-exclamation" href="/review/known-gaps">
    What's missing and the remediation plan
  </Card>

  <Card title="Security" icon="shield" href="/review/security">
    Security review with code examples
  </Card>
</CardGroup>