{"id":14546,"library":"elm-test","title":"Elm Test Runner CLI","description":"elm-test is the official Node.js command-line interface (CLI) for running test suites written with the `elm-explorations/test` Elm package. As of April 2026, the current stable version is `0.19.1-revision17`, with frequent patch-level releases (revisions) to address compatibility issues, bug fixes, and Node.js environment support. It functions by compiling Elm tests and executing them within a Node.js environment. A key differentiator is its tight coupling with specific versions of the `elm-explorations/test` Elm package; users must ensure compatibility between the CLI and the Elm testing library to avoid unexpected behavior, such as missing test distribution diagrams or compilation errors. It provides features like watch mode, selective test execution by file or glob, and various reporting formats.","status":"active","version":"0.19.1-revision17","language":"javascript","source_language":"en","source_url":"https://github.com/rtfeldman/node-test-runner","tags":["javascript","elm","elm-test","cli"],"install":[{"cmd":"npm install elm-test","lang":"bash","label":"npm"},{"cmd":"yarn add elm-test","lang":"bash","label":"yarn"},{"cmd":"pnpm add elm-test","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package is primarily a CLI tool and does not expose JavaScript/TypeScript modules for direct `import` or `require` statements. Interaction is via command-line invocation, typically using `npx` or by defining scripts in `package.json`.","wrong":"elm-test (without npx or if not globally installed)","symbol":"elm-test CLI","correct":"npx elm-test"}],"quickstart":{"code":"import { exec } from 'child_process';\nimport { promisify } from 'util';\n\nconst execPromise = promisify(exec);\n\nasync function runElmTests() {\n  try {\n    console.log(\"1. Installing elm-test as a dev dependency...\");\n    // Using npm install locally ensures `npx elm-test` works reliably.\n    await execPromise('npm install --save-dev elm-test');\n    console.log(\"elm-test installed.\");\n\n    console.log(\"2. Initializing Elm test project (creates tests/Example.elm and configures elm.json)...\");\n    // The --yes flag answers 'y' to prompts, making it non-interactive.\n    const initOutput = await execPromise('npx elm-test init --yes');\n    console.log(initOutput.stdout);\n\n    console.log(\"3. Running all tests in the project...\");\n    const runOutput = await execPromise('npx elm-test');\n    console.log(runOutput.stdout);\n\n    console.log(\"4. Running tests in a specific file (e.g., tests/Example.elm)...\");\n    const specificFileOutput = await execPromise('npx elm-test tests/Example.elm');\n    console.log(specificFileOutput.stdout);\n\n    console.log(\"Quickstart complete. Note: Watch mode (npx elm-test --watch) runs indefinitely.\");\n  } catch (error) {\n    console.error(`Error during elm-test quickstart: ${error.message}`);\n    console.error(`Stderr: ${error.stderr}`);\n  }\n}\n\nrunElmTests();","lang":"javascript","description":"This quickstart demonstrates how to programmatically install, initialize, and run `elm-test` from a Node.js script, covering basic test execution patterns."},"warnings":[{"fix":"Ensure your `elm.json` specifies `\"elm-explorations/test\": \"2.x.x\"` in your `test-dependencies` and run `elm install`.","message":"Starting with `elm-test@0.19.1-revision10`, this CLI tool strictly requires `elm-explorations/test` version `2.0.0` or newer (specifically `2.x.x`). Older versions of `elm-explorations/test` are incompatible.","severity":"breaking","affected_versions":">=0.19.1-revision10"},{"fix":"Upgrade your Node.js environment to version 12.20.0 or higher. For current stability and features, Node.js 18+ is recommended.","message":"Node.js 10 support was dropped in `elm-test@0.19.1-revision8`. The minimum required Node.js version is `12.20.0`.","severity":"breaking","affected_versions":">=0.19.1-revision8"},{"fix":"Always upgrade both `elm-test` CLI and `elm-explorations/test` package together to compatible versions. Refer to the official `elm-test` GitHub README for the version compatibility table.","message":"When using `elm-test` versions `0.19.1-revision9` or older, running `elm-test init` could install `elm-explorations/test@2.0.0` or later, which has known incompatibilities (e.g., missing distribution diagrams) despite partial functionality.","severity":"gotcha","affected_versions":"<=0.19.1-revision9"},{"fix":"Always install `elm-test` with the `revision` suffix, e.g., `npm install elm-test@latest` or `npm install elm-test@0.19.1-revision17` to ensure you get the most up-to-date and stable version.","message":"Due to a naming quirk, there is an `npm` package named `0.19.1` which is not the latest version. The latest stable versions are always named `0.19.1-revisionX`.","severity":"gotcha","affected_versions":"All"},{"fix":"Use `npx elm-test \"src/**/*Tests.elm\"` instead of `npx elm-test src/**/*Tests.elm`.","message":"When specifying test files using globs (e.g., `src/**/*Tests.elm`), always wrap the glob pattern in double quotes. Without quotes, your shell might expand the glob prematurely, preventing `elm-test` from correctly handling file patterns, especially in watch mode or across different operating systems.","severity":"gotcha","affected_versions":"All"},{"fix":"For Node.js 12 environments, ensure you are using `elm-test@0.19.1-revision12` or `elm-test@0.19.1-revision15` or newer. For other versions, ensure your `npm` client is up-to-date (v10+ is recommended).","message":"Older `elm-test` revisions had intermittent Node.js compatibility issues, notably `0.19.1-revision13` and `0.19.1-revision14` which broke Node.js 12 (and `npm` v10 for `14-18`). While `0.19.1-revision15` and later restored Node.js 12 support, always check release notes if encountering Node.js environment errors.","severity":"gotcha","affected_versions":"0.19.1-revision13, 0.19.1-revision14"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Upgrade `elm-test` to `0.19.1-revision11` or newer. This version bundles a fix for `RuntimeError: unreachable` and `0.19.1-revision16` fixed Lamdera compiler compatibility.","cause":"An older version of `elm-solve-deps-wasm` was causing runtime errors or `elm-test init` failures, or incompatibility with the Lamdera compiler.","error":"Error: Command failed: npx elm-test init --yes (or similar process crash output) / RuntimeError: unreachable"},{"fix":"Upgrade `elm-test` to `0.19.1-revision12` or newer. This version escapes disallowed XML characters to prevent crashes.","cause":"Test outputs from `elm-program-test` (or other Elm test libraries) contained characters disallowed in XML, causing the JUnit reporter to crash.","error":"XML parsing error or crash when generating JUnit report (e.g., `elm-test --report junit`)"},{"fix":"Upgrade `elm-test` to `0.19.1-revision13` or newer.","cause":"A bug in `elm-test` versions prior to `0.19.1-revision13` would incorrectly report duplicate source directories if `tests` was explicitly listed in `elm.json`'s `source-directories`.","error":"Error: Duplicate source directories (when `elm.json` contains `\"source-directories\": [\"tests\"]`)"}],"ecosystem":"npm"}