• Public
  • Public/Protected
  • All
Vangware's Test

Build Status Coverage License NPM Version Open Issues

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



import { suite } from "@vangware/test";

const add = (addend2: number) => (addend1: number) => addend1 + addend2;

export default suite([
        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
])("Example suite name (optional)");

Then run:


If let's say the first test fails, the error reads something like this:

[FAIL] Example suite name (optional)

> Given a 1 and a 2, must return 3.

Received: 4
Wanted:   3


Documentation can be found HERE. It is auto-generated with typedoc based on the JSDocs and the types in the source. Shouldn't be necessary to read this, code editors like VSCode integrate the documentation in the UI.


Changelog can be found HERE.

Test coverage

Test coverage can be found HERE.


Suite Type aliases


SuiteImport: Promise<{ default: SuiteResult | ((name: string) => SuiteResult) }>

Promise import of a file containing a suite.


SuiteResult: { failed: ReadOnlyArray<TestResult>; name: string; passed: ReadOnlyArray<TestResult> }

Output object given by a suite.

Type declaration

  • Readonly failed: ReadOnlyArray<TestResult>

    Array of failed tests.

  • Readonly name: string

    Name of the test suite.

  • Readonly passed: ReadOnlyArray<TestResult>

    Array of passed tests.

Test Type aliases


MaybePromise<Value>: Promise<Value> | Value

Value tha can be possibly wrapped in a Promise.

Type parameters

  • Value


Test<Value>: { given: string; must: string; received: MaybePromise<Value>; wanted: MaybePromise<Value> }

Object that describes a test.

Type parameters

  • Value

Type declaration

  • Readonly given: string

    String explaining the given value.

  • Readonly must: string

    String explaining what the test must return.

  • Readonly received: MaybePromise<Value>

    Value being tested.

  • Readonly wanted: MaybePromise<Value>

    Expected value.


TestResult: Pick<Test<unknown>, "given" | "must"> & { error?: string }

Output of the test function.


Const FAIL

FAIL: string = ...

Fail message with colors.

Const PASS

PASS: string = ...

Pass message with colors.


UNWANTED_COMMENT: string = ...

Unwanted comment (// Unwanted in red text).

Common Functions

Const comment

  • comment(formatter: (input: string) => string): (value: string) => string
  • Takes a title and a value and turns it into an inline comment.


    • formatter: (input: string) => string
        • (input: string): string
        • Parameters

          • input: string

          Returns string

    Returns (value: string) => string

      • (value: string): string
      • Parameters

        • value: string

        Returns string

Const indentMap

  • indentMap(lines: ReadOnlyArray<string>): string[]
  • Maps trough and array of strings and add indent to each item.


    • lines: ReadOnlyArray<string>

    Returns string[]

Const lastAwareMap

  • lastAwareMap<Item, Output>(mapper: (last: boolean) => (item: Item) => Output): (input: ReadOnlyArray<Item>) => Output[]
  • Maps trough an array and sets an argument to true when is the last item.

    Type parameters

    • Item

    • Output


    • mapper: (last: boolean) => (item: Item) => Output
        • (last: boolean): (item: Item) => Output
        • Parameters

          • last: boolean

          Returns (item: Item) => Output

            • (item: Item): Output
            • Parameters

              • item: Item

              Returns Output

    Returns (input: ReadOnlyArray<Item>) => Output[]

      • (input: ReadOnlyArray<Item>): Output[]
      • Parameters

        • input: ReadOnlyArray<Item>

        Returns Output[]

Const missingComment

  • missingComment(value: string): string

Const promiseWrap

  • promiseWrap<Value>(maybePromise: MaybePromise<Value>): Promise<Value>
  • Given a value that could be either a promise or a value, return the value wrapped in a promise.

    Type parameters

    • Value


    Returns Promise<Value>

Const promiseWrapMap

  • promiseWrapMap<Value>(maybePromises: ReadOnlyArray<MaybePromise<Value>>): Promise<Value>[]

Const stringify

  • stringify<Input>(input: Input): string
  • Stringifies value reliably (using JSON.stringify).

    Type parameters

    • Input


    • input: Input

    Returns string

Const stringifyMap

  • stringifyMap<Input>(input: ReadOnlyArray<Input>): string[]
  • Applies stringify to every value in the given array.

    Type parameters

    • Input


    • input: ReadOnlyArray<Input>

    Returns string[]

Const wantedComment

  • wantedComment(value: string): string

Compare Functions

Const compare

  • compare<Wanted>(wanted: Wanted): (received: Wanted) => string
  • Compare two values and show the differences between them.

    Type parameters

    • Wanted


    • wanted: Wanted

    Returns (received: Wanted) => string

      • (received: Wanted): string
      • Parameters

        • received: Wanted

        Returns string

Const compareArrays

  • compareArrays<Wanted>(wanted: ReadOnlyArray<Wanted>): (received: ReadOnlyArray<Wanted>) => string
  • Compare two arrays and displays the differences (unwanted, missing and matching items).

    Type parameters

    • Wanted


    • wanted: ReadOnlyArray<Wanted>

    Returns (received: ReadOnlyArray<Wanted>) => string

      • (received: ReadOnlyArray<Wanted>): string
      • Parameters

        • received: ReadOnlyArray<Wanted>

        Returns string

Const compareObjects

  • compareObjects<Wanted>(wanted: Wanted): (received: Wanted) => string
  • Compare two objects and displays the differences (unwanted, missing and matching items).

    Type parameters

    • Wanted: Record<string, unknown>


    • wanted: Wanted

    Returns (received: Wanted) => string

      • (received: Wanted): string
      • Parameters

        • received: Wanted

        Returns string

Const comparePrimitives

  • comparePrimitives<Wanted>(wanted: Wanted): <Received>(received: Received) => string
  • Compares two primitive values.

    Type parameters

    • Wanted


    • wanted: Wanted

    Returns <Received>(received: Received) => string

      • <Received>(received: Received): string
      • Type parameters

        • Received


        • received: Received

        Returns string

Const stringifyMatchingItems

  • stringifyMatchingItems(lastParent: boolean): <Item>(matchingItems: ReadOnlyArray<Item>) => string[]
  • Takes a boolean to know if this is the last item, and an array and returns a string for matching items.


    • lastParent: boolean

    Returns <Item>(matchingItems: ReadOnlyArray<Item>) => string[]

      • <Item>(matchingItems: ReadOnlyArray<Item>): string[]
      • Type parameters

        • Item


        • matchingItems: ReadOnlyArray<Item>

        Returns string[]

Const stringifyMissingItems

  • stringifyMissingItems<Item>(missingItems: ReadOnlyArray<Item>): string
  • Takes an array and returns a string for missing items.

    Type parameters

    • Item


    • missingItems: ReadOnlyArray<Item>

    Returns string

Const stringifyUnwantedItems

  • stringifyUnwantedItems(lastParent: boolean): (input: ReadOnlyArray<unknown>) => string[]
  • Takes a boolean to know if the paren is in it's last item, and an array and returns a string of unwanted elements.


    • lastParent: boolean

    Returns (input: ReadOnlyArray<unknown>) => string[]

      • (input: ReadOnlyArray<unknown>): string[]
      • Parameters

        • input: ReadOnlyArray<unknown>

        Returns string[]

Suite Functions

Const isSuiteResult

Const stringifySuiteResult

  • stringifySuiteResult(__namedParameters: SuiteResult): string

Const stringifySuiteResults

  • stringifySuiteResults(suiteResults: ReadOnlyArray<SuiteResult>): string

Const suite

  • suite<Value>(tests: ReadOnlyArray<Test<Value>>): (name: string) => Promise<SuiteResult>
  • Creates a new test suite (array of tests).

    Type parameters

    • Value


    • tests: ReadOnlyArray<Test<Value>>

    Returns (name: string) => Promise<SuiteResult>

Const suiteImport

Const suitesImport

  • suitesImport(paths: ReadOnlyArray<string>): Promise<SuiteResult[]>

Test Functions

Const areTestResults

  • areTestResults(maybeTestResults: ReadOnlyArray<unknown>): maybeTestResults is ReadOnlyArray<TestResult>
  • Check if all the items in an array are TestResults.


    • maybeTestResults: ReadOnlyArray<unknown>

    Returns maybeTestResults is ReadOnlyArray<TestResult>

Const isPassedTestResult

  • isPassedTestResult<Actual>(value: TestResult | Actual): boolean

Const isTestResult

Const stringifyTestResult

  • stringifyTestResult(testResult: TestResult): string

Const stringifyTestResults

  • stringifyTestResults(testResults: ReadOnlyArray<TestResult>): string[]

Const test

  • Takes a Test object and returns a TestResult object.

    Type parameters

    • Value


    • __namedParameters: Test<Value>

    Returns Promise<TestResult>

Const testMap

  • testMap<Value>(tests: ReadOnlyArray<Test<Value>>): Promise<TestResult>[]

Const testName

  • Takes a TestResult and returns the name of the test.


    Returns string

Const testResultsFilterTuple


Generated using TypeDoc