Testing Strategy
Relevant source files
The following files were used as context for generating this wiki page:
The testing strategy for nth-check is designed to ensure the accuracy and performance of CSS nth-child formula parsing and compilation. The project utilizes a combination of unit tests, functional verification against a "slow" reference implementation, and automated linting/formatting checks. The primary goal is to validate that the optimized functions produced by the compiler strictly adhere to the CSS Selectors Level 3 specification while maintaining high execution speed.
The test suite is built on vitest and covers three main areas: the parsing logic that transforms string formulas into numeric tuples, the compilation logic that generates matcher functions, and the sequence generation logic.
Test Infrastructure and Tooling
The project employs a modern TypeScript-based testing stack. Execution is handled via NPM scripts that orchestrate testing, linting, and type checking.
Key Tools and Scripts
| Component | Tool / Command | Description |
|---|---|---|
| Test Runner | vitest | Executes unit tests defined in .spec.ts files. |
| Linter/Formatter | biome | Performs static analysis and code formatting. |
| Static Analysis | eslint | Additional linting for code quality. |
| Type Checking | tsc --noEmit | Ensures type safety across the codebase and tests. |
Sources: package.json:34-40, biome.json:1-73
Test Execution Flow
The following diagram illustrates the standard testing workflow triggered by npm test.
This multi-stage process ensures that code not only functions correctly but also adheres to defined style and type constraints before completion.
Sources: package.json:34-40
Unit Testing Framework
Unit tests are divided into specialized files targeting parse, compile, and generate functionalities.
Parser Validation
Tests in src/parse.spec.ts verify that the parse function correctly handles both valid CSS formulas and malformed inputs.
- Valid Cases: Iterates through a fixture of known valid formulas (e.g., "2n+1", "even", "odd") and compares the output to expected
[a, b]tuples. - Invalid Cases: Ensures that strings like "asdf" or "2+0" trigger an
Error.
Sources: src/parse.spec.ts:5-18, src/fixtures/rules.ts:1-42
Compiler Differential Testing
The src/compile.spec.ts file uses a differential testing approach. It compares the output of the "highly optimized" functions generated by compile against a "slow" reference implementation (slowNth).
function slowNth([a, b]: [number, number]): number[] {
if (a === 0 && b > 0) return [b - 1];
return valueArray.filter((value) => {
for (
let index = b;
a > 0 ? index <= valueArray.length : index >= 1;
index += a
) {
if (value === valueArray[index - 1]) return true;
}
return false;
});
}
Sources: src/compile.spec.ts:14-29
The test suite iterates through a valueArray of 2,000 indices to ensure the optimized matcher produces identical results to the iterative loop for all valid rules.
Sources: src/compile.spec.ts:5-12, src/compile.spec.ts:31-48
Data-Driven Testing with Fixtures
The project centralizes test cases in a fixture file to ensure consistency across different test modules.
Rule Fixtures
The src/__fixtures__/rules.ts file contains arrays of test data:
valid: A list of tuples containing the raw CSS string and its expected parsed[a, b]representation. It includes edge cases like negative step sizes (-n+2) and specific CSS keywords (even,odd).invalid: A list of strings that should fail parsing, used to verify the robustness of the parser's error handling.
Sources: src/fixtures/rules.ts:1-42
Sequence Generation Testing
The generate and sequence functions are tested to ensure they produce correct, monotonically increasing indices, especially for formulas with end values (negative a values).
Tests confirm that for negative step sizes, the generator correctly terminates by returning null once the index exceeds the offset b. For positive step sizes, it verifies that the values produced are consistent with the results of the compile function for the same indices.
Sources: src/compile.spec.ts:60-100
Summary
The nth-check testing strategy prioritizes correctness through rigorous comparison between optimized production code and a simplified reference model. By leveraging comprehensive fixtures and automated linting tools like Biome and ESLint, the project maintains a high standard of reliability for CSS selector parsing and index matching. The combination of static type checking and dynamic unit tests ensures that performance optimizations do not compromise spec compliance.