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

Usage

All this configurations are setup automatically by @vangware/create-package when creating a new package. For manual setup of each file, follow the instructions below.

📦 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
Copy

Add a test script to package.json:

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

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

{
    "scripts": {
        "test": "NODE_OPTIONS='--loader tsx --no-warnings' test"
    }
}
Copy

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

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

{
    "scripts": {
        "test": "NODE_OPTIONS='--loader tsx --no-warnings' c8 test"
    }
}
Copy

Run tests:

pnpm test
# or
npm test
# or
yarn test
Copy

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

🌎 Browser

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

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

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

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,
    },
];
Copy

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

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,
};
Copy

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

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.
Copy

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".
Copy

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.