Registry / testing / japa
library4.0.0jsnpmunverified

Japa is a lean and fast Node.js test runner designed for both testing applications and for building custom test runners. The current stable version is v10.4.0, with minor and patch releases occurring frequently—typically several times a quarter—and major versions released periodically as breaking changes are introduced. A key differentiator is its minimal core, offering faster boot times compared to alternatives like Mocha or Ava, primarily because it does not ship with its own CLI; tests are executed directly as standard Node.js scripts. Japa supports ES6 async/await syntax, ES modules, test groups with lifecycle hooks, regression tests, and offers an extensible assertion system often utilized via plugins. Its design philosophy emphasizes simplicity and provides the foundational components for highly customized testing environments.

npm install japa
INSTALL
IMPORT
SIG · JAPA
J
japa
testingjavascriptv4.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

test
import test from 'japa'
import { test } from 'japa'
The primary testing function is the default export in ESM. For CommonJS, use `const test = require('japa')`.
Test
import { Test } from 'japa'
import Test from 'japa'
The `Test` class is a named export, used for programmatic control over individual test instances, particularly when building custom runners.
Runner
import { Runner } from 'japa'
import Runner from 'japa'
The `Runner` class is a named export, essential for orchestrating test execution programmatically and for developing custom test runner workflows.

This quickstart demonstrates basic Japa tests, organizes them into groups with lifecycle hooks, configures the `@japa/assert` plugin for assertions, and shows how to programmatically run tests.

import test, { Runner } from 'japa' import { assert } from '@japa/assert' // Japa typically uses plugins for assertions // Configure Japa to discover test files and use the assertion plugin test.configure({ files: ['**/*.spec.ts'], // Adjust glob pattern to your test file naming plugins: [assert()] }) // A simple function to be tested function add(a: number, b: number): number { return a + b } // Basic test demonstrating the main `test` function test('should correctly add two positive numbers', ({ assert }) => { assert.equal(add(2, 3), 5) assert.notEqual(add(1, 1), 3) }) // Test group with lifecycle hooks test.group('Complex Operations', (group) => { let result: number // State for the group group.beforeEach(() => { // Executed before each test in this group result = 0 console.log(' [Group Hook] Resetting result to 0') }) group.afterEach(() => { // Executed after each test in this group console.log(` [Group Hook] Current result after test: ${result}`) }) test('should initialize result to 0', ({ assert }) => { assert.equal(result, 0) }) test('should allow adding values incrementally', ({ assert }) => { result = add(result, 10) assert.equal(result, 10) result = add(result, 5) assert.equal(result, 15) }) }).timeout(5000) // Example of a group-level timeout in milliseconds // Manually run the tests. This is optional if using a global runner setup. const runner = new Runner() runner.run() .then(() => console.log('Tests completed.')) .catch((error) => console.error('Tests failed:', error))
Debug
Known issues
breakingIn v10.0.0, the way regression tests are reported by the emitter changed. This may break custom test reporters that rely on the `test:start` and `test:end` emitter events to determine the state of a test, especially for regression test scenarios.
fix
Review and update custom test reporters to adapt to the new emitter event structure for regression tests.
affects: >=10.0.0
breakingWith v9.0.0, the `title` property within `test:start` and `test:end` events no longer provides a custom `toString` method. Direct access to the test title should now use `event.title.original` or `event.title.expanded` properties.
fix
Modify any code accessing test titles from emitter events to use `event.title.original` or `event.title.expanded`.
affects: >=9.0.0
gotchaJapa is intentionally minimal and does not ship with a command-line interface (CLI). Tests are executed directly as standard Node.js scripts (e.g., `node test/my-test.spec.js`), which deviates from many other test runners that provide `test` or `run` commands.
fix
Ensure your project's `package.json` scripts or CI configurations directly invoke test files using `node` or a custom runner built on Japa.
affects: *
gotchaThe `bail` mode, introduced in v10.0.0, causes the test runner to exit immediately upon the first failing test. While useful for CI/CD, this can halt entire test suites prematurely. Subsequent versions (v10.1.1, v10.2.0, v10.3.0) included fixes for `bail` mode idempotency and skipping behavior.
fix
Understand the implications of `bail` mode for your workflow. If full test suite execution is always required, ensure `bail` mode is not enabled. Review specific patch notes for `bail` related fixes if encountering unexpected behavior on versions between 10.0.0 and 10.3.0.
affects: >=10.0.0
gotchaWhile Japa includes 'inbuilt assertion library' as a feature, common practice and examples often show the use of `@japa/assert` as a plugin for a more robust and explicit assertion experience. Users expecting a globally available `assert` might be confused.
fix
Install `@japa/assert` (`npm i -D @japa/assert`) and register it as a plugin in your Japa configuration (e.g., `test.configure({ plugins: [assert()] })`) to enable the `assert` object in your test callbacks.
affects: *
Errors
Common errors & fixes
TypeError: test is not a function
The main `test` function was imported incorrectly, often by attempting a named import when it is the default export, or by using CommonJS `require` syntax incorrectly.
fix
For ESM, ensure you use `import test from 'japa'`. For CommonJS, use `const test = require('japa')`.
TypeError: Cannot read properties of undefined (reading 'group')
The `test` function was not imported correctly, leading to `test.group` being called on an undefined or improperly imported `test` object.
fix
Verify that `test` is correctly imported as the primary export of the `japa` package. For ESM: `import test from 'japa'`. For CJS: `const test = require('japa')`.
Error: Timeout of 5000ms exceeded for test "should perform a long running operation"
A test or a test group exceeded its configured timeout duration before completing execution, often due to long-running asynchronous operations or infinite loops.
fix
Optimize the test's execution time, increase the timeout duration using `test.timeout(ms)` or `group.timeout(ms)`, and ensure all asynchronous operations within the test are properly awaited.
Upgrade
Version history
4.0.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
4 hits · last 30 days
node
4
Resources
japa — npm install japa · libregistry