Sizzle Test Suite Integration

Relevant source files

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

• test/sizzle.spec.ts
• test/tools/sizzle-testinit.ts
• test/fixtures/sizzle.html
• src/index.ts
• test/fixtures/fries.xml
• README.md

The Sizzle Test Suite Integration in cheerio-select serves as a comprehensive validation framework to ensure compatibility with jQuery-style selectors. Since cheerio-select is a wrapper around css-select specifically designed to support jQuery positional pseudo-selectors, the project incorporates a ported version of the original Sizzle engine's test suite to verify correctness across complex selector edge cases.

Sources: README.md:1-15, test/sizzle.spec.ts:31-35

Test Infrastructure and Initialization

The integration relies on a specialized initialization layer that simulates a browser-like DOM environment using htmlparser2 and domhandler. This infrastructure allows the test suite to run against static HTML and XML fixtures while providing standard DOM methods such as getElementById.

Core Initialization Components

The initialization process is managed through test/tools/sizzle-testinit.ts. It provides the following key utilities:

• loadDocument(): Loads the primary sizzle.html fixture and augments the resulting array with DOM-like utility methods.
• t(selector, expectedIds, context): A specialized assertion helper that executes a select call and compares the resulting element IDs against an expected array.
• q(...ids): A shorthand helper to retrieve specific elements from the document by their ID.

Sources: test/tools/sizzle-testinit.ts:25-83

DOM Simulation Data Flow

The following diagram illustrates how the test suite initializes the document environment before running assertions.

Supported Selector Categories

The Sizzle integration tests a wide variety of selector types to ensure cheerio-select correctly handles both standard CSS and extended jQuery syntax.

Category	Description	Example from Suite
Basic Selectors	IDs, Classes, and Tags.	#body, .blog, div
Hierarchy	Child, descendant, and sibling combinators.	p > a, dl ol, p + p, p ~ div
Attributes	Equality, existence, and substring matching.	a[rel='bookmark'], [lang=中文]
Pseudo-classes	Positional and structural pseudos.	:first, :last, :nth-child(even)
XML Selectors	Case-sensitive and namespaced selectors.	soap\:Envelope, foo_bar

Sources: test/sizzle.spec.ts:40-800, test/fixtures/fries.xml:1

Positional Pseudo-Selectors

A critical part of the integration is verifying jQuery-specific positionals. Unlike standard CSS nth-child, these refer to the index within the currently matched set.

XML and Namespace Handling

The integration includes specific tests for XML documents, ensuring that the engine respects xmlMode and handles namespaced elements correctly. The fries.xml fixture is used to test these capabilities.

• Namespaced Elements: The suite verifies selectors like soap\:Envelope using the xmlMode: true option.
• Case Sensitivity: Unlike HTML, XML selectors are tested for strict case sensitivity as defined in the source fixtures.
• Underscore IDs: The engine is verified to support IDs containing underscores, which are common in XML schemas (e.g., foo_bar).

Sources: test/sizzle.spec.ts:133-162, test/fixtures/fries.xml:1

Error Handling and "Broken" Selectors

The suite contains a broken helper function designed to ensure the engine throws appropriate errors when encountering invalid selector syntax. This prevents the engine from hanging or producing unpredictable results on malformed input.

const broken = (selector: string) =>
    expect(() => select(selector, [])).toThrow(Error);

// Examples of tested broken selectors
broken("[");
broken("a,");
broken(":nth-child(asdf)");

Sources: test/sizzle.spec.ts:25-26%3B%0Abroken(%22a%2C%22)%3B%0Abroken(%22%3Anth-child(asdf)%22)%3B%0A%60%60%60%0A%0ASources%3A%20%5Btest/sizzle.spec.ts%3A25-26), test/sizzle.spec.ts:164-190

Conclusion

The Sizzle Test Suite Integration provides the technical foundation for cheerio-select's claim of jQuery compatibility. By utilizing a robust initialization layer and porting hundreds of test cases from the original Sizzle project, the integration ensures that complex selectors, including positional pseudos and XML namespaces, behave identically to the jQuery selector engine.