banira
    Preparing search index...

    Class TestHelper

    Helper class for testing web components in a JSDOM environment

    This class provides utilities for compiling TypeScript web components and mounting them in a JSDOM environment for testing. It supports both direct script mounting and compile-then-mount workflows.

    Mounting runs the component's code (jsdom is configured with runScripts: "dangerously" — required for custom elements to register and upgrade). Only mount code you trust, i.e. your own components under test; never feed untrusted third-party source through the helper.

    // Mount a pre-compiled component
    const helper = new TestHelper();
    const context = await helper.mountAsScript('my-component', compiledCode);
    const element = context.document.querySelector('my-component');

    // Compile and mount a TypeScript component
    const context = await helper.compileAndMountAsScript(
      'my-component',
      'src/my-component.ts',
      { target: 'ES2015' }
    );
    Index

    Constructors

    constructor

    Properties

    blockNetwork confineToRoot? readyTimeout

    Methods

    compileAndMountAsScript mountAsScript mountInBrowser

    Constructors

    • Creates a new TestHelper instance

      Parameters

      • Optionaloptions: ConstructorOptions

        Optional JSDOM constructor options to override defaults

      Returns TestHelper

    Properties

    blockNetwork: boolean = false

    When true, the script-reachable network APIs (XMLHttpRequest, WebSocket, fetch, EventSource) are removed from the JSDOM window before the component script runs, so mounting potentially untrusted code cannot make outbound requests (SSRF / exfiltration). Off by default; callers that mount untrusted components (e.g. the MCP --local-only server) opt in.

    confineToRoot?: string

    When set, compileAndMountAsScript confines the bundled module graph to this directory — a component's local imports cannot pull source from outside it into the mounted bundle. Used by the MCP --local-only path. See security-findings #22.

    readyTimeout: number = 1000

    Upper bound (ms) for waiting on a custom element to be defined before giving up, so a component that never registers fails fast instead of hanging. Resolution happens as soon as the element is defined.

    Methods

    • Compiles a TypeScript component and mounts it in a JSDOM environment

      Parameters

      • tagName: string

        The custom element tag name

      • fileName: string

        Path to the TypeScript source file

      • compilerOptions: CompilerOptions = Compiler.DEFAULT_COMPILER_OPTIONS

        TypeScript compiler options

      • Optionalattributes: Record<string, string>

        Optional key-value pairs of attributes to set on the mounted component

      Returns Promise<MountContext>

      Promise resolving to a MountContext

      Compiles the file and its local import graph into a single self-contained classic script (see bundleModule) and mounts it, so components that import sibling modules work — not just single-file ones.

    • Mounts a pre-compiled component in a JSDOM environment

      Parameters

      • tagName: string

        The custom element tag name

      • code: string

        The compiled JavaScript code for the component

      • Optionalattributes: Record<string, string>

        Optional key-value pairs of attributes to set on the mounted component

      Returns Promise<MountContext>

      Promise resolving to a MountContext

      This method creates a new JSDOM instance with a basic HTML structure, adds the component's tag to the body, and injects the component's code as a script. It waits for a short period to allow for component initialization.

    • Mounts a compiled component in a real browser via Playwright, for higher-fidelity testing than JSDOM (layout, real CSS, true custom-element semantics). Playwright is an optional peer dependency — install it with npm i -D playwright and npx playwright install chromium.

      Parameters

      • tagName: string

        The custom element tag name

      • code: string

        The compiled JavaScript (injected as a module script, so components with imports/exports work)

      Returns Promise<BrowserMountContext>

      A BrowserMountContext; call close() when done

      Error if Playwright is not installed

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Methods