Test All Versions

6.2.0 · active · verified Tue Apr 21

The `test-all-versions` package is a Node.js CLI tool designed to run a project's test suite against all published versions of one or more specified npm dependencies. It helps ensure backward compatibility of libraries by automating the arduous process of testing across a matrix of dependency versions. Currently stable at version 6.2.0, the tool is primarily configured via a `.tav.yml` file, allowing for advanced scenarios such as testing against specific Node.js version ranges, handling peer dependencies, running multiple test commands, defining `preinstall`/`pretest`/`posttest` hooks, and configuring environment variable matrices for comprehensive testing. Its release cadence appears active, indicated by its 6.x version, though a specific schedule isn't published. It differentiates itself from general CI/CD solutions by specifically targeting and simplifying dependency version compatibility testing, making it an invaluable tool for library maintainers.

Common errors

```
Error: Command failed with exit code 1
```
cause One of the test commands specified in `.tav.yml` or via the CLI arguments failed for a particular dependency version.

fix Examine the preceding output for the specific version that failed and the test script's stdout/stderr. Replicate the failure locally by installing the problematic dependency version and running the test manually.
```
Error: No .tav.yml file found and no module specified.
```
cause `tav` was executed without a `.tav.yml` configuration file in the current directory and without specifying the `<module> <semver> <command>` arguments on the command line.

fix Either create a `.tav.yml` configuration file in the current working directory, or specify the module, semver range, and test command directly on the `tav` command line.
```
EACCES: permission denied, mkdir '/tmp/tav-...' (or similar permission errors)
```
cause The temporary directory where `test-all-versions` attempts to install modules and run tests lacks write permissions for the current user or process.

fix Ensure your user account has appropriate permissions to create directories and files in `/tmp` (or your system's designated temporary directory). This issue can sometimes arise in restrictive CI environments or containerized setups.

Warnings

breaking Node.js 14 or higher is now required to run `test-all-versions`.
Fix: Upgrade your Node.js runtime to version 14 or newer. Ensure your CI/CD environment uses a compatible Node.js version.
gotcha Complex configurations using the `.tav.yml` file can lead to verbose output, long execution times, or unexpected test environments if not carefully managed.
Fix: Start with simpler `.tav.yml` configurations. Utilize the `--dry-run` flag to inspect the planned test matrix before full execution. Carefully define Node.js version ranges and peer dependencies to minimize unnecessary test runs.
gotcha Debugging test failures across a large matrix of dependency versions can be challenging due to consolidated output.
Fix: Use the `--quiet` flag to suppress test stdout unless an error occurs. For debugging a specific failure, identify the failing version from the output, then replicate the environment manually by installing that dependency version and running the test script directly.

Install

npm install test-all-versions npm
yarn add test-all-versions yarn
pnpm add test-all-versions pnpm

Imports

tav (CLI Command)
wrong:
```
node_modules/test-all-versions/index.js <module> <semver> <command>
```
correct:
```
tav <module> <semver> <command>
```
This is the primary method of interacting with `test-all-versions` for most developers. `npx tav` can also be used for local installations.
tav (programmatic API)
wrong:
```
import tav from 'test-all-versions';
```
correct:
```
const tav = require('test-all-versions');
```
The package exposes its main function as a CommonJS default export. Programmatic use is available but less common than CLI interaction.
.tav.yml (configuration file)
wrong:
```
(Attempting to pass complex multi-module or matrix configurations solely via command-line arguments)
```
correct:
```
(Place a `.tav.yml` file in your project's root directory)
```
For advanced test matrices involving multiple modules, Node.js versions, environment variables, or hooks, the `.tav.yml` file is the recommended and most capable configuration method.

Quickstart

Demonstrates running tests against multiple versions of the `mysql` and `pg` modules using a `.tav.yml` configuration with environment variables and Node.js version constraints.

/* file: dummy-test.js */
console.log(`Running test for ${process.env.TAV_MODULE_NAME} v${process.env.TAV_MODULE_VERSION} with MYSQL_USER=${process.env.MYSQL_USER ?? 'N/A'}`);
// In a real scenario, you'd import and test the dependency:
// const testedModule = require(process.env.TAV_MODULE_NAME);
// assert.ok(testedModule.someMethod());
process.exit(0); // Simulate passing test

/* file: .tav.yml */
mysql:
  versions: ^2.0.0 || ^3.0.0
  commands: node dummy-test.js
  env:
    - MYSQL_USER=root
    - MYSQL_PASS=secret!
  node: ">=14.0.0"
pg:
  versions: "*"
  commands: node dummy-test.js

/* Run from your terminal */
# First, install test-all-versions locally or globally:
# npm install test-all-versions
# Or use npx for local execution:
npx tav --verbose

view raw JSON →