{"id":17783,"library":"llparse-test-fixture","title":"llparse Test Fixture","description":"llparse-test-fixture is a utility package designed to provide a consistent and controlled environment for testing parsers generated by `llparse` and other `llparse`-based modules. `llparse` itself is an API for compiling incremental parsers into highly optimized C output, often used in performance-critical applications like `llhttp` (the HTTP parser in Node.js). This fixture, currently at version 5.1.0, facilitates the creation of test cases, feeding input data, and asserting on the behavior and output of such low-level parsers. It primarily serves as a development dependency for projects that utilize `llparse` to ensure the correctness and robustness of their generated parsers, offering abstractions to simplify complex parsing scenarios in tests. Its release cadence is likely tied to updates in the core `llparse` project. It differentiates itself by providing specialized tools for a generated C-based parser, contrasting with general-purpose testing libraries.","status":"active","version":"5.1.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/indutny/llparse-test-fixture","tags":["javascript","llparse","test","fixture","typescript"],"install":[{"cmd":"npm install llparse-test-fixture","lang":"bash","label":"npm"},{"cmd":"yarn add llparse-test-fixture","lang":"bash","label":"yarn"},{"cmd":"pnpm add llparse-test-fixture","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides the core parser generation API for which this package creates test fixtures. While not a direct runtime dependency of the fixture itself, it's a conceptual peer dependency for any project using this fixture to test `llparse`-generated code.","package":"llparse","optional":false}],"imports":[{"note":"The library primarily targets ESM environments for testing modern Node.js and browser projects. While CJS might work via transpilation, direct `require` is discouraged since v3 due to its TypeScript-first design.","wrong":"const createFixture = require('llparse-test-fixture').createFixture;","symbol":"createFixture","correct":"import { createFixture } from 'llparse-test-fixture';"},{"note":"This is a named export; there is no default export. Direct subpath imports are generally not supported or recommended for stability.","wrong":"import ParserTestStream from 'llparse-test-fixture/stream';","symbol":"ParserTestStream","correct":"import { ParserTestStream } from 'llparse-test-fixture';"},{"note":"IParsedEvent is a TypeScript type definition, intended for type-only imports to avoid bundling unnecessary runtime code. Using a regular import might lead to compilation errors in some TypeScript configurations.","wrong":"import { IParsedEvent } from 'llparse-test-fixture';","symbol":"IParsedEvent","correct":"import type { IParsedEvent } from 'llparse-test-fixture';"}],"quickstart":{"code":"import { createFixture, ParserTestStream, IParsedEvent } from 'llparse-test-fixture';\n// Assume 'my-llparse-parser' is a module that exports a class\n// generated by llparse, with a parse() method and event callbacks.\n// For demonstration, we'll mock a simple parser structure.\n\ninterface MyParserCallbackEvents {\n  on_data?: (value: number) => void;\n  on_complete?: () => void;\n}\n\nclass MockLLParseParser {\n  private callbacks: MyParserCallbackEvents = {};\n  constructor(callbacks: MyParserCallbackEvents) {\n    this.callbacks = callbacks;\n  }\n\n  // Simulate parsing, calling callbacks based on input\n  parse(data: Buffer): number {\n    for (const byte of data) {\n      if (byte === 0x01 && this.callbacks.on_data) {\n        this.callbacks.on_data(byte);\n      } else if (byte === 0x02 && this.callbacks.on_complete) {\n        this.callbacks.on_complete();\n      }\n    }\n    return data.length;\n  }\n\n  // Simulate reinitialization\n  reset(): void {\n    console.log('Parser reset.');\n  }\n}\n\ndescribe('My LLParse Parser', () => {\n  it('should parse simple data and trigger complete event', async () => {\n    const events: IParsedEvent[] = [];\n    const fixture = createFixture(MockLLParseParser, {\n      on_data: (value) => events.push({ type: 'data', value }),\n      on_complete: () => events.push({ type: 'complete' })\n    });\n\n    const parser = fixture.parser; // Access the mocked parser instance\n    const stream = new ParserTestStream(parser);\n\n    stream.feed(Buffer.from([0x01, 0x01]));\n    stream.feed(Buffer.from([0x02]));\n    stream.end();\n\n    // Wait for all async parsing to settle if applicable (mocked here as sync)\n    await new Promise(resolve => setImmediate(resolve));\n\n    expect(events).toEqual([\n      { type: 'data', value: 1 },\n      { type: 'data', value: 1 },\n      { type: 'complete' }\n    ]);\n    expect(fixture.getCalls('on_complete').length).toBe(1);\n  });\n\n  it('should handle parser reset correctly', async () => {\n    const events: IParsedEvent[] = [];\n    const fixture = createFixture(MockLLParseParser, {\n      on_data: (value) => events.push({ type: 'data', value })\n    });\n\n    const parser = fixture.parser;\n    parser.parse(Buffer.from([0x01]));\n    fixture.reset(); // Calls the parser's reset method\n\n    parser.parse(Buffer.from([0x01]));\n    expect(events.length).toBe(2); // Events before and after reset\n  });\n});","lang":"typescript","description":"Demonstrates how to use `llparse-test-fixture` to test a hypothetical `llparse`-generated parser, feeding it data, capturing events, and asserting expected outcomes."},"warnings":[{"fix":"Always check the release notes for `llparse-test-fixture` when upgrading `llparse` to ensure compatibility. Re-evaluate parser mock implementations and event expectations.","message":"Major versions of `llparse-test-fixture` are typically tied to `llparse` itself. Upgrading `llparse` may require upgrading the fixture, as internal APIs or expected parser behavior might change, leading to test failures or incorrect mock interactions.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Verify that `node-gyp` (or equivalent build tool) is correctly installed and configured. Check system environment variables like `CC`, `CXX`, and `PATH` for proper compiler access. For CI/CD, use Docker images with pre-installed toolchains.","message":"When testing `llparse`-generated C code (e.g., via `napi-rs` or direct C++ bindings), ensure your testing environment has the necessary C/C++ toolchain configured. Mismatched compiler versions or missing build tools can lead to compilation errors during test setup.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure that your test suite (e.g., Jest, Mocha) is configured to handle asynchronous tests. Use `async/await` with `Promise` or `setTimeout(..., 0)` to defer assertions until all expected parser events have been processed. The `ParserTestStream` helps, but custom callbacks might need explicit waiting.","message":"Asynchronous event handling in `llparse` parsers (e.g., `on_data` callbacks) can lead to race conditions or incomplete test assertions if not properly awaited. Tests might pass spuriously if assertions run before all parser events have fired.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Run `npm install llparse-test-fixture` or `yarn add llparse-test-fixture`. For CJS projects, ensure proper transpilation or switch to ESM if possible, as the library is primarily designed for ESM.","cause":"The package is not installed or the import path is incorrect, or it's a CommonJS project trying to import an ESM-only library.","error":"Error: Cannot find module 'llparse-test-fixture'"},{"fix":"Double-check the `createFixture` call to ensure all expected `llparse` callbacks are provided. Consult the documentation for your `llparse`-generated parser to confirm the exact callback API.","cause":"The mocked parser or the fixture was not correctly initialized with the expected callback handlers, or the `llparse` parser logic changed its expected callback names.","error":"TypeError: Cannot read properties of undefined (reading 'on_data')"},{"fix":"Explicitly import and use the necessary types, e.g., `import type { IParsedEvent } from 'llparse-test-fixture';` for type-only imports, or add explicit type annotations to variables where the complex type is inferred.","cause":"This TypeScript error indicates that a type inference resulted in a complex type that TypeScript cannot easily name or reference across module boundaries without an explicit import, often seen when `isolatedModules` is enabled.","error":"TS2742: The inferred type of '...' cannot be named without a reference to '.../node_modules/llparse-test-fixture/index.d.ts'. This is likely not portable. A type annotation is necessary."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}