Test262 Test Suite Stream API

Common errors

• Error: provided Test262 directory does not contain 'test' subdirectory

  cause The `test262Dir` provided to the `TestStream` constructor is not the root of a valid Test262 repository clone, or the 'test' subdirectory is missing/misplaced.
  fix Ensure `test262Dir` points to the exact root of your Test262 repository clone, which typically contains 'test/', 'harness/', and other standard Test262 directories. Double-check the path for typos.

• Error: Unsupported Test262 version

  cause The Test262 repository you are streaming has a version that is not officially supported by this `test262-stream` library version.
  fix Update your `test262-stream` package to the latest version, or, as a temporary workaround (with caution), provide the `acceptVersion` option with the version string of your Test262 clone. However, updating the library is the recommended approach for compatibility.

Warnings

• gotcha Using the `acceptVersion` option with an outdated or incorrect version can lead to the stream emitting invalid tests that may not accurately reflect the Test262 specification. It's generally safer to update the library to ensure compatibility.
  Fix: Omit `acceptVersion` to rely on the library's default supported version, or ensure the provided version matches the actual Test262 repository version you are using. Consider updating the `test262-stream` library itself.
• gotcha The `test262Dir` path must point to the root directory of a cloned Test262 repository. An incorrect path will result in errors as the library won't be able to locate tests or harness files.
  Fix: Verify that the `test262Dir` argument points to the correct absolute or relative path of your Test262 repository clone.
• gotcha Setting `omitRuntime: true` will prevent the insertion of necessary execution code (like assertion functions and 'include' files) into `test.contents`. This is useful for static analysis but will make the `contents` property unsuitable for direct execution.
  Fix: Set `omitRuntime: false` if you intend to execute `test.contents` directly. Understand the implications based on your use case for the test content.
• deprecated The usage example shows `var TestStream = require('test262-stream');`. While functional in CommonJS environments, modern Node.js development strongly recommends ESM `import` syntax.
  Fix: Use `import TestStream from 'test262-stream';` in ESM modules, or ensure your project is configured for CommonJS if sticking with `require`.

Install

• npm install test262-stream npm
• yarn add test262-stream yarn
• pnpm add test262-stream pnpm

Imports

• TestStream
  wrong:

  const TestStream = require('test262-stream');

  correct:

  import TestStream from 'test262-stream';

  The documentation uses CommonJS `require`, but ESM `import` is the modern standard. Both are likely supported if running in an environment that handles CJS interoperability.
• Test262Stream

  import TestStream from 'test262-stream';

  The primary export is a class named `TestStream`. There is no named export for `Test262Stream`.
• stream events
  wrong:

  for await (const test of stream) { ... }

  correct:

  stream.on('data', function(test) { ... });
  stream.on('end', function() { ... });
  stream.on('error', function(err) { ... });

  The library uses Node.js `EventEmitter` pattern for streams. While async iterators might work for readable streams, the library's primary documented usage is event-based.

Quickstart

This quickstart initializes a `TestStream` to process a subset of the Test262 test suite, logging details of each test found.

import TestStream from 'test262-stream';
import path from 'path';

// Replace with your actual path to the Test262 repository
const test262Dir = process.env.TEST262_DIR || '/path/to/test262';

const stream = new TestStream(test262Dir, {
    includesDir: path.join(test262Dir, 'harness'),
    paths: ['test/built-ins/eval', 'test/language/statements/empty/S12.3_A1.js'],
    omitRuntime: true,
    acceptVersion: '2.0.0'
});

stream.on('data', function(test) {
    console.log(`File: ${test.file}`);
    console.log(`Scenario: ${test.scenario}`);
    // console.log(`Contents:\n${test.contents}`); // Uncomment for full contents
    // console.log(`Attributes: ${JSON.stringify(test.attrs, null, 2)}`);
    // console.log(`Copyright: ${test.copyright}`);
    // console.log(`Insertion Index: ${test.insertionIndex}`);
});

stream.on('end', function() {
    console.log('No further tests.');
});

stream.on('error', function(err) {
    console.error('Something went wrong:', err.message);
    process.exit(1);
});