Node.js unit tests

Run JavaScript tests with the built-in Node.js test runner and publish JUnit results in GitLab. No third-party test framework is required.

Run tests

Use the default CI Tools tools image, which includes Node.js and Bash. A custom image must provide Bash, GNU find/sort, and Node.js 20 or later with the built-in JUnit reporter. Install application dependencies in your existing preparation jobs when tests need them; this component does not run npm install.

Include common and node-unittest in .gitlab-ci.yml:

include:
  - component: $CI_SERVER_FQDN/xrow-public/ci-tools/common@stable
  - component: $CI_SERVER_FQDN/xrow-public/ci-tools/node-unittest@stable
    inputs:
      path: tests

Create tests/example.test.mjs:

import assert from 'node:assert/strict';
import {test} from 'node:test';

test('adds numbers', () => {
  assert.equal(2 + 3, 5);
});

The test:node-unittest job runs the test and uploads node-unittest-junit.xml. Failed assertions fail the job; the JUnit report is retained on failure. Test results also appear in the job log.

Select files and reports

The default path is . and the default filename pattern is *.test.*js, matching .test.js, .test.mjs, and .test.cjs files recursively. Discovery excludes node_modules and .git directories. A missing directory or no matching files fails the job.

Set pattern for other naming conventions and junit-report to choose a report path relative to the project directory. Use distinct name and junit-report values when including multiple instances. If your naming convention does not match the default existence rule, also override rules, for example with rules: [{when: on_success}].

The component uses Node's native assertions, exit status, and JUnit reporter. It does not run third-party test frameworks, TypeScript compilation, or coverage collection. Node's own skipped/TODO tests remain visible in its report; a successful job does not imply that those tests executed.

Inputs

Name	Description	Default	Type
---	---	---	---
allow-failure	Should the pipeline continue when one or more tests fail?	false	boolean
image	The image used to run the tests.	${CI_TOOLS_REPO}/tools:${CI_TOOLS_COMPONENT_VERSION}	string
junit-report	Path to the JUnit report shown in the GitLab test summary.	node-unittest-junit.xml	string
name	The name of the test job.	node-unittest	string
needs	The jobs that this job depends on.	[]	array
path	The directory to search for Node.js test files.	.	string
pattern	The file name pattern used to discover Node.js test files.	*.test.*js	string
rules	The rules for the test job.	[{"exists":["**/*.test.*js"],"when":"on_success"},{"when":"never"}]	array
stage	The stage for the test job.	test	string