gauntlet

Gauntlet is a tiny test runner meant to replace things like mocha by using test libraries that became stable in node 20.

Goals:

• no dependencies
• fast
• tests written in ESM typescript with incremental compilation
• good defaults that can be changed with CLI options

Features:

• If all tests pass, it just prints out "Tests complete: N passed". If it takes more than a few milliseconds to run them, it will update a one-line counter as it works.
• Optionally, you can print out a mocha-style tree-list of the tests and their status emoji.
• Optionally, you can see the stdout/stderr from the tests (normally hidden).
• Optionally, you can see a wall of shame of the slowest tests.
• Tests are normally compiled from tests/ into a local cache folder, but you can change either folder name.
• Run or skip tests based on a regex. Change the timeout if you have slow tests.

Requirements:

• nodejs >= 20 (22+ is better, node:test improved a lot in 22)
• typescript 5

How to use

Put your tests in tests/ and give them filenames that end with .test.ts. Use suite/test or describe/it notation from the node:test module to define your tests, and assert using node:assert. Then run the tests with:

npx gauntlet

Everything from your tests/ folder will be copied over into a new .gauntlet/ folder as .gauntlet/tests/. Anything that ends with .ts will be compiled using the typescript compiler, and the compiler output will have an .mjs extension.

As an optimization, if the only files that have changed since the last test run are .test.ts files, only those will be recompiled. If anything else has changed, all .ts files will be recompiled.

Then, the entire lib/ folder is copied into .gauntlet/lib/ so that relative imports will work inside the tests.

You can specify different names for the test folder, the .gauntlet/ folder, and the lib folder, and you can also list other folders to copy (for example, web assets used by tests).

You can wipe the .gauntlet/ folder with: npx gauntlet --clean

All possible options are listed with: npx gauntlet --help

You can also list the defaults as a set of explicit command-line arguments with: npx gauntlet --config

Gotchas

• "An entire file timed out." The nodejs test runner will start its stopwatch when all test files are enqueued, not when a test starts actually running. So if you have a lot of tests, some of them may timeout before they even get to start. This gets reported (by the nodejs test runner) as a timeout of the entire file. Arguably this is a bug in their runner, but you can work around it by extending your timeout.

• Test name matching against the full name (suite names + test name) is broken in node v20, but fixed in node v22. For example, a test named "butters itself" under suite "toast" will not match "toast butters itself" in node v20, but will in node v22. Upgrading to node v22 has a side benefit of making the test runner faster, so I recommend it.

Interesting

• https://github.com/eeue56/ts-assert