uvu

library0.5.6jsnpmunverified

uvu is an extremely fast and lightweight test runner designed for both Node.js and browser environments, currently stable at version 0.5.6. It features a minimalist API, supporting `async`/`await` tests and native ES Modules. While `uvu` ships with its own optional assertion library (`uvu/assert`), it is entirely compatible with any assertion library that throws standard JavaScript Errors for failures. It differentiates itself by its focus on performance, minimal footprint, and flexibility in choosing assertion methods, making it a strong contender for projects prioritizing speed and small bundle sizes. Releases are typically patch-based, addressing bugs and improving compatibility, with major feature additions occurring less frequently.

testing

npm install uvu

github ↗package ↗

INSTALL

IMPORT

SIG · UVU

uvu

testingjavascriptv0.5.6

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

test

✓ import { test } from 'uvu';

✗ const test = require('uvu');

`test` is a named export. ESM is the preferred and modern usage, especially since v0.5.0 introduced native ESM support. Using `require` in a pure ESM context will lead to errors.

assert

✓ import * as assert from 'uvu/assert';

✗ import { is, equal } from 'uvu/assert';

The `uvu/assert` module exports its assertion methods as a single module object, so use `import * as assert from 'uvu/assert;'` and then access methods like `assert.is()`. Attempting to destructure individual assertion methods directly will fail.

suite

✓ import { suite } from 'uvu';

✗ import suite from 'uvu';

`suite` is a named export for grouping tests. Like `test`, `require('uvu').suite` is the CJS equivalent but generally discouraged in modern setups.

This quickstart demonstrates basic test definition with `uvu` and shows how to use its built-in `uvu/assert` module for various assertions, including `is`, `snapshot`, and `equal`.

import { test } from 'uvu'; import * as assert from 'uvu/assert'; test('Math.sqrt()', () => { assert.is(Math.sqrt(4), 2); assert.is(Math.sqrt(144), 12); assert.is(Math.sqrt(2), Math.SQRT2); }); test('JSON operations', () => { const input = { foo: 'hello', bar: 'world' }; const output = JSON.stringify(input); // Snapshot assertions require the exact string match assert.snapshot(output, `{"foo":"hello","bar":"world"}`); // Deep equality assertion assert.equal(JSON.parse(output), input, 'JSON parse matches original'); }); test.run(); // To run this test file: // $ npm install --save-dev uvu // $ uvu tests/demo.js

uvu --version

Debug

Known issues

breakingThe immutability protection on the `context` object, which prevented modification within test handlers, was removed. `uvu` now passes the original `context` object directly to test handlers, allowing for mutations. This might alter behavior for tests that relied on `context` being read-only within a test.

fix

Review tests that interact with the `suite` context. Ensure any modifications to the context within test handlers are intentional and do not create unintended side effects across tests. If immutability is desired for specific values, clone them explicitly.

affects: >=0.4.0

breakingNative ES Module (ESM) support was introduced, promoting `import` statements. While `uvu` attempts to detect and use ESM, older Node.js versions or CommonJS projects may require the `--require esm` flag (e.g., `node -r esm your-test.js` or `uvu -r esm tests`). Misconfiguration can lead to 'SyntaxError: Cannot use import statement outside a module' or other module resolution issues.

fix

For new projects, configure `package.json` with `"type": "module"` and use `import`/`export`. For mixed or older projects, ensure Node.js is recent enough (>=12 for full native ESM support without flags) or use the `-r esm` flag explicitly when running tests.

affects: >=0.5.0

breakingSince v0.5.6, `uvu` explicitly ensures that tests will fail if they include `process.exit` calls or leave unresolved Promises. Previously, such scenarios might have silently passed or exited without indicating a failure, leading to unreliable test results.

fix

Review tests for `process.exit()` calls within test bodies; these should be removed or mocked if testing exit behavior. Identify and ensure all Promises are properly handled and resolved/rejected within asynchronous tests to prevent unhandled rejections from failing the test suite.

affects: >=0.5.6

gotchaForgetting to call `test.run()` (or `suite.run()` for named suites) at the end of your test file will result in no tests being executed, as `uvu` queues tests and only executes them when explicitly told to.

fix

Always include `test.run();` as the last statement in your test file to initiate the test execution process. For modularized test files that are imported by a runner, ensure the runner handles the execution.

affects: All versions

Errors

Common errors & fixes

SyntaxError: Cannot use import statement outside a module

Attempting to use ES module `import` syntax in a Node.js environment configured for CommonJS, or an older Node.js version without native ESM support, without the `--require esm` flag.

fix

Ensure your `package.json` has `"type": "module"` if you intend to write ES Modules, or use the `--require esm` flag with Node.js or `uvu` CLI: `node -r esm your-test.js` or `uvu -r esm tests/`.

TypeError: uvu.test is not a function (or similar for suite, assert)

This usually indicates that `test` or `suite` were incorrectly imported as default exports (`import test from 'uvu'`) rather than named exports (`import { test } from 'uvu'`), or that `uvu/assert` methods are being destructured instead of accessed via the `assert` object.

fix

For `test` and `suite`, use named imports: `import { test, suite } from 'uvu';`. For `uvu/assert`, use `import * as assert from 'uvu/assert';` and then call methods like `assert.is()`.

ReferenceError: assert is not defined

The `uvu/assert` module is optional and must be explicitly imported into your test file if you wish to use its assertion methods.

fix

Add `import * as assert from 'uvu/assert';` at the top of your test file where `assert` is needed.

Upgrade

Version history

0.5.6latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/lukeed/uvu ↗

packagehttps://www.npmjs.com/package/uvu ↗