Automated Testing Strategy
Relevant source files
The following files were used as context for generating this wiki page:
The automated testing strategy for the OpenMRS project is a multi-layered approach designed to ensure high code quality, feature reliability, and stable deployments across its diverse microfrontend and AI backend ecosystem. It integrates Test-Driven Development (TDD) principles, rigorous code coverage requirements, and tiered testing environments ranging from local unit tests to cloud-based End-to-End (E2E) suites.
Sources: conductor/workflow.md:3-8, README.md:126-150
Testing Principles and Methodology
The project adheres to a strict "User Experience First" philosophy, supported by a deliberate technical stack and a rigorous task lifecycle. Central to this is the requirement for Test-Driven Development (TDD) and high quantitative quality gates.
Test-Driven Development (TDD) Lifecycle
All development tasks follow a "Red-Green-Refactor" cycle to ensure that functionality is defined by tests before implementation begins.
The strategy mandates running tests in non-interactive mode using CI=true for tools like linters and test runners to ensure consistent execution in both local and CI environments.
Sources: conductor/workflow.md:3-33, conductor/workflow.md:79-84
Tiers of Testing
The strategy is divided into distinct tiers, each targeting different levels of the application stack, from individual modules to integrated user flows.
1. Unit Testing
Unit tests are mandatory for every module. They utilize setup and teardown mechanisms (e.g., fixtures, beforeEach/afterEach) and mock external dependencies to isolate code logic. For the Python AI backend, pytest is the primary tool, while frontend packages use yarn turbo run test.
2. Integration Testing
Integration tests focus on complete user flows, including database transactions, authentication, and form submissions. In the patient chart modules, this includes validating dynamic form generation based on concept metadata (e.g., range limits and decimal restrictions).
3. End-to-End (E2E) Testing
E2E tests use Playwright to simulate real user interactions against a full environment. These tests can run against a local backend or a remote instance (e.g., dev3.openmrs.org).
| Component | Tooling | Scope |
|---|---|---|
| Frontend (ESM) | Playwright, Vitest/Jest | UI components, Order Basket, Lab results |
| AI Backend | Pytest | Transcription, OCR, Vitals extraction |
| Mobile | Safari DevTools | Touch interactions, Responsive layouts |
Sources: conductor/workflow.md:86-98, openmrs-esm-patient-chart-main/README.md:46-64, openmrs-esm-patient-chart-main/README.md:89-115, openmrs-esm-patient-chart-main/packages/esm-patient-orders-app/README.md:65-71
Quality Gates and Coverage
Before any task or phase is considered "Done," it must pass several quality gates. The most critical quantitative metric is a code coverage target of >80% for all new code.
Verification Protocol
Upon phase completion, the following automated protocol is triggered:
- Determine Scope: Use
git diff --name-onlyto identify all code files changed in the phase. - Verify Test Existence: Ensure every modified code file has a corresponding test file following the project's naming conventions.
- Automated Execution: Run the test suite via commands like
CI=true npm testoryarn turbo run coverage. - Proactive Debugging: If tests fail, developers are permitted a maximum of two fix attempts before escalation is required.
Sources: conductor/workflow.md:40-62, conductor/workflow.md:143-154, readmes/COMPLETION_CHECKLIST.md:145-155
Development and Testing Commands
Standardized commands are used across the repository to maintain consistency in testing and verification.
Frontend Package Testing
# Run unit and integration tests for all packages
yarn turbo run test
# Run tests in watch mode for a specific package
yarn turbo run test:watch --filter=@openmrs/esm-patient-conditions-app
# Generate coverage reports
yarn turbo run coverage
Sources: openmrs-esm-patient-chart-main/README.md:46-75
Backend Python Testing
# Run tests for a single file
pytest <test_file>.py
# Run all tests with coverage
pytest --cov=app --cov-report=html
Sources: opencode.md:5-10, conductor/workflow.md:31-33
Playwright E2E Execution
# Run all E2E tests in headless mode
yarn test-e2e
# Run tests in UI mode (interactive debugger)
yarn test-e2e --headed --ui
Sources: openmrs-esm-patient-chart-main/README.md:105-115
Mobile and UI Verification
The strategy includes specific requirements for mobile responsiveness, particularly for patient-facing and clinical data entry tools.
- Mobile Testing: Testing on actual iPhone hardware when possible, using Safari developer tools for touch interaction and layout verification.
- Touch Targets: Ensuring targets meet a minimum size of 44x44px.
- Accessibility: Leveraging Carbon Design System components to ensure proper ARIA labels and semantic HTML.
Sources: conductor/workflow.md:94-98, conductor/workflow.md:129-132, readmes/COMPLETION_CHECKLIST.md:124-130
Conclusion
The automated testing strategy for OpenMRS is built on the foundation of TDD and enforced through strict CI/CD quality gates. By combining modular unit tests, concept-aware integration tests, and Playwright-driven E2E scenarios, the project ensures that both core EHR functionalities and AI-enhanced features (like voice transcription and vitals extraction) remain resilient and user-centric. The requirement for 80% coverage and auditable verification reports attached via Git notes provides a transparent and high-quality development lifecycle.
Sources: conductor/workflow.md:156-168, readmes/COMPLETION_CHECKLIST.md:195-210