@vangware/test

✅ Equality test with enforced legibility (based on RITEway and inspired by uvu).

Writing tests

TypeScript

import type { Tests } from "@vangware/test";
import { add } from "../src/add.js";

export default [
	{
		given: "a 1 and a 2",
		must: "return 3",
		received: () => add(2)(1),
		wanted: () => 3,
	},
	{
		given: "a 1 and a -2",
		must: "return -1",
		received: () => add(-2)(1),
		wanted: () => -1,
	},
] as Tests<number>;

JavaScript

import { add } from "../src/add.js";

/** @type {import("@vangware/test").Tests<number>} */
export default [
	{
		given: "a 1 and a 2",
		must: "return 3",
		received: () => add(2)(1),
		wanted: () => 3,
	},
	{
		given: "a 1 and a -2",
		must: "return -1",
		received: () => add(-2)(1),
		wanted: () => -1,
	},
];

Alternatives

Instead of exporting an Array of Test as default, the export can also be a single Test:

import type { Test } from "@vangware/test";
import { add } from "../src/add.js";

export default {
	given: "a 1 and a 2",
	must: "return 3",
	received: () => add(2)(1),
	wanted: () => 3,
} as Test<number>;

Or multiple exports with different tests:

import type { Test } from "@vangware/test";
import { add } from "../src/add.js";

export const test1: Test<number> = {
	given: "a 1 and a 2",
	must: "return 3",
	received: () => add(2)(1),
	wanted: () => 3,
};

export const test2: Test<number> = {
	given: "a 1 and a -2",
	must: "return -1",
	received: () => add(-2)(1),
	wanted: () => -1,
};

It can also be used directly without the test bin by importing the different utils directly:

import { test } from "@vangware/test";
import { customFormatter } from "./customFormatter.js";

test({
	given: "a 1 and a 2",
	must: "return 3",
	received: () => add(2)(1),
	wanted: () => 3,
}).then(customFormatter);

Running

This should suffice:

npx test

When working with TypeScript files directly, ts-node is required, and then to run it:

NODE_OPTIONS='--loader ts-node/esm' npx test

Coverage

c8 can be added and then:

# For JavaScript
npx c8 test

# For TypesScript
NODE_OPTIONS='--loader ts-node/esm' npx c8 test

Output

If a test fails, it looks like this:

[TEST] ./tests/example.test.ts
[FAIL] Given a 1 and a 2, must return 3, but...
	└ it has the wrong value. Wanted 3 but received 4.

And if the wanted/received type is more complex, like an object, then the output goes into details about the error:

[TEST] ./tests/example.test.ts
[FAIL] Given an object, must add a single property, but...
	├ foo.bar has the wrong value. Wanted 1 but received 2.
	├ foo.baz.1 is missing.
	└ bar was set with the value "bar".

Documentation

Documentation is available HERE. It is auto-generated with typedoc based on the JSDocs and the types in the source. It shouldn't be necessary to read this. Code editors like VS Code integrate the documentation in the UI.

Changelog

Changelog can be found HERE.

Test coverage

Test coverage can be found HERE.