Machinepack Test Runner

3.0.1 verified Thu Apr 23 auth: no javascript maintenance

test-machinepack provides a raw command-line test runner specifically designed for `node-machine` 'machinepacks'. Its current stable version is 3.0.1, though the last known development activity dates back to 2017, suggesting it is in maintenance mode rather than active development. While it includes a basic, generic test driver, the documentation explicitly recommends against using it for production testing, instead pointing to more robust, community-maintained drivers like `test-machinepack-mocha`. The primary function of this package is to expose a consistent interface for running tests defined in JSON or JSON5 format within a machinepack's `tests` directory, thereby enabling custom test drivers to integrate seamlessly with the `node-machine` ecosystem.

Common errors

error command not found: testmachinepack ↓

cause The `testmachinepack` command-line utility was not installed globally or is not in your system's PATH.

fix

Install the package globally using npm install -g test-machinepack.

error Error: Failed to parse test file: [filepath].json5 (SyntaxError: Unexpected token ...) ↓

cause The JSON or JSON5 test file contains syntax errors, making it unparseable by the runner.

fix

Carefully review the specified test file for malformed JSON or JSON5 syntax. Tools like jsonlint or online JSON validators can help identify issues.

error Error: Could not find 'machine' with identity 'some-machine' in the current machinepack. ↓

cause The `machine` property in your test file refers to a machine identity that does not exist or is not exposed by your machinepack.

fix

Ensure the machine property in your JSON/JSON5 test file exactly matches the identity of an existing machine within your machinepack. Verify the machine's file name and export.

Warnings

gotcha The built-in test driver included with `test-machinepack` is explicitly labeled as 'pretty basic' and not recommended for serious use. Users are encouraged to utilize external drivers, such as `test-machinepack-mocha`, for more robust and feature-rich testing. ↓

fix Migrate to a recommended external test driver (e.g., `test-machinepack-mocha`) for comprehensive testing needs. This module should primarily be used for its runner interface for custom drivers.

deprecated The package appears to be unmaintained since 2017 based on its GitHub activity and copyright dates. While functional, it may not receive updates for new Node.js versions or security fixes, potentially leading to compatibility issues. ↓

fix Evaluate the stability and compatibility with your current Node.js environment. For new projects, consider alternatives or be prepared to fork and maintain the package yourself if extensive `node-machine` testing is required.

gotcha Test definitions are written in JSON or JSON5 format, which differs significantly from traditional JavaScript/TypeScript test files. This can be a steep learning curve for developers unfamiliar with the `node-machine` convention. ↓

fix Familiarize yourself with the `node-machine` test specification and the JSON/JSON5 structure. Refer to the examples provided in `machinepack-npm`'s test directory for practical usage patterns.

Install

npm install test-machinepack

yarn add test-machinepack

pnpm add test-machinepack

Imports

testmachinepack CLI
wrong
```
node testmachinepack
```
correct
```
testmachinepack
```
The primary way to use this package is via its globally installed CLI command. Installation via `npm install -g` is typically required.
runTests
wrong
```
import { runTests } from 'test-machinepack';
```
correct
```
const runTests = require('test-machinepack');
```
Programmatic usage is primarily for building custom test drivers. The package exports a single function as its default (CommonJS) export. ESM named imports will not work.
runTests (ESM)
wrong
```
import * as testMachinepack from 'test-machinepack';
```
correct
```
import runTests from 'test-machinepack';
```
While primarily a CommonJS package from 2017, modern bundlers can often handle importing the default CommonJS export as an ESM default import.

Quickstart

Demonstrates global installation and basic CLI usage of `test-machinepack` to run tests defined in a JSON5 file within a simulated machinepack structure.

npm install -g test-machinepack
mkdir my-awesome-machinepack
cd my-awesome-machinepack
# Assuming you have `machinepack` installed globally to use `pm scrub`
# npm install -g machinepack
pm scrub
mkdir tests
cat > tests/example-machine.json5 <<EOF
{
  "machine": "example-machine",
  "expectations": [
    {
      "using": {
        "input1": "hello"
      },
      "outcome": "success"
    },
    {
      "using": {
        "input1": ""
      },
      "outcome": "error",
      "todo": true
    }
  ]
}
EOF

# Run tests using the built-in (basic) driver
testmachinepack