Skip to content

5.1 Unit Tests and Fixtures

Jump to bottom
coding man edited this page Nov 4, 2026 · 1 revision

Unit Tests and Fixtures

Relevant source files

The following files were used as context for generating this wiki page:

Purpose and Scope

This page details the unit testing infrastructure of VariantScope, located under the tests/unit directory. Powered by Vitest, the test suites validate core modules in isolation using dependency mocking and static API snapshots (tests/fixtures). This ensures fast, deterministic validation of biological data pipelines, coordinate/protein-change matching, error handling, partial source failures, and statistical summarization without relying on external network services.

1. Test Fixtures and Loader Architecture

Real API responses from UniProt, AlphaFold, NCBI ClinVar (E-utilities), and gnomAD GraphQL endpoints are trimmed and saved as static JSON and PDB files inside tests/fixtures tests/fixtures/README.md:1-10.

The fixture loader helper function fixture(name) tests/unit/fixture.js:6-9 reads these snapshots synchronously from disk using node:fs tests/unit/fixture.js:2-3. If the requested file ends with .json, it parses the string via JSON.parse(); otherwise, it returns raw text (such as PDB coordinate files).

graph TD
    sub51_loader["tests/unit/fixture.js"] -->|"readFileSync()"| sub51_dir["tests/fixtures/"]
    sub51_dir -->|"uniprot-TP53.json"| sub51_src["tests/unit/sources.test.js"]
    sub51_dir -->|"alphafold-P04637-residues1-25.pdb"| sub51_src
    sub51_dir -->|"gnomad-TP53-variants.json"| sub51_src
    sub51_dir -->|"clinvar-TP53-esummary.json"| sub51_join["tests/unit/join.test.js"]

    classDef default stroke:#333,fill:#fff;
Loading

Figure 5.1.1: Fixture loading data flow from static snapshots to unit test suites.

Sources: tests/fixtures/README.md:1-10, tests/unit/fixture.js:1-9, tests/unit/sources.test.js:1-167

2. Core Module Unit Test Suites

2.1 Pipeline Orchestration (pipeline.test.js)

The orchestrator test suite validates loadGene across success paths, partial data degradation, and cancellation tests/unit/pipeline.test.js:1-150.

Key behaviors verified:

  • Successful integration: When all core fetchers (fetchUniprot, fetchAlphaFold, fetchClinvar, fetchGnomadVariants, fetchGnomadConstraint) succeed, variants are correctly joined, assigned rarity tiers, and checked for numbering alignment tests/unit/pipeline.test.js:56-65.
  • Alias resolution: The typed user query is sent to UniProt to resolve official symbols, which are subsequently propagated to downstream fetchers tests/unit/pipeline.test.js:67-71.
  • Partial failures: If fetchGnomadVariants fails, the pipeline still yields ClinVar variants and AlphaFold structures, setting variant rarity to 'unknown' rather than 'absent' tests/unit/pipeline.test.js:73-80.
  • Abort propagation: AbortSignal instances are correctly passed through to all underlying fetch operations tests/unit/pipeline.test.js:137-149.
graph TD
    sub51_lg["loadGene()"] -->|"1. fetchUniprot"| sub51_fu["src/core/uniprot.js"]
    sub51_lg -->|"2. fetchAlphaFold"| sub51_fa["src/core/alphafold.js"]
    sub51_lg -->|"3. fetchClinvar"| sub51_fc["src/core/clinvar.js"]
    sub51_lg -->|"4. fetchGnomadVariants"| sub51_fg["src/core/gnomad.js"]
    sub51_fu -->|"Accession & Sequence"| sub51_join["src/core/join.js"]
    sub51_fa -->|"pLDDT Array"| sub51_join
    sub51_fc -->|"ClinVar Variants"| sub51_join
    sub51_fg -->|"gnomAD Frequencies"| sub51_join

    classDef default stroke:#333,fill:#fff;
Loading

Figure 5.1.2: Pipeline test orchestration flow linking core modules to integration tests in pipeline.test.js.

Sources: tests/unit/pipeline.test.js:1-150

2.2 Source Adapters and Parsers (sources.test.js, parse.test.js)

Individual data adapters and parsing routines are tested using fixture payloads:

  • Symbol Validation: isValidGeneSymbol ensures only valid alphanumeric symbols and hyphens pass, rejecting SQL injection vectors or malformed strings tests/unit/sources.test.js:23-31.
  • UniProt Parsing: fetchUniprot extracts accessions, lengths, protein names, and reference sequences while flagging aliases tests/unit/sources.test.js:33-55.
  • AlphaFold pLDDT Extraction: parsePlddt correctly reads B-factor columns from C-atom PDB lines, ignoring non-ATOM entries tests/unit/sources.test.js:88-112.
  • Protein Change Parsing: parseProteinChange handles standard 3-letter/1-letter amino acid conversions, strips transcript prefixes, and correctly categorizes mutations to skip (such as frameshifts, stop-gained, or synonymous changes) tests/unit/parse.test.js:1-97.
  • Classification Normalization: normalizeClassification maps raw ClinVar strings (e.g., "Pathogenic/Likely pathogenic") to canonical buckets ("Pathogenic", "VUS", "Benign", etc.) tests/unit/parse.test.js:117-139.

Sources: tests/unit/sources.test.js:1-167, tests/unit/parse.test.js:1-161

2.3 Joining, Numbering, and Statistics (join.test.js, stats.test.js)

Data merging and statistical computations are verified against both hand-crafted minimal inputs and full-scale TP53 fixture datasets:

  • Coordinate vs Protein-Change Matching: joinVariants prioritizes exact genomic coordinate keys (chr-pos-ref-alt) and falls back to unique protein changes only when coordinates are absent tests/unit/join.test.js:37-98.
  • Numbering Verification: checkNumbering and numberingReport flag sequences where fewer than 95% (NUMBERING_MIN_RATE) of ClinVar reference residues match the UniProt reference sequence tests/unit/join.test.js:141-163.
  • Rarity Thresholds: rarityFromAf enforces exact allele frequency boundaries (e.g., ultra-rare $< 10^{-5}$, rare $< 10^{-4}$, low-frequency $< 10^{-2}$, common $\ge 10^{-2}$) tests/unit/stats.test.js:11-33.
  • Density Windows: densityWindows computes sliding window variant counts across residue positions tests/unit/stats.test.js:50-79.
  • Summary Statistics: summarize calculates pathogenic shares, confident region subsets (pLDDT $\ge 70$), and rarity distributions while excluding unaligned numbering records tests/unit/stats.test.js:81-139.

Sources: tests/unit/join.test.js:1-174, tests/unit/stats.test.js:1-139

Content imported from DeepWiki.

VariantScope Wiki

Clone this wiki locally