test-runner

Common errors

• ReferenceError: require is not defined

  cause Attempting to use `require` in an ECMAScript Module (ESM) file (e.g., when `"type": "module"` is set in `package.json`).
  fix Switch to `import { Tom } from 'test-runner'` or change your file to be a CommonJS module by removing `"type": "module"` from `package.json` or changing the file extension to `.cjs`.

• SyntaxError: Named export 'Tom' not found. The requested module 'test-runner' does not provide an export named 'Tom'

  cause Attempting to use an ESM `import` statement in a CommonJS context without proper transpilation, or incorrect export mapping in `package.json`.
  fix If in a CommonJS context, use `const { Tom } = require('test-runner')`. If in ESM, ensure your `package.json` correctly defines module type and exports, and that the `test-runner` package correctly provides ESM exports.

• TypeError: tom.test is not a function

  cause The `Tom` object was not correctly instantiated, or the `test` method does not exist on the object being used. This usually happens if `Tom` was not imported/required properly or if `module.exports = tom` is missing from the test file.
  fix Ensure you have `const { Tom } = require('test-runner')` (or `import { Tom } from 'test-runner')` and `const tom = new Tom()` in your test file, and that the test file exports the `tom` instance: `module.exports = tom`.

• Error: No test files found matching pattern: <your_pattern>

  cause The command-line arguments for `test-runner` do not correctly specify the path(s) to your test files, or the files do not exist at the specified location.
  fix Verify the file paths and patterns provided to `test-runner`. Use glob patterns cautiously and ensure they match your file structure. E.g., `npx test-runner 'test/**/*.js'`.

Warnings

• breaking The project is explicitly marked as 'Work In Progress' (WIP) and is currently at version 0.11.1. This indicates that the API is not yet stable and breaking changes may occur frequently without strict adherence to semantic versioning until a 1.0 release.
  Fix: Monitor the project's GitHub repository and release notes closely for updates. Consider pinning to exact versions for critical projects and thorough testing after updates.
• gotcha test-runner requires Node.js version 12.17 or higher. Running on older Node.js environments will result in runtime errors or unexpected behavior due to unsupported syntax or APIs.
  Fix: Ensure your Node.js environment meets the minimum requirement by upgrading to version 12.17 or newer (e.g., using nvm or your package manager).
• gotcha The test definition relies on an instance of the `Tom` class from 'test-object-model' (re-exported by 'test-runner'). Users must familiarize themselves with the `Tom` API (e.g., `tom.test`, `tom.skip`) as it's the primary interface for defining tests, differing from other runners that might use global functions or specific syntaxes.
  Fix: Refer to the 'test-object-model' documentation and the 'test-runner' README for examples on how to correctly structure test files using the `Tom` instance.
• gotcha test-runner supports both CommonJS (CJS) and ECMAScript Modules (ESM). Incorrectly mixing module systems (e.g., using `require` in an ESM file with `"type": "module"` or `import` in a pure CJS file without transpilation) can lead to module resolution errors.
  Fix: Ensure consistency in your module system. For ESM, use `import` statements and ensure your `package.json` has `"type": "module"`. For CJS, use `require` statements. Refer to Node.js documentation on module systems.
• gotcha While test-runner supports isomorphic testing across Node.js and headless Chromium, environment-specific APIs (e.g., `node-fetch` in Node.js vs. native `fetch` in browser) or DOM manipulation will require careful abstraction or separate test files/configurations to run successfully in both environments.
  Fix: Use universal APIs or conditional logic (e.g., checking `typeof window`) within your tests, or create distinct test files and run configurations for browser-only and Node.js-only code.

Install

• npm install test-runner npm
• yarn add test-runner yarn
• pnpm add test-runner pnpm

Imports

• Tom
  wrong:

  import Tom from 'test-runner'

  correct:

  import { Tom } from 'test-runner'

  For ECMAScript Modules (ESM) environments. 'Tom' is a named export. Attempting a default import will fail. 'Tom' is re-exported from the 'test-object-model' package.
• Tom
  wrong:

  const Tom = require('test-runner')

  correct:

  const { Tom } = require('test-runner')

  For CommonJS (CJS) environments. 'Tom' is a named export. Attempting to require the entire module and access it as a default export will result in an undefined 'Tom'. 'Tom' is re-exported from the 'test-object-model' package.
• Tom
  wrong:

  import { Tom } from 'test-runner'; // Used only for type annotation, potentially causes runtime overhead or bundling issues if not handled by a type-stripping transpiler.

  correct:

  import type { Tom } from 'test-runner'

  For TypeScript projects, this imports the type definition for the Tom class. Assumes type definitions are shipped with the package or via @types. (Unconfirmed in v0.11.1)

Quickstart

This quickstart demonstrates how to set up and run basic synchronous and asynchronous tests using `test-runner` in a Node.js CommonJS environment, including an external dependency (`node-fetch`) for API testing.

npm install --save-dev test-runner node-fetch

// test.js
const { Tom } = require('test-runner')
const assert = require('assert').strict
const fetch = require('node-fetch')

const tom = new Tom()

tom.test('Math.random() should return a number between 0 and 1', function () {
  const result = Math.random()
  assert.equal(typeof result, 'number')
  assert.ok(result >= 0 && result <= 1)
})

tom.test('REST API should return the current todo item', async function () {
  const response = await fetch('https://jsonplaceholder.typicode.com/todos/1')
  const todo = await response.json()
  assert.equal(todo.userId, 1)
  assert.equal(todo.title, 'delectus aut autem')
})

module.exports = tom;

// Run from your terminal
// $ npx test-runner test.js