werkregie/doc/adrs/0002-2026-10-14.node-test.md

Node's Own Test Runner for the JavaScript of the Page

Status:

• proposed: 2026-10-14
• accepted: 2026-10-14
• rejected: -
• superseded: -

Decision [accepted]: The build tests the JavaScript of the page with node --test, without npm packages: the smallest new technology that tests the logic of the page.

Context and Problem Statement

dashboard/src/main/resources/static/index.html holds all JavaScript of the page; no automated test checks it. werkrevisor named the gap in werkregie PR#78, on the counting of the merges by day, week and month. A test framework for JavaScript is a new technology in werkregie and needs the consent of the human.

Technical Background

• The page is plain JavaScript in classic scripts, served by the dashboard; there is no bundler and no package.json.
• In the Werk family, werkbaum tests its frontend with Vitest and jsdom; Werkator builds it with npm ci, so its build host has Node.
• Node has a test runner and assertions of its own since Node 18 (node:test, node:assert).
• The licence allowlist of the required checks does not hold UPL-1.0, the licence of GraalJS.

Considered Options

• node --test without npm
• Vitest and jsdom, as werkbaum
• GraalJS in the Kotest tests

node --test without npm

A Gradle task runs node --test on test files next to the Kotlin tests; the tested functions move into a script of their own.

Advantages

• No package, so no lock file, no npm audit and no licence check for npm.
• Node exists on Werkator's build host already.

Disadvantages

• Only functions without the DOM are testable.
• Each machine that runs ./gradlew build needs Node.

Vitest and jsdom, as werkbaum

Advantages

• Tests of the rendered HTML too; the same tools as werkbaum.

Disadvantages

• npm packages: a lock file, and the npm checks of vulnerabilities and licences become binding.

GraalJS in the Kotest tests

Advantages

• The build stays a JVM build.

Disadvantages

• A large dependency under UPL-1.0, outside the licence allowlist.

Decision Outcome

mi chose node --test without npm on 2026-10-14. A move to Vitest and jsdom stays open for when the rendered HTML needs tests.