@vangware/test | @vangware/test

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

Usage

Write:

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:

@vangware/test

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

Changelog can be found HERE.

Test coverage

Test coverage can be found HERE.

Index

Suite Type aliases

Test Type aliases

Variables

Common Functions

Compare Functions

Suite Functions

Test Functions

Suite Type aliases

SuiteImport

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

Promise import of a file containing a suite.

SuiteResult

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

MaybePromise<Value>: Promise<Value> | Value

Value tha can be possibly wrapped in a Promise.

Type parameters

Value

Test

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

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

Output of the test function.

Variables

Const FAIL

FAIL: string = ...

Fail message with colors.

Const PASS

PASS: string = ...

Pass message with colors.

Const UNWANTED_COMMENT

UNWANTED_COMMENT: string = ...

Unwanted comment (// Unwanted in red text).

Common Functions

Const comment

comment(formatter: (input: string) => string): (value: string) => string

- Defined in utils/comment.ts:6
Takes a title and a value and turns it into an inline comment.

Parameters
- 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[]

- Defined in utils/indentMap.ts:8
Maps trough and array of strings and add indent to each item.

Parameters
- lines: ReadOnlyArray<string>
Returns string[]

Const lastAwareMap

lastAwareMap<Item, Output>(mapper: (last: boolean) => (item: Item) => Output): (input: ReadOnlyArray<Item>) => Output[]

- Defined in utils/lastAwareMap.ts:8
Maps trough an array and sets an argument to true when is the last item.

Type parameters
- Item
- Output
Parameters
- 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

- Defined in utils/missingComment.ts:9
Comment for missing items.

Parameters
- value: string
Returns string

Const promiseWrap

promiseWrap<Value>(maybePromise: MaybePromise<Value>): Promise<Value>

- Defined in utils/promiseWrap.ts:9
Given a value that could be either a promise or a value, return the value wrapped in a promise.

Type parameters
- Value
Parameters
- maybePromise: MaybePromise<Value>
Returns Promise<Value>

Const promiseWrapMap

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

- Defined in utils/promiseWrapMap.ts:10
Maps using promiseWrap.

Type parameters
- Value
Parameters
- maybePromises: ReadOnlyArray<MaybePromise<Value>>
Returns Promise<Value>[]

Const stringify

stringify<Input>(input: Input): string

- Defined in utils/stringify.ts:6
Stringifies value reliably (using JSON.stringify).

Type parameters
- Input
Parameters
- input: Input
Returns string

Const stringifyMap

stringifyMap<Input>(input: ReadOnlyArray<Input>): string[]

- Defined in utils/stringifyMap.ts:9
Applies stringify to every value in the given array.

Type parameters
- Input
Parameters
- input: ReadOnlyArray<Input>
Returns string[]

Const wantedComment

wantedComment(value: string): string

- Defined in utils/wantedComment.ts:9
Comment for wanted items.

Parameters
- value: string
Returns string

Compare Functions

Const compare

compare<Wanted>(wanted: Wanted): (received: Wanted) => string

- Defined in compare/compare.ts:11
Compare two values and show the differences between them.

Type parameters
- Wanted
Parameters
- 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

- Defined in compare/compareArrays.ts:16
Compare two arrays and displays the differences (unwanted, missing and matching items).

Type parameters
- Wanted
Parameters
- 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

- Defined in compare/compareObjects.ts:15
Compare two objects and displays the differences (unwanted, missing and matching items).

Type parameters
- Wanted: Record<string, unknown>
Parameters
- wanted: Wanted
Returns (received: Wanted) => string
- - (received: Wanted): string
  - Parameters
    - received: Wanted
    Returns string

Const comparePrimitives

comparePrimitives<Wanted>(wanted: Wanted): <Received>(received: Received) => string

- Defined in compare/comparePrimitives.ts:9
Compares two primitive values.

Type parameters
- Wanted
Parameters
- wanted: Wanted
Returns <Received>(received: Received) => string
- - <Received>(received: Received): string
  - Type parameters
    - Received
    Parameters
    - received: Received
    Returns string

Const stringifyMatchingItems

stringifyMatchingItems(lastParent: boolean): <Item>(matchingItems: ReadOnlyArray<Item>) => string[]

- Defined in compare/stringifyMatchingItems.ts:11
Takes a boolean to know if this is the last item, and an array and returns a string for matching items.

Parameters
- lastParent: boolean
Returns <Item>(matchingItems: ReadOnlyArray<Item>) => string[]
- - <Item>(matchingItems: ReadOnlyArray<Item>): string[]
  - Type parameters
    - Item
    Parameters
    - matchingItems: ReadOnlyArray<Item>
    Returns string[]

Const stringifyMissingItems

stringifyMissingItems<Item>(missingItems: ReadOnlyArray<Item>): string

- Defined in compare/stringifyMissingItems.ts:10
Takes an array and returns a string for missing items.

Type parameters
- Item
Parameters
- missingItems: ReadOnlyArray<Item>
Returns string

Const stringifyUnwantedItems

stringifyUnwantedItems(lastParent: boolean): (input: ReadOnlyArray<unknown>) => string[]

- Defined in compare/stringifyUnwantedItems.ts:11
Takes a boolean to know if the paren is in it's last item, and an array and returns a string of unwanted elements.

Parameters
- lastParent: boolean
Returns (input: ReadOnlyArray<unknown>) => string[]
- - (input: ReadOnlyArray<unknown>): string[]
  - Parameters
    - input: ReadOnlyArray<unknown>
    Returns string[]

Suite Functions

Const isSuiteResult

isSuiteResult<Actual>(value: Actual | SuiteResult): value is SuiteResult

- Defined in suite/isSuiteResult.ts:10
Check if given value is a SuiteResult object.

Type parameters
- Actual
Parameters
- value: Actual | SuiteResult
Returns value is SuiteResult

Const stringifySuiteResult

stringifySuiteResult(__namedParameters: SuiteResult): string

- Defined in suite/stringifySuiteResult.ts:10
Takes a SuiteResult object and returns a stringified version of it.

Parameters
- __namedParameters: SuiteResult
Returns string

Const stringifySuiteResults

stringifySuiteResults(suiteResults: ReadOnlyArray<SuiteResult>): string

- Defined in suite/stringifySuiteResults.ts:10
Takes an array of SuiteResult and returns an array of strings.

Parameters
- suiteResults: ReadOnlyArray<SuiteResult>
Returns string

Const suite

suite<Value>(tests: ReadOnlyArray<Test<Value>>): (name: string) => Promise<SuiteResult>

- Defined in suite/suite.ts:12
Creates a new test suite (array of tests).

Type parameters
- Value
Parameters
- tests: ReadOnlyArray<Test<Value>>
Returns (name: string) => Promise<SuiteResult>
- - (name: string): Promise<SuiteResult>
  - Parameters
    - name: string
    Returns Promise<SuiteResult>

Const suiteImport

suiteImport(path: string): Promise<SuiteResult>

- Defined in suite/suiteImport.ts:8
Import a file that exports a suite.

Parameters
- path: string
Returns Promise<SuiteResult>

Const suitesImport

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

- Defined in suite/suitesImport.ts:10
Imports all the suites of the given array of paths.

Parameters
- paths: ReadOnlyArray<string>
Returns Promise<SuiteResult[]>

Test Functions

Const areTestResults

areTestResults(maybeTestResults: ReadOnlyArray<unknown>): maybeTestResults is ReadOnlyArray<TestResult>

- Defined in test/areTestResults.ts:10
Check if all the items in an array are TestResults.

Parameters
- maybeTestResults: ReadOnlyArray<unknown>
Returns maybeTestResults is ReadOnlyArray<TestResult>

Const isPassedTestResult

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

- Defined in test/isPassedTestResult.ts:9
Checks if given TestResult passed.

Type parameters
- Actual
Parameters
- value: TestResult | Actual
Returns boolean

Const isTestResult

isTestResult<Actual>(value: TestResult | Actual): value is TestResult

- Defined in test/isTestResult.ts:9
Check if given value is a TestResult object.

Type parameters
- Actual
Parameters
- value: TestResult | Actual
Returns value is TestResult

Const stringifyTestResult

stringifyTestResult(testResult: TestResult): string

- Defined in test/stringifyTestResult.ts:10
Takes a TestResult and returns a stringified version of it.

Parameters
- testResult: TestResult
Returns string

Const stringifyTestResults

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

- Defined in test/stringifyTestResults.ts:10
Takes an array of TestResult and returns an array of strings.

Parameters
- testResults: ReadOnlyArray<TestResult>
Returns string[]

Const test

test<Value>(__namedParameters: Test<Value>): Promise<TestResult>

- Defined in test/test.ts:12
Takes a Test object and returns a TestResult object.

Type parameters
- Value
Parameters
- __namedParameters: Test<Value>
Returns Promise<TestResult>

Const testMap

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

- Defined in test/testMap.ts:10
Map given array of tests.

Type parameters
- Value
Parameters
- tests: ReadOnlyArray<Test<Value>>
Returns Promise<TestResult>[]

Const testName

testName(__namedParameters: TestResult): string

- Defined in test/testName.ts:9
Takes a TestResult and returns the name of the test.

Parameters
- __namedParameters: TestResult
Returns string

Const testResultsFilterTuple

testResultsFilterTuple(testResults: ReadOnlyArray<TestResult>): readonly [TestResult[], TestResult[]]

- Defined in test/testResultsFilterTuple.ts:10
Filter tests results in a tuple [passed, failed].

Parameters
- testResults: ReadOnlyArray<TestResult>
Returns readonly [TestResult[], TestResult[]]

Generated using TypeDoc

Usage

Documentation

Changelog

Test coverage

Index

Suite Type aliases

Test Type aliases

Variables

Common Functions

Compare Functions

Suite Functions

Test Functions

Suite Type aliases

SuiteImport

SuiteResult

Type declaration

Readonly failed: ReadOnlyArray<TestResult>

Readonly name: string

Readonly passed: ReadOnlyArray<TestResult>

Test Type aliases

MaybePromise

Type parameters

Value

Test

Type parameters

Value

Type declaration

Readonly given: string

Readonly must: string

Readonly received: MaybePromise<Value>

Readonly wanted: MaybePromise<Value>

TestResult

Variables

Const FAIL

Const PASS

Const UNWANTED_COMMENT

Common Functions

Const comment

Parameters

formatter: (input: string) => string

Parameters

input: string

Returns string

Returns (value: string) => string

Parameters

value: string

Returns string

Const indentMap

Parameters

lines: ReadOnlyArray<string>

Returns string[]

Const lastAwareMap

Type parameters

Item

Output

Parameters

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

Parameters

last: boolean

Returns (item: Item) => Output

Parameters

item: Item

Returns Output

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

Parameters

input: ReadOnlyArray<Item>

Returns Output[]

Const missingComment

Parameters

value: string

Returns string

Const promiseWrap

Type parameters

Value

Parameters

maybePromise: MaybePromise<Value>

Returns Promise<Value>

Const promiseWrapMap

Type parameters

Value