Integration Testing Suite
Relevant source files
The following files were used as context for generating this wiki page:
The Integration Testing Suite validates the core API logic, database interactions, and multi-tenant isolation within the Digital Health Care platform. It executes against a dedicated PostgreSQL instance defined by the TEST_DATABASE_URL environment variable to ensure that business rules, clinical workflows, and security policies function correctly in a real-world environment.
This suite utilizes Vitest as the test runner and provides a custom testing harness to manage the Fastify application lifecycle and database state between test runs. It specifically focuses on verifying row-level security (RLS) and complex clinical processes like scheduling, patient registration, and consultation management.
Sources: README.md:52-56, apps/api/vitest.integration.config.ts
Core Architecture and Lifecycle
The integration suite relies on a global setup and a per-test harness to maintain environment consistency and test isolation.
Global Setup
The global-setup.ts file prepares the environment before any tests execute. It ensures the NODE_ENV is set to test and verifies that the TEST_DATABASE_URL is provided. This prevents accidental execution against production or development databases.
Sources: apps/api/test/global-setup.ts
Testing Harness
The createHarness function in harness.ts initializes the core components for each test file. It creates a Prisma client instance (owner) and builds the Fastify application with specific configurations, such as setting the LOG_LEVEL to silent.
Sources: apps/api/test/harness.ts:16-25
The diagram above illustrates the typical lifecycle of an integration test, from environment setup to database cleanup.
Sources: apps/api/test/harness.ts, apps/api/test/clinical.int.test.ts:37-45
Database Management
Tests use a strategy of truncation rather than rebuilding migrations to maintain speed. The resetDatabase utility identifies all tables in the public schema (excluding system tables like _prisma_migrations) and executes a TRUNCATE command with CASCADE.
Sources: apps/api/test/harness.ts:27-38
Tenancy and Seeding Utilities
To test multi-tenant isolation, the suite provides utilities to create multiple organizations and staff members:
- seedTwoClinics: Creates two distinct organizations (
clinic-a,clinic-b) each with a clinic admin and a doctor. This is primarily used to verify that data from one tenant is never accessible to another. - addStaff: Dynamically adds staff members with specific roles (e.g.,
front_desk,doctor) to an existing organization. - staffLogin: Simulates a login by generating a mock
TokenResponse, including anaccessToken, to be used in subsequent request headers.
Sources: apps/api/test/harness.ts:40-100
Clinical Workflow Testing
Integration tests verify complex state transitions and clinical rules across different modules.
Consultation and Vitals
The clinical.int.test.ts file validates the consultation lifecycle. It ensures that only the assigned doctor can record notes and that these notes are stored encrypted in the database.
Sources: apps/api/test/clinical.int.test.ts:60-120
| Feature | Validation Rule | Source File |
|---|---|---|
| Note Encryption | Notes must start with v1. and not contain plain text clinical data in the DB. | apps/api/test/clinical.int.test.ts:79-81 |
| Access Control | Front desk and admins are forbidden (403) from viewing consultation notes. | apps/api/test/clinical.int.test.ts:114-118 |
| Locking | Once a prescription is signed/locked, notes and vitals become immutable (409). | apps/api/test/clinical.int.test.ts:140-160 |
| BMI Calculation | The system automatically calculates BMI when weight and height are provided. | apps/api/test/clinical.int.test.ts:178-180 |
Scheduling and Availability
The suite verifies that doctor availability is correctly translated into bookable slots while accounting for leaves and holidays.
Sources: apps/api/test/scheduling.int.test.ts:80-150
The sequence diagram shows how availability data is posted and then retrieved as calculated slots by the API.
Sources: apps/api/test/scheduling.int.test.ts:88-105
Security and Isolation Testing
A critical component of the suite is verifying Tenant Isolation. Tests explicitly attempt to access resources across organizational boundaries to ensure the Row-Level Security (RLS) policies and app_current_organisation_id() context are functioning.
- Cross-Tenant Access: Tests verify that a doctor from Clinic B receives a
404 Not Foundwhen attempting to access a consultation or patient chart belonging to Clinic A. - Audit Logging: Tests assert that significant actions (e.g.,
patient.created,consultation.saved,allergy.removed) generate appropriate audit logs without leaking sensitive data into the log metadata.
Sources: apps/api/test/clinical.int.test.ts:258-270, apps/api/test/patients.int.test.ts:87-95
Configuration Summary
The integration tests are configured via Vitest with the following parameters:
| Parameter | Value | Description |
|---|---|---|
include | **/*.int.test.ts | Matches files ending in .int.test.ts |
globalSetup | ./test/global-setup.ts | Path to the environment initialization script |
testTimeout | 30000ms | Maximum duration allowed per test |
hookTimeout | 30000ms | Maximum duration for beforeEach/afterAll hooks |
| Sources: apps/api/vitest.integration.config.ts |
The Integration Testing Suite ensures that the Digital Health Care platform maintains strict data boundaries and clinical accuracy by simulating real API traffic against a managed database instance.