Testing Strategy
Relevant source files
The following files were used as context for generating this wiki page:
The testing strategy for the entities library is designed to ensure the high-performance encoding and decoding logic remains spec-compliant and free of regressions across various execution modes. The project utilizes Vitest as its primary test runner, augmented by Biome for linting and formatting verification.
The suite encompasses unit tests for core API functions, integration tests against official HTML/XML entity maps, streaming-specific validation, and specialized tests for the internal trie-based data structures.
Sources: package.json:67-68, src/decode.spec.ts:1
Core Testing Infrastructure
The project relies on a modern TypeScript testing stack. Tests are located alongside source code using the .spec.ts suffix. The package.json defines several test-related scripts to maintain code quality.
| Script | Command | Purpose |
|---|---|---|
test | npm run test:vi && npm run lint | Runs all Vitest tests and linters. |
test:vi | vitest run | Executes the Vitest test suite. |
lint | npm run lint:es && npm run lint:ts && npm run lint:biome | Multi-stage linting (ESLint, TS, Biome). |
benchmark | node --import=tsx scripts/benchmark.ts | Measures performance against competitors. |
Sources: package.json:57-68, biome.json:88-99
Multi-Implementation Validation
A significant portion of the decoding tests uses a "multi-implementation" approach. This ensures that synchronous decoding, streaming (all at once), and streaming (character-by-character) all produce identical results for the same input.
Streaming vs. Synchronous Flow
The following diagram illustrates how the test suite verifies different decoder implementations against a single set of test cases.
This strategy is implemented by creating a makeStreamingImpl helper that wraps the EntityDecoder class to mimic the standard decodeHTML and decodeXML APIs.
Sources: src/decode.spec.ts:8-85
Functional Test Categories
Decode and Encode Integrity
The project performs extensive round-trip testing to ensure that encoding a string and subsequently decoding it returns the original value. This is applied to:
- Standard XML entities (
&,<, etc.). - The full HTML5 entity set.
- Astral code points and surrogate pairs.
- Legacy (semicolon-optional) entities.
Sources: src/encode.spec.ts:6-45, src/index.spec.ts:25-52
Trie and Radix Tree Validation
Because the library uses a highly optimized Uint16Array trie for lookups, specific tests verify the trie's construction and traversal:
- Compact Runs: Verifies that linear chains of single-child nodes are correctly collapsed to save space.
- Branching Logic: Tests single branches, jump tables, and sparse dictionaries within the trie.
- Deduplication: Ensures recursive or duplicate subtrees are cached and referenced correctly via relative pointers.
Sources: scripts/trie/decode-trie.spec.ts:37-75, scripts/trie/compact-run.spec.ts:13-39, scripts/trie/encode-trie.spec.ts:40-75
Edge Case and Error Handling
The EntityDecoder is tested against specific HTML specification error conditions using a mock EntityErrorProducer:
- Missing semicolons after character references.
- Absence of digits in numeric character references.
- Out-of-range numeric values (e.g., values > U+10FFFF mapping to
U+FFFD).
Sources: src/decode.spec.ts:121-131, src/decode.spec.ts:245-325
Specialized Scan Path Testing
The library uses two paths for scanning escapable characters: an inline scan window (for short gaps) and a regex fallback (for long clean spans). The test suite explicitly checks for "drift" between these two paths.
This ensures that no character is accidentally skipped by the optimized regex skip logic.
Sources: src/encode.spec.ts:106-125, src/escape.spec.ts:42-65
Summary of Testing Significance
The testing strategy guarantees that performance optimizations—such as the binary trie, bitset-based scanning, and streaming decoders—do not compromise the accuracy required for HTML/XML processing. By testing across multiple implementation modes (Sync/Stream) and validating against internal data structure integrity (Trie), the library maintains high reliability for downstream consumers like htmlparser2 and the AWS SDK.
Sources: readme.md:12-18, src/decode.spec.ts:85-90