open-index/open-npm huggingface dataset:
npm package: @robey/gauntlet
Description: a tiny test runner
Author: Robey Pointer
Latest version: 1.2.0

# 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