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

Type aliases

MaybePromise

MaybePromise<Value>: Promise<Value> | Value

Value tha can be possibly wrapped in a Promise.

Type parameters

Value

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

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 COMMA

COMMA: "," = ","

Comma character (to avoid repetition).

Const EMPTY

EMPTY: "" = ""

Empty string.

Const FAIL

FAIL: string = ...

Fail message with colors.

Const INDENT

INDENT: " " = " "

Indent for string output (used by object and array output).

Const PASS

PASS: string = ...

Pass message with colors.

Const UNWANTED_COMMENT

UNWANTED_COMMENT: string = ...

Unwanted comment (// Unwanted in red text).

Functions

Const arrayFlat1

arrayFlat1<Item>(source: readonly Item[]): (Item extends readonly InnerArr[] ? InnerArr : Item)[]

- Defined in utils/arrayFlat1.ts:6
Return array with 1 level flatted.

Type parameters
- Item
Parameters
- source: readonly Item[]
Returns (Item extends readonly InnerArr[] ? InnerArr : Item)[]

Const comment

comment(formatter: (source: string) => string): (title: string) => (value: undefined | string) => string

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

Parameters
- formatter: (source: string) => string
  
  Color/style formatter for the text.
  - - (source: string): string
    - Parameters
      - source: string
      Returns string
Returns (title: string) => (value: undefined | string) => string
- - (title: string): (value: undefined | string) => string
  - Parameters
    - title: string
    Returns (value: undefined | string) => string
    - - (value: undefined | string): string
      - Parameters
        
        value: undefined | string
        
        Returns string

Const compare

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

- Defined in compare/compare.ts:12
Compare two values and show the differences in different ways.

Type parameters
- Wanted
  
  The wanted value type.
Parameters
- wanted: Wanted
  
  Wanted value.
Returns (received: Wanted) => string
- - (received: Wanted): string
  - Parameters
    - received: Wanted
    Returns string

Const compareArrayMatchingItems

compareArrayMatchingItems(lastParent: boolean): <Item>(source: readonly Item[]) => string[]

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

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

Const compareArrayMissingItems

compareArrayMissingItems<Item>(source: readonly Item[]): string

- Defined in compare/compareArrayMissingItems.ts:11
Takes a source array and returns a string for missing items.

Type parameters
- Item
  
  Type of the items in the arrays being compared.
Parameters
- source: readonly Item[]
  
  Source array of missing items.
Returns string

Const compareArrayUnwantedItems

compareArrayUnwantedItems(lastParent: boolean): (source: readonly unknown[]) => string[]

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

Parameters
- lastParent: boolean
  
  Last item of the parent.
Returns (source: readonly unknown[]) => string[]
- - (source: readonly unknown[]): string[]
  - Parameters
    - source: readonly unknown[]
    Returns string[]

Const compareArrays

compareArrays<Wanted>(wanted: readonly Wanted[]): (received: readonly Wanted[]) => string

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

Type parameters
- Wanted
  
  The wanted value type.
Parameters
- wanted: readonly Wanted[]
  
  Wanted array.
Returns (received: readonly Wanted[]) => string
- - (received: readonly Wanted[]): string
  - Parameters
    - received: readonly Wanted[]
    Returns string

Const compareObjects

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

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

Type parameters
- Wanted: Record<string, unknown>
  
  The wanted value type.
Parameters
- wanted: Wanted
  
  Wanted object.
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:11
Compares two primitive values.

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

Const everyIsTestResult

everyIsTestResult(source: readonly unknown[]): source is readonly TestResult[]

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

Parameters
- source: readonly unknown[]
Returns source is readonly TestResult[]

Const indentMap

indentMap(source: readonly string[]): string[]

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

Parameters
- source: readonly string[]
Returns string[]

Const isPassedTestResult

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

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

Type parameters
- Actual
  
  The actual type of the value.
Parameters
- value: TestResult | Actual
Returns boolean

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
  
  Value to check.
Returns value is SuiteResult

Const isTestResult

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

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

Type parameters
- Actual
  
  The actual type of the value.
Parameters
- value: TestResult | Actual
  
  Value to check.
Returns value is TestResult

Const joinComma

joinComma<Item>(source: readonly Item[]): string

- Defined in utils/joinComma.ts:6
Join array with a comma followed by a space.

Type parameters
- Item
Parameters
- source: readonly Item[]
Returns string

Const joinNewLine

joinNewLine<Item>(source: readonly Item[]): string

- Defined in utils/joinNewLine.ts:6
Join array with new lines.

Type parameters
- Item
Parameters
- source: readonly Item[]
Returns string

Const lastAwareMap

lastAwareMap<Item, Output>(mapper: (last: boolean) => (item: Item) => Output): (source: readonly 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
  
  Type of the items in the array.
- Output
  
  Output type after mapping.
Parameters
- mapper: (last: boolean) => (item: Item) => Output
  
  Mapping function with last boolean argument.
  - - (last: boolean): (item: Item) => Output
    - Parameters
      - last: boolean
      Returns (item: Item) => Output
      - (item: Item): Output
        
        Parameters
        
        item: Item
        
        Returns Output
Returns (source: readonly Item[]) => Output[]
- - (source: readonly Item[]): Output[]
  - Parameters
    - source: readonly Item[]
    Returns Output[]

Const missingComment

missingComment(value: undefined | string): string

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

Parameters
- value: undefined | string
Returns string

Const promiseWrap

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

- Defined in utils/promiseWrap.ts:10
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>
  
  Value or Promise value.
Returns Promise<Value>

Promise of that value.

Const promiseWrapMap

promiseWrapMap<Value>(source: readonly MaybePromise<Value>[]): Promise<Value>[]

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

Type parameters
- Value
Parameters
- source: readonly MaybePromise<Value>[]
Returns Promise<Value>[]

Const stringify

stringify<Source>(source: Source): string

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

Type parameters
- Source
  
  Type of the Source value to be transformed into string.
Parameters
- source: Source
  
  Source value to be stringified.
Returns string

Const stringifyMap

stringifyMap<Source>(source: readonly Source[]): string[]

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

Type parameters
- Source
Parameters
- source: readonly Source[]
Returns string[]

Const suite

suite<Value>(tests: readonly Test<Value>[]): (name: string) => Promise<SuiteResult>

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

Type parameters
- Value
  
  The value being checked in the test.
Parameters
- tests: readonly Test<Value>[]
  
  List of test descriptions.
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:9
Import a file that exports a suite.

Parameters
- path: string
  
  File path to load from.
Returns Promise<SuiteResult>

Const suiteResultToString

suiteResultToString(__namedParameters: SuiteResult): string

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

Parameters
- __namedParameters: SuiteResult
Returns string

Const suiteResultToStringMap

suiteResultToStringMap(suites: readonly SuiteResult[]): string

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

Parameters
- suites: readonly SuiteResult[]
Returns string

Const suitesImport

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

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

Parameters
- paths: readonly string[]
  
  Array of file paths.
Returns Promise<SuiteResult[]>

Const test

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

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

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

Const testMap

testMap<Value>(source: readonly Test<Value>[]): Promise<TestResult>[]

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

Type parameters
- Value
Parameters
- source: readonly Test<Value>[]
Returns Promise<TestResult>[]

Const testName

testName(__namedParameters: TestResult): string

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

Parameters
- __namedParameters: TestResult
Returns string

Const testResultToString

testResultToString(testResult: TestResult): string

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

Parameters
- testResult: TestResult
  
  TestResult to generate the string from.
Returns string

Const testResultToStringMap

testResultToStringMap(source: readonly TestResult[]): string[]

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

Parameters
- source: readonly TestResult[]
Returns string[]

Const testResultsFilterTuple

testResultsFilterTuple(source: readonly TestResult[]): FilterTuple<TestResult, TestResult>

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

Parameters
- source: readonly TestResult[]
Returns FilterTuple<TestResult, TestResult>

Const wantedComment

wantedComment(value: undefined | string): string

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

Parameters
- value: undefined | string
Returns string

Generated using TypeDoc

Usage

Documentation

Changelog

Test coverage

Index

Type aliases

Variables

Functions

Type aliases

MaybePromise

Type parameters

Value

SuiteImport

SuiteResult

Type declaration

Readonly failed: ReadonlyArray<TestResult>

Readonly name: string

Readonly passed: ReadonlyArray<TestResult>

Test

Type parameters

Value

Type declaration

Readonly given: string

Readonly must: string

Readonly received: MaybePromise<Value>

Readonly wanted: MaybePromise<Value>

TestResult

Variables

Const COMMA

Const EMPTY

Const FAIL

Const INDENT

Const PASS

Const UNWANTED_COMMENT

Functions

Const arrayFlat1

Type parameters

Item

Parameters

source: readonly Item[]

Returns (Item extends readonly InnerArr[] ? InnerArr : Item)[]

Const comment

Parameters

formatter: (source: string) => string

Parameters

source: string

Returns string

Returns (title: string) => (value: undefined | string) => string

Parameters

title: string

Returns (value: undefined | string) => string

Parameters

value: undefined | string

Returns string

Const compare

Type parameters

Wanted

Parameters

wanted: Wanted

Returns (received: Wanted) => string

Parameters

received: Wanted

Returns string

Const compareArrayMatchingItems

Parameters

lastParent: boolean

Returns <Item>(source: readonly Item[]) => string[]

Type parameters

Item

Parameters

source: readonly Item[]

Returns string[]

Const compareArrayMissingItems

Type parameters

Item

Parameters

source: readonly Item[]

Returns string

Const compareArrayUnwantedItems

Parameters