Cypress E2E Testing
Relevant source files
The following files were used as context for generating this wiki page:
Cypress is utilized in this project to perform functional testing of the built application through the user interface. While these tests interact with the UI, the current implementation stubs all server data using intercepts and fixtures, meaning they operate as isolated integration tests rather than full end-to-end tests involving a live backend.
Tests are organized primarily by application section and feature, such as test/integration/clinicians or test/integration/patients/patient. These tests prioritize the validation of business logic: how data is created, displayed, stored, and modified across different interfaces.
Sources: test/README.md:1-48, AGENTS.md:18-20
Testing Architecture
The testing framework is built on Cypress and integrated with the project's build toolchain (Vite). It utilizes a stubbed API layer to simulate backend responses, allowing for deterministic testing of UI states.
Execution Flow
The following diagram illustrates how Cypress interacts with the application and the stubbed API during a typical test run:
This flow ensures that the frontend logic can be tested independently of backend availability.
Sources: test/README.md:16-19, test/README.md:71-77
Synchronization Strategies
To avoid flaky tests, the project follows specific synchronization strategies:
- Observable State: Prefer route aliases for network lifecycles using
cy.wait('@alias'). - Retrying Assertions: Use
cy.get()with appropriate timeouts to wait for rendered state. - Clock Control: Use
cy.clock()andcy.tick()for testing debounced inputs or timers, rather than arbitrarycy.wait(ms).
Sources: test/README.md:52-65
API Stubbing and Composition
API routes are configured in test/support/api/ and organized by model or collection. The framework uses a mutation pattern to allow individual tests to modify standard fixture data for specific scenarios.
Citations: test/README.md:71-92
Common API Commands
The system includes global configurations and API stubs loaded automatically via test/support/e2e.js.
| Command Category | Purpose | Example File Reference |
|---|---|---|
| Auth/Clinicians | Handle login and clinician profiles | test/support/api/clinicians |
| Flows/Actions | Manage patient workflows and tasks | test/support/api/actions |
| Programs | Manage administrative program structures | test/support/api/programs |
| Workspaces | Context for patient and form data | test/support/api/workspaces |
Sources: test/support/e2e.js:12-42
Component and Integration Testing
The project distinguishes between component tests and routed integration tests.
Test Organization
- Component Specs: Located next to source code as
src/**/*.cy.js. - Integration Specs: Located under
test/integration/**/*.js. - Fixtures: JSON files stored in
test/fixtures/representing reusable portions of API data.
Sources: test/README.md:28-33, AGENTS.md:18-20
Real-time Updates (WebSockets)
Integration tests verify WebSocket behavior by sending mock messages to the application to trigger UI updates without full page reloads.
// Example of triggering a WebSocket update in a test
cy.sendWs({
category: 'NameChanged',
resource: { type: 'actions', id: testActionId },
payload: { attributes: { name: 'New Name' } }
});
cy.get('[data-testid="name-field"]').should('contain', 'New Name');
Sources: test/integration/patients/patient/patient-flow.js:130-145, test/integration/patients/patient/dashboard.js:770-785
Code Coverage
The project enforces a strict "merged coverage" contract, combining results from Cypress (browser/integration) and Vitest (unit).
Coverage Requirements
- Source of Truth:
.nyc_output/merged.json. - Baseline: 100% for statements, functions, lines, and branches.
- Enforcement:
npm run coverage:check:baselineensures the repo-wide baseline is met.
| Command | Description |
|---|---|
npm run coverage | Runs full suite and generates merged report |
npm run coverage:e2e | Executes Cypress integration tests with instrumentation |
npm run coverage:component | Executes Cypress component tests |
Sources: test/README.md:3-14, package.json:44-53
Conclusion
Cypress E2E testing in this repository serves as a robust functional validation layer. By combining comprehensive API stubbing with WebSocket simulation and strict 100% coverage requirements, the system ensures that complex business logic and UI states remain stable across the patient and administrative dashboards.
Sources: test/README.md:46-48, package.json:44-46