Testing Strategy & Frameworks
Relevant source files
The following files were used as context for generating this wiki page:
- frontend/README.md
- DO NOT DELETE EDL PIPELINE/README.md
- DO NOT DELETE EDL PIPELINE/tests/test_runner.py
- DO NOT DELETE EDL PIPELINE/tests/test_integrity.py
- frontend/src/tests/conditionModals.test.tsx
- frontend/src/tests/snapshotEngine.test.ts
- DO NOT DELETE EDL PIPELINE/src/edl_pipeline/runner.py
- CONTRIBUTING.md
Nexus Scanner employs a multi-layered testing strategy to ensure the integrity of its equity research data and the reliability of its frontend screening engine. The strategy combines automated unit tests, pipeline validation gates, and integrity checks to verify data transformations from raw exchange inputs to immutable scanner revisions.
The project splits testing between the Python EDL Pipeline (backend data generation) and the React/TypeScript Frontend (browser-based evaluation). Backend tests verify deterministic transform helpers and pipeline orchestration, while frontend tests ensure the correctness of the snapshot engine, Web Workers, and UI condition builders.
Pipeline Validation & Integrity
The EDL (Extract, Data, Load) pipeline uses validation gates to prevent the promotion of invalid data. Scripts within the pipeline must exit with a non-zero code if they fail to produce required artifacts.
Validation Gates
The pipeline validates artifacts after each script execution and performs a final check on the complete output set before publication. Required script failures halt the pipeline, while enrichment failures are reported as warnings.
| Validation Type | Component | Description |
|---|---|---|
| Schema Validation | ArtifactSpec | Verifies required fields, counts, and JSON/Gzip integrity. |
| Freshness Gates | inspect_publication | Checks for stale sessions, date alignment, and missing indicators. |
| Integrity Checks | test_integrity.py | Verifies data logic (e.g., EOD2 history overlays, earnings date parsing). |
| Coverage Gates | MINIMUM_HISTORY_COVERAGE | Requires at least 90% equity history coverage for breadth artifacts. |
Sources: DO NOT DELETE EDL PIPELINE/src/edl_pipeline/runner.py:53-67, DO NOT DELETE EDL PIPELINE/README.md:120-130, DO NOT DELETE EDL PIPELINE/process_mbi_market_breadth.py:27-28
Pipeline Execution Flow
The following diagram illustrates how the pipeline runner orchestrates scripts and validates their outputs:
Frontend Testing Framework
The frontend uses Vitest and React Testing Library for component and logic verification. Tests run in a JSDOM environment and simulate user interactions with screening modals and the snapshot engine.
Snapshot Engine Testing
The snapshotEngine.test.ts file verifies the core screening logic, including:
- Concurrent Task Handling: Ensures a revision loads only once for multiple screen and comparison tasks.
- Cache Reuse: Verifies that match sets are reused when only pagination changes.
- Worker Resiliency: Tests Web Worker lifecycle, including timeouts and fallback to the main thread if construction is blocked (e.g., by CSP).
- Gzip Decompression: Confirms the client can fetch and decode columnar-encoded Gzip snapshots.
Sources: frontend/src/tests/snapshotEngine.test.ts:25-30, frontend/src/tests/snapshotEngine.test.ts:81-88, frontend/README.md:460-475
UI & Condition Testing
Component tests in conditionModals.test.tsx validate the ScreenerModal and ConditionCatalogModal.
- Parameter Contracts: Ensures inputs like boolean checkboxes, numeric spinbuttons, and select dropdowns (e.g., F&O status) correctly map to the underlying expression tree.
- State Persistence: Verifies that edited rows are retained during category switches and that the "Reset" action restores defaults.
- Validation Logic: Blocks the "Apply" button when required numeric fields are cleared.
Sources: frontend/src/tests/conditionModals.test.tsx:44-55, frontend/src/tests/conditionModals.test.tsx:84-100
Testing Procedures
Developers must verify changes before opening pull requests using specific commands for each environment.
Backend (Python)
Run unit tests for deterministic transform helpers:
cd "DO NOT DELETE EDL PIPELINE"
python3 -m unittest discover -s tests -v
To check pipeline ordering and schemas without live endpoint hits:
EDL_FETCH_OHLCV=0 EDL_CLEANUP_INTERMEDIATE=0 python3 run_full_pipeline.py
Sources: CONTRIBUTING.md:12-25, DO NOT DELETE EDL PIPELINE/README.md:151-155
Frontend (Node.js)
Execute the Vitest suite:
cd frontend
npm test
Sources: frontend/package.json:10, frontend/README.md:520-525
Summary of Frameworks
| Environment | Primary Tool | Purpose |
|---|---|---|
| Python Backend | unittest | Data transformation and pipeline runner logic. |
| Frontend Core | vitest | Engine logic, Web Worker orchestration, and Gzip decoding. |
| Frontend UI | React Testing Library | Component state, user interaction, and condition building. |
| CI Validation | ArtifactSpec / inspect_publication | Automated schema and data quality enforcement. |
Sources: frontend/package.json:20-35, DO NOT DELETE EDL PIPELINE/src/edl_pipeline/runner.py:200-210, CONTRIBUTING.md:27-35
Testing in Nexus Scanner ensures that the immutable data releases consumed by the frontend are accurate and that the browser-based screening engine correctly evaluates complex financial conditions across thousands of symbols.