✅ hTest

Declarative unit testing, for everyone

✅ hTest

Declarative, boilerplate-free unit testing, for everyone.

https://htest.dev

Features at a glance

Quick start

Suppose you have written a utility function sum() that takes a variable number of arguments and adds them together. Testing it could be as simple as:

import { sum } from "../src/util.js";

export default {
	run: sum,
	tests: [
		{
			arg: 1,
			expect: 1
		},
		{
			args: [1, 2, 3],
			expect: 6
		},
		{
			args: [],
			expect: undefined
		}
	]
}

Yes, that’s really it! You can add name, descrption and other metadata if you want, but you don’t have to.

But the real power of hTest is in its nested structure. Suppose we wanted to add more tests for sum(), e.g. for the case where you’re summing with NaN. We can abstract away the commonality between these tests, and write them as a nested object:

import { sum } from "../src/util.js";

export default {
	run: sum,
	tests: [
		{
			arg: 1,
			expect: 1
		},
		{
			args: [1, 2, 3],
			expect: 6
		},
		{
			args: [],
			expect: undefined
		},
		{
			name: "With NaN",
			run (...args) {
				return sum(NaN, ...args);
			},
			expect: NaN,
			tests: [
				{
					args: [1, 2, 3],
				},
				{
					args: [],
				},
				{
					args: [NaN]
				}
			]
		}
	]
}

Now let’s suppose these NaN tests grew too much to be maintained in a single file. You can just move them whenever you want, and import them:

import { sum } from "../src/util.js";
import NaNTests from "./sum-nan.js";

export default {
	run: sum,
	tests: [
		{
			arg: 1,
			expect: 1
		},
		{
			args: [1, 2, 3],
			expect: 6
		},
		{
			args: [],
			expect: undefined
		},
		NaNTests
	]
}

Of course this is a rather contrived example, but it showcases some of the essence of hTest.

What the hTest? Do we really need another unit testing framework?

Unit testing is hard enough as it stands — the more friction in writing tests, the fewer get written. hTest is a unit testing framework that focuses on making it as quick and painless as possible to write tests. Forget nested function calls with repetitive code. hTest aims to eliminate all boilerplate, so you can focus on writing the actual tests.

hTest can be used in one of two ways: JS-first or HTML-first.

JS-first mode

HTML-first mode

Write your tests in nested object literals, and you can run them either in Node or in the browser. Tests inherit values they don’t specify from their parents, so you never have to repeat yourself.

Write your tests in HTML files and run them only in the browser.
  • More suitable for pure JS code.
  • Compatible with CI and other automated test running processes.
  • Code must be compatible with Node to use the Node test runner.
  • More suitable for UI-heavy code.
  • Pass-criteria extends beyond value matching or error catching, and could even be things like what CSS selectors match or what the DOM looks like.
  • Reactive evaluation: if the HTML changes or the user interacts with the UI, relevant tests are re-evaluated.
  • Mock interactions like click or focus with HTML attributes.

You can even mix and match the two modes in the same testsuite! E.g. even a UI-heavy library has many JS-only functions that are better tested via JS-first tests.

Sample terminal output

Roadmap

hTest is still a work in progress, but is stable enough to be used in production. It was soft launched in Q4 2023, but has been in use since 2022 (2017 if you count its early precursor — though that only included the HTML syntax).

The main things that still need to be done before launch are:

Any help with these would be greatly appreciated!

hTest in the wild

JS-first testsuites

HTML-first testsuites

Testsuites

Single page tests