{"id":17713,"library":"imhotap","title":"Imhotap Test Runner","description":"Imhotap is a lightweight, 'meta-test-framework' designed to run test files as independent processes and aggregate their results. It operates on the principle that each test file should be executable and indicate success or failure via its exit code. The tool automatically detects and parses Test Anything Protocol (TAP) output from test files, but is agnostic to the specific underlying test framework used, supporting any TAP producer like `tape`, `node-tap`, or `pitesti`. Key differentiators include its parallel execution model (defaulting to CPU cores - 1 concurrency), support for custom runners (e.g., `ts-node` for TypeScript files), and flexible glob-based file selection. The current stable version is 2.2.0, with a focus on stability and compatibility rather than frequent breaking changes.","status":"active","version":"2.2.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/bengl/imhotap","tags":["javascript","test","runner","meta","tap"],"install":[{"cmd":"npm install imhotap","lang":"bash","label":"npm"},{"cmd":"yarn add imhotap","lang":"bash","label":"yarn"},{"cmd":"pnpm add imhotap","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While primarily a CLI tool, Imhotap offers a programmatic interface for its CLI function, `cli`, allowing integration into custom scripts. Prefer ESM imports.","wrong":"const cli = require('imhotap').cli;","symbol":"cli","correct":"import { cli } from 'imhotap'; // Programmatic CLI execution"},{"note":"The `TapRunner` class provides a more granular programmatic way to define and execute test runs without invoking the full CLI process. Use ESM imports.","wrong":"const TapRunner = require('imhotap').TapRunner;","symbol":"TapRunner","correct":"import { TapRunner } from 'imhotap'; // Programmatic runner class"},{"note":"Imhotap is intended to be run directly as a command-line tool after global installation or via `npx` / `package.json` scripts, not typically invoked via `node` directly.","wrong":"node imhotap --files 'test/**/*.js'","symbol":"Running Imhotap via CLI","correct":"imhotap --files 'test/**/*.js'"}],"quickstart":{"code":"mkdir -p my-project/test\necho 'console.log(\"TAP version 13\")' > my-project/test/basic.js\necho 'console.log(\"ok 1 - basic test\")' >> my-project/test/basic.js\n\necho 'console.log(\"TAP version 13\")' > my-project/test/failing.js\necho 'console.log(\"not ok 1 - failing test\")' >> my-project/test/failing.js\necho 'process.exit(1)' >> my-project/test/failing.js\n\ncd my-project\nnpx imhotap --files 'test/**/*.js'","lang":"javascript","description":"This quickstart demonstrates how to set up two basic TAP-producing test files (one passing, one failing) and run them with `imhotap` using a glob pattern."},"warnings":[{"fix":"Ensure test files are fully isolated and do not conflict when run simultaneously. If isolation is not feasible, use the `-c 1` option to run tests serially.","message":"Imhotap runs test files in parallel as separate processes. If your tests are not isolated and share resources (e.g., databases, global state, specific ports), you may encounter race conditions or unexpected failures. Adjust concurrency (`-c`) to 1 if tests require serial execution.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Install the runner globally (`npm i -g <runner>`) or locally as a `devDependency` (`npm i -D <runner>`). For local installs, `npx` or a `package.json` script wrapping `imhotap` is recommended.","message":"When using a custom runner (`-R/--runner`), ensure the runner is installed and accessible in the system's PATH, or within the project's `node_modules/.bin`. If not found, `imhotap` will attempt to use `npx`, but this might fail or be slower.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For non-JavaScript files, use `-R <runner_command>` (e.g., `-R tsnode`, `-R bash`). For executable scripts, ensure they have a shebang (`#!/usr/bin/env bash`) and execute permissions.","message":"Imhotap expects JavaScript files (`.js`) to be executable by Node.js by default. For other file types (e.g., `.ts`, `.sh`, Python scripts), you must explicitly provide a `--runner` option, or ensure the files are marked as executable (e.g., `chmod +x file.sh`) and have a shebang.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure your test framework outputs valid TAP to `stdout`. If your framework outputs to `stderr` and you prefer that, use `--stream stderr`. Consult `testanything.org` for TAP specification.","message":"Imhotap expects TAP output from test files. If a test file's `stdout` or `stderr` does not contain valid TAP data, `imhotap` will display both streams inside a YAML block, which may be less parseable by TAP reporters. It prioritizes `stdout` over `stderr` for TAP detection by default.","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":"Ensure the reporter package is installed globally or as a devDependency. If locally installed, ensure `npx` can find it or add it to your PATH.","cause":"The specified TAP reporter (via `-r`) was not found in the system's PATH or `node_modules/.bin`.","error":"Error: Command failed: <reporter_command>"},{"fix":"For shell scripts or other executable formats, run `chmod +x <file>` on the test file. Alternatively, specify a runner using `-R` (e.g., `-R bash` for a shell script).","cause":"A test file was attempted to be executed directly, but it lacks execute permissions.","error":"Error: Command failed: chmod EACCES"},{"fix":"Double-check the glob pattern for typos or incorrect paths. Ensure files actually exist at the specified location relative to where `imhotap` is run.","cause":"The provided glob pattern did not match any files in the project directory.","error":"No files found matching glob pattern: 'test/**/*.spec.js'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}