@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>: Value | Promise<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: readonly TestResult[]; name: string; passed: readonly TestResult[] }

Output object given by a suite.

Type declaration

Readonly failed: readonly TestResult[]

Array of failed tests.
Readonly name: string

Name of the test suite.
Readonly passed: readonly 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?: undefined | string }

Output of the test function.

Variables

Const COMMA

COMMA: "," = ","

Comma character (to avoid repetition).

Const EMPTY

EMPTY: "" = ""

Empty string.

Const FAIL

FAIL: string = mix([whiteText, redBackground])("[FAIL]")

Fail message with colors.

Const INDENT

INDENT: " " = " "

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

Const PASS

PASS: string = mix([whiteText, greenBackground])("[PASS]")

Pass message with colors.

Const UNWANTED_COMMENT

UNWANTED_COMMENT: string = comment(redText)("Unwanted")(undefined)

Unwanted comment (// Unwanted in red text).

Const arrayFlat1

arrayFlat1: <Item>(source: readonly Item[]) => FlatArray<readonly Item[], Depth>[] = arrayFlat(1)

Return array with 1 level flatted.

Type declaration

- <Item>(source: readonly Item[]): FlatArray<readonly Item[], Depth>[]
- Type parameters
  - Item
  Parameters
  - source: readonly Item[]
  Returns FlatArray<readonly Item[], Depth>[]

Const everyIsTestResult

everyIsTestResult: (source: readonly Item[]) => source is readonly Predicated[] = arrayEvery(isTestResult)

Check if all the items in an array are TestResults.

Type declaration

- (source: readonly Item[]): source is readonly Predicated[]
- Parameters
  - source: readonly Item[]
  Returns source is readonly Predicated[]

Const indentMap

indentMap: (source: readonly Item[]) => Output[] = arrayMap((item: string) => `${INDENT}${item}`)

Maps trough and array of strings and add indent to each item.

Type declaration

- (source: readonly Item[]): Output[]
- Parameters
  - source: readonly Item[]
  Returns Output[]

Const joinComma

joinComma: <Item>(source: readonly Item[]) => string = arrayJoin(", ")

Join array with a comma followed by a space.

Type declaration

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

Const joinNewLine

joinNewLine: <Item>(source: readonly Item[]) => string = arrayJoin("\n")

Join array with new lines.

Type declaration

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

Const missingComment

missingComment: (Anonymous function) = comment(grayText)("Missing")

Comment for missing items.

Const promiseWrapMap

promiseWrapMap: Object = arrayMap(promiseWrap)

Maps using promiseWrap.

Const stringifyMap

stringifyMap: Object = arrayMap(stringify)

Applies stringify to every value in the given array.

Const testMap

testMap: Object = arrayMap(test)

Map given array of tests.

Const testResultToStringMap

testResultToStringMap: (source: readonly Item[]) => Output[] = arrayMap(testResultToString)

Takes an array of TestResult and returns an array of strings.

Type declaration

- (source: readonly Item[]): Output[]
- Parameters
  - source: readonly Item[]
  Returns Output[]

Const testResultsFilterTuple

testResultsFilterTuple: (source: readonly Item[]) => FilterTuple<Item, Filtered> = arrayFilterTuple<TestResult, TestResult>(isPassedTestResult)

Filter tests results in a tuple [passed, failed].

Type declaration

- (source: readonly Item[]): FilterTuple<Item, Filtered>
- Parameters
  - source: readonly Item[]
  Returns FilterTuple<Item, Filtered>

Const wantedComment

wantedComment: (Anonymous function) = comment(redText)("Wanted")

Comment for wanted items.

Functions

Const comment

comment(formatter: (source: string) => string): (Anonymous function)

- Defined in src/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 (Anonymous function)

Const compare

compare<Wanted>(wanted: Wanted): (Anonymous function)

- Defined in src/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 (Anonymous function)

Const compareArrayMatchingItems

compareArrayMatchingItems(lastParent: boolean): (Anonymous function)

- Defined in src/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 (Anonymous function)

Const compareArrayMissingItems

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

- Defined in src/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): (Anonymous function)

- Defined in src/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 (Anonymous function)

Const compareArrays

compareArrays<Wanted>(wanted: readonly Wanted[]): (Anonymous function)

- Defined in src/compare/compareArrays.ts:17
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 (Anonymous function)

Const compareObjects

compareObjects<Wanted>(wanted: Wanted): (Anonymous function)

- Defined in src/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 (Anonymous function)

Const comparePrimitives

comparePrimitives<Wanted>(wanted: Wanted): (Anonymous function)

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

Type parameters
- Wanted
  
  The wanted value type.
Parameters
- wanted: Wanted
  
  Wanted value.
Returns (Anonymous function)

Const isPassedTestResult

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

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

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

Const isSuiteResult

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

- Defined in src/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: Actual | TestResult): value is TestResult

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

Type parameters
- Actual
Parameters
- value: Actual | TestResult
  
  Value to check.
Returns value is TestResult

Const lastAwareMap

lastAwareMap<Item, Output>(mapper: (last: boolean) => (item: Item) => Output): (Anonymous function)

- Defined in src/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 (Anonymous function)

Const promiseWrap

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

- Defined in src/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 stringify

stringify<Source>(source: Source): string

- Defined in src/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 suite

suite<Value>(tests: readonly Test<Value>[]): (Anonymous function)

- Defined in src/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 (Anonymous function)

Const suiteImport

suiteImport(path: string): Promise<SuiteResult>

- Defined in src/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: { failed: ReadonlyArray<TestResult>; name: string }): string

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

Parameters
- __namedParameters: { failed: ReadonlyArray<TestResult>; name: string }
  - failed: ReadonlyArray<TestResult>
  - name: string
Returns string

Const suiteResultToStringMap

suiteResultToStringMap(suites: readonly SuiteResult[]): string

- Defined in src/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 src/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: { given: string; must: string; received: MaybePromise<Value>; wanted: MaybePromise<Value> }): Promise<TestResult>

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

Type parameters
- Value
  
  Value being tested.
Parameters
- __namedParameters: { given: string; must: string; received: MaybePromise<Value>; wanted: MaybePromise<Value> }
  - given: string
  - must: string
  - received: MaybePromise<Value>
  - wanted: MaybePromise<Value>
Returns Promise<TestResult>

Const testName

testName(__namedParameters: { error: undefined | string; given: string; must: string }): string

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

Parameters
- __namedParameters: { error: undefined | string; given: string; must: string }
  - error: undefined | string
  - given: string
  - must: string
Returns string

Const testResultToString

testResultToString(testResult: TestResult): string

- Defined in src/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

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: readonly TestResult[]

Readonly name: string

Readonly passed: readonly 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

Const arrayFlat1

Type declaration

Type parameters

Item

Parameters

source: readonly Item[]

Returns FlatArray<readonly Item[], Depth>[]

Const everyIsTestResult

Type declaration

Parameters

source: readonly Item[]

Returns source is readonly Predicated[]

Const indentMap

Type declaration

Parameters

source: readonly Item[]

Returns Output[]

Const joinComma

Type declaration

Type parameters

Item

Parameters

source: readonly Item[]

Returns string

Const joinNewLine

Type declaration

Type parameters

Item

Parameters

source: readonly Item[]

Returns string

Const missingComment

Const promiseWrapMap

Const stringifyMap

Const testMap

Const testResultToStringMap

Type declaration

Parameters

source: readonly Item[]

Returns Output[]

Const testResultsFilterTuple

Type declaration

Parameters

source: readonly Item[]

Returns FilterTuple<Item, Filtered>

Const wantedComment