@vangware/test

Equality test with enforced readability, based on the concept of RITEway and inspired by uvu.

Usage

Node

Install @vangware/tests as a dev dependency:

pnpm add -D @vangware/test
# or
npm install -D @vangware/test
# or
yarn add --dev @vangware/test

Add a test script to package.json:

{
	"scripts": {
		"test": "test"
	}
}

pnpm add -D tsx
# or
npm install -D tsx
# or
yarn add --dev tsx

{
	"scripts": {
		"test": "NODE_OPTIONS='--import tsx' test"
	}
}

pnpm add -D c8
# or
npm install -D c8
# or
yarn add --dev c8

{
	"scripts": {
		"test": "c8 test"
	}
}

{
	"scripts": {
		"test": "NODE_OPTIONS='--import tsx' c8 test"
	}
}

Run tests:

pnpm test
# or
npm test
# or
yarn test

Deno

Import @vangware/test using the npm: prefix, and use it directly:

import { test } from "npm:@vangware/test";
import { add } from "../src/add.js";

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

Browser

Import @vangware/test using esm.sh, and use it directly:

<script type="module">
	import { test } from "https://esm.sh/@vangware/test";
	import { add } from "../src/add.js";

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

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,
	},
] satisfies Tests<number>;

JavaScript

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

/** @satisfies {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,
	},
];

Other 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,
} satisfies 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 (like with the Deno and Browser examples above):

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);

Default output

@vangware/tests provides a default output for the tests. 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".

But developers can choose to run test directly and use their own formatter, as it was pointed out in the previous section.

Useful links

• Documentation: TypeDoc generated documentation.
• Changelog: List of changes between versions.
• Tests Coverage: Coveralls page with tests coverage.