Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/arrozet/caret/llms.txt

Use this file to discover all available pages before exploring further.

Caret uses a layered test strategy: Vitest for the React frontend and all Node backend services, and Pytest for the Python AI service. Unit tests validate individual functions, components, and classes in complete isolation from the network and database. Integration tests cover API boundaries, protocol behaviour, and multi-layer flows. End-to-end browser tests are planned via Playwright but are not yet configured in the repository — until they are, the collaboration debug harness serves as the primary manual E2E check.

​
Test Tooling at a Glance

AreaFrameworkEnvironment
FrontendVitest 4, jsdom, React Testing Libraryjsdom (browser-like)
Node services (api-gateway, auth, document, collab)Vitest 3Node
Python AI servicePytest, pytest-asyncioPython 3.x
E2ENot yet configured — Playwright planned—

​
Test File Locations

Tests live close to the code they cover. The following tree shows the canonical paths for each service: 
# Frontend
app/frontend/src/**/*.test.ts
app/frontend/src/**/*.test.tsx
app/frontend/src/**/*.integration.test.tsx

# Node backend services
app/backend/api-gateway/tests/unit/*.test.ts
app/backend/api-gateway/tests/integration/*.test.ts
app/backend/auth-service/tests/unit/*.test.ts
app/backend/auth-service/tests/integration/*.test.ts
app/backend/document-service/tests/unit/*.test.ts
app/backend/document-service/tests/integration/*.test.ts
app/backend/collab-service/tests/unit/*.test.ts
app/backend/collab-service/tests/integration/*.test.ts

# Python AI service
app/backend/ai-service/tests/unit/test_*.py
app/backend/ai-service/tests/integration/test_*.py

​
Frontend Testing

The frontend uses Vitest 4 with a jsdom environment and React Testing Library for rendering and interacting with components. There are two separate Vitest configuration files — vitest.unit.config.ts and vitest.integration.config.ts — so unit and integration suites can be run independently with different settings. src/test/setup.ts runs before every test suite and takes care of installing @testing-library/jest-dom matchers and mocking browser APIs that jsdom does not implement, such as matchMedia and scrollIntoView.

​
Frontend Commands

cd app/frontend

bun run test              # Run all tests (unit + integration) once
bun run test:unit         # Run unit tests only (vitest.unit.config.ts)
bun run test:integration  # Run integration tests only (vitest.integration.config.ts)
bun run test:watch        # Watch mode — re-runs on file changes

​
What the Frontend Tests Cover

  • Component states — rendering, conditional visibility, and error states for UI components.
  • Hooks and stores — Zustand stores and custom React hooks in isolation with mocked Supabase and API clients.
  • Editor utilities and extensions — Tiptap/ProseMirror extension logic and document transformation helpers.
  • AI streaming UI — chunk rendering and markdown display with mocked SSE streams.
  • Collaboration helpers — URL/session/presence utilities with mocked WebSocket and Y.js boundaries.
Running bun run build in app/frontend executes tsc -b && vite build, which runs the full TypeScript compiler before bundling. This catches type errors that Vitest’s transpile-only mode might miss. Make it a habit to run a build before opening a PR.

​
Node Service Testing

All four Node backend services share the same Vitest-based testing pattern. Use the commands below from inside each service directory, or use the Makefile shortcuts from the repository root.

​
Per-Service Commands

# From inside the service directory
bun run test:unit         # Unit tests only
bun run test:integration  # Integration tests only

# Examples for each service
cd app/backend/api-gateway   && bun run test:unit
cd app/backend/auth-service  && bun run test:unit
cd app/backend/document-service && bun run test:unit
cd app/backend/collab-service   && bun run test:unit

​
Makefile Shortcuts (From Repo Root)

make api-gateway-test-unit
make api-gateway-test-integration
make auth-service-test-unit
make auth-service-test-integration
make document-service-test-unit
make document-service-test-integration
make collab-service-test-unit
make collab-service-test-integration

​
What the Node Tests Cover

  • API Gateway — proxy routing logic, CORS header enforcement, rate-limit behaviour, and OpenAPI metadata endpoints.
  • Document service — request validation, repository and service-layer behaviour, permission checks, document CRUD flows, and correct HTTP status codes.
  • Auth service — JWT validation middleware and shared error-handling middleware.
  • Collab service — Y.js sync and awareness message handling at the protocol layer, CollabPersistenceService in isolation from WebSocket handling, JWT handshake validation, and repository behaviour for document_collab_updates and document_collab_snapshots.

​
AI Service Testing (Python / Pytest)

The Python AI service uses Pytest with pytest-asyncio for async test cases. Run tests from the app/backend/ai-service directory using uv.

​
AI Service Commands

cd app/backend/ai-service

uv run pytest                          # Run all tests
uv run pytest tests/unit -q            # Unit tests only, quiet output
uv run pytest tests/integration -q    # Integration tests only, quiet output

​
Makefile Shortcuts (From Repo Root)

make ai-service-test-unit
make ai-service-test-integration

​
What the AI Tests Cover

  • Pydantic schemas — request/response model validation and serialisation edge cases.
  • Agent orchestration — prompt assembly, dependency injection, and model catalog selection without calling real LLM providers.
  • SSE chunk behaviour — streaming output correctness with mocked provider clients.
  • Embedding indexing and search — pgvector query construction and result ranking with mocked embedding clients.
  • Repository behaviour — SQL query logic for AI tables and pgvector searches.

​
Linting and Formatting

Linting and format checks are a required step before committing. They run as the first stage in the CI pipeline.

​
Frontend and Node Services

# From inside a service directory
bun run lint            # ESLint — checks for code quality issues
bun run lint:fix        # ESLint with auto-fix
bun run format:check    # Prettier — checks formatting without writing changes
bun run format:write    # Prettier — auto-formats files

​
Makefile Shortcuts

make frontend-lint
make frontend-format-check
make document-service-lint
make collab-service-format-check
# ... and so on for each service

​
Python AI Service

The AI service uses Ruff for linting and Pyright for static type checking, both invoked through uv: 
cd app/backend/ai-service

uv run ruff check .         # Lint with Ruff
uv run ruff check . --fix   # Lint and auto-fix
uv run pyright              # Static type checking

# Makefile equivalents
make ai-service-lint
make ai-service-format-check

​
Test Principles

These principles guide how tests are written across all services:
  • Deterministic and network-free — unit tests must not make real HTTP, database, WebSocket, or LLM calls. Mock all external boundaries.
  • Mock at the right boundary — mock Supabase, Drizzle, SQLAlchemy, WebSocket, and LLM clients in unit tests; use real HTTP in integration tests.
  • API boundary behaviour in integration tests — route-level status codes, error shapes, and middleware interactions belong in integration tests, not unit tests.
  • Regression tests at the lowest useful layer — when fixing a bug, add a test at the layer where the bug lived.
  • No production data — never connect to real Supabase user data in automated tests. Use isolated test projects or mocked clients.
  • No secrets in test files — keep API keys, JWT secrets, and database URLs out of test source files and snapshots.
The collaboration debug harness at http://localhost:5173/debug/collab-harness is the recommended tool for manual WebSocket and Y.js synchronisation testing. It lets you simulate multiple connected clients from a single browser tab, observe sync messages, and inspect awareness state — useful for scenarios that are difficult to cover with automated tests.

​
Intended CI Order

The following pipeline order applies once GitHub Actions workflow files are added to the repository: 
1. Lint and format checks (ESLint, Prettier, Ruff)
2. Type checks and builds (tsc, Pyright, Vite build)
3. Unit tests (all services in parallel)
4. Integration tests
5. E2E smoke tests (when Playwright is configured)
6. Deploy from the prod branch only after all checks pass

Build docs developers (and LLMs) love

Get started for freeTalk to us