Test topology and validation

Test layers

Contract tests

The contract suite under tests/contract/ verifies the request and response shapes for the shared API surface.

client.test.js — API client headers, tenant propagation, base URL routing, and requestBulk behavior.
modelService.test.js — model CRUD request shapes and response normalization.
promptService.test.js — prompt bulk/v1 lanes, versioning, document generation, and validation.
schemaService.test.js — schema CRUD, versioning, generation, and processing rule resolution.
useCaseService.test.js, agentService.test.js, documentService.test.js — adjacent service contracts.

Unit tests

The unit suite under tests/unit/ verifies pure helpers and security guardrails.

RBAC and access control
sanitization and secure logging
schema utilities and JSON parsing
diffing and data filtering
normalization helpers
token/cache helpers
validation helpers

Component tests

src/components/sidebar/Sidebar.test.jsx and src/components/Topbar/Topbar.test.jsx cover the shared chrome that the protected workspace depends on.

End-to-end workflows

The Playwright suite under e2e/tests/workflow/ covers major user journeys such as:

batch processing,
schema verification,
agent preflight,
prompt preflight,
artifact management,
debug flows for agent and schema pages,
sample PDF creation.

Runner split

vitest is the primary unit/contract runner.
Playwright uses its own configuration and setup in playwright.config.ts / playwright.config.js.
tests/setup.js and e2e/global-setup.js provide different initialization layers for the two test systems.

Minimal validation by change area

Change area	Focused tests	Minimal validation
API client or auth headers	`tests/contract/client.test.js`	Run contract tests for API requests
Prompt flows	`tests/contract/promptService.test.js`	Run prompt contract tests
Schema flows	`tests/contract/schemaService.test.js`	Run schema contract tests
RBAC / auth helpers	`tests/unit/rbac.test.js`	Run the relevant unit test file
Sanitization / logging	`tests/unit/sanitize.test.js`, `tests/unit/secureLogger.test.js`	Run the helper-specific unit tests
Live test / extraction helpers	`tests/unit/dataFiltering.test.js`, `tests/unit/dataNormalization.test.js`	Run the helper tests, then the matching Playwright workflow if UI changed
Shared chrome	`src/components/sidebar/Sidebar.test.jsx`, `src/components/Topbar/Topbar.test.jsx`	Run the component test(s) and affected route workflow
Route or navigation changes	relevant Playwright workflow spec	Run the affected Playwright workflow

Validation commands

npm run test:run for the full Vitest suite.
npm run test:coverage when you need coverage feedback.
npx playwright test for the browser workflows.
npm run lint or npm run security:lint for static checks.

How to use this page

Pick the narrowest test that proves the behavior you changed first. Only broaden to the full suite when the change touches shared infrastructure or route composition.