Options
All
  • Public
  • Public/Protected
  • All
Menu

@vangware/test

Index

Type aliases File System

Type aliases Test

Variables Output

Functions File System

Functions Output

Functions Test

File System Type aliases

ReadOnlyDirent

ReadOnlyDirent: Readonly<Dirent>

Read-only {@link Dirent}.

ReadOnlyURL

ReadOnlyURL: Readonly<URL>

Read-only {@link URL}.

ReadOnlyURLs

ReadOnlyURLs: ReadOnlyArray<ReadOnlyURL>

Array of ReadOnlyURL.

TestsImport

TestsImport: Promise<ReadOnlyRecord<Test | Tests>>

Promise import of a file containing Test or Tests.

Test Type aliases

Difference

Difference<Value>: { error?: unknown; index?: number; item?: Difference<Value>; kind: "A" | "D" | "E" | "N" | "X"; lhs?: Value; path?: ReadOnlyArray<string>; rhs?: Value }

Difference object from deep-diff, with some customizations on top.

example
const difference: Difference<string> = {
    kind: "E",
    path: ["🟢", "🟩"],
    lhs: "🟢",
    rhs: "🟩",
};

Type parameters

  • Value = unknown

Type declaration

  • Optional Readonly error?: unknown

    Only has a value when kind is X.

  • Optional Readonly index?: number

    Indicates the array index where the change occurred (kind A).

  • Optional Readonly item?: Difference<Value>

    Contains a nested change record indicating the change that occurred at the array index (kind A).

  • Readonly kind: "A" | "D" | "E" | "N" | "X"

    Indicates the kind of change.

  • Optional Readonly lhs?: Value

    The value on the left-hand-side of the comparison (undefined for kind N).

  • Optional Readonly path?: ReadOnlyArray<string>

    The property path.

  • Optional Readonly rhs?: Value

    The value on the right-hand-side of the comparison (undefined for kind D).

Differences

Differences<Value>: ReadOnlyArray<Difference<Value>>

Array of Difference.

example
const differences: Differences<string> = [
    {
        kind: "E",
        path: ["🟢", "🟩"],
        lhs: "🟢",
        rhs: "🟩",
    }
];

Type parameters

  • Value = unknown

Test

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

Object that describes a test.

example
const test: Test<number> = {
    given: "a number",
    must: "make it double",
    received: double(2),
    wanted: 4,
};

Type parameters

  • Value = unknown

Type declaration

  • Readonly given: string

    Description of the given value.

  • Readonly must: string

    Description of the wanted value.

  • Readonly received: MaybePromise<Value>

    Value being tested.

  • Readonly wanted: MaybePromise<Value>

    Expected value.

TestResult

TestResult<Value>: Pick<Test, "given" | "must"> & { differences?: Differences<Value> }

Object that describes a test result (given, must and differences).

example
const testResult: TestResult<string> = {
    given: "🟢",
    must: "🟩",
    differences: [
        {
            kind: "E",
            path: ["🟢", "🟩"],
            lhs: "🟢",
            rhs: "🟩",
        }
    ],
};

Type parameters

  • Value = unknown

Tests

Tests<Value>: ReadOnlyArray<Test<Value>>

Array of Test.

example
const tests: Tests<number> = [
    {
        given: "a number",
        must: "make it double",
        received: double(2),
        wanted: 4,
    }
];

Type parameters

  • Value = unknown

TestsImport

TestsImport: Promise<ReadOnlyRecord<Test | Tests>>

Promise import of a file containing Test or Tests.

TestsRecord

TestsRecord: ReadOnlyRecord<Tests, string>

Object that maps path->Tests.

example
const testsRecord: TestsRecord = {
    "file:///tests/example.test.ts": [
        {
            given: "a number",
            must: "make it double",
            received: double(2),
            wanted: 4,
        }
    ]
};

Output Variables

Const FAIL

FAIL: string = ...

Fail message with colors.

Const PASS

PASS: string = ...

Pass message with colors.

Const TEST

TEST: string = ...

Test message to be shown next to the test path.

Const formatValueDictionary

formatValueDictionary: Record<TypeOfValue, (value: unknown) => string> = ...

Dictionary type->formatter to be used by formatValue.

Const stringifyDifferenceDictionary

stringifyDifferenceDictionary: ReadOnlyRecord<(difference: Difference) => string, Difference["kind"]> = ...

Dictionary Difference kind->formatter.

File System Functions

getFilePaths

  • getFilePaths(directory: Readonly<URL>): Promise<ReadOnlyURLs>

  • Recursively search for files in the given directory and filters them based on given filterer function.

    example
    getFiles("./tests/"); // ["./tests/vangware.test.ts"]

    Parameters

    • directory: Readonly<URL>

      Directory to get files from.

    Returns Promise<ReadOnlyURLs>

    Array of files in given directory that match filterer.

isTestFilePath

  • isTestFilePath(input: Readonly<URL>): input is Readonly<URL>

  • Checks if given path is a test file (ends with .test.ext).

    example
    isTestFile(new URL("file:///tests/vangware.test.ts")); // true
    isTestFile(new URL("file:///tests/vangware.ts")); // false

    Parameters

    • input: Readonly<URL>

    Returns input is Readonly<URL>

    true if given path ends with .test.ext, false otherwise.

testImport

  • testImport(path: Readonly<URL>): Promise<Test<unknown>[]>

  • Import a file that exports a Test or an array of Test.

    example
    testImport(new URL("file:///example/test.js"));
    // Promise<[
    // 	{ given: "example", must: "example", received: "value", wanted: "value" },
    // 	{ given: "example", must: "example", received: "value", wanted: "value" },
    // ]>

    Parameters

    • path: Readonly<URL>

      Path to the test file.

    Returns Promise<Test<unknown>[]>

    A promise with an array of Test and the path.

testsImport

  • Imports all the tests of the given array of paths and returns a TestsRecord.

    example
    suiteImport([
        "file:///example/test-1.js",
        "file:///example/test-2.js",
    ]);
    // Promise<{
    // 	"file:///example/test-1.js": [
    // 		{ given: "example", must: "example", received: "value", wanted: "value" },
    // 	},
    // 	"file:///example/test-2.js": [
    // 		{ given: "example", must: "example", received: "value", wanted: "value" },
    // 	],
    // }>

    Parameters

    Returns Promise<Readonly<Record<string, Tests<unknown>>>>

    A TestsRecord object with the tests.

Output Functions

formatPropertyPath

  • formatPropertyPath(propertyPath: ReadOnlyArray<string>): string

  • Stringifies and colorizes an array representing a property path.

    example
    formatPropertyPath(["foo", "bar"]); // "foo.bar" (with colors)
    formatPropertyPath([]); // "it"

    Parameters

    • propertyPath: ReadOnlyArray<string>

      Path to format.

    Returns string

    String with formatted path.

formatValue

  • formatValue(value: unknown): string

  • Colorizes and formats a value based on its type.

    example
    formatValue(1); // "1" (with colors)
    formatValue(BigInt(1)); // "1n" (with colors)
    formatValue([]); // "Array([])" (with colors)
    formatValue({}); // "Object({})" (with colors)

    Parameters

    • value: unknown

      Value to colorize.

    Returns string

    Colorized value as a string.

relativePath

  • relativePath(path: string | Readonly<URL>): string

  • Given a path, replace the CWD with a "." to make it relative.

    example
    // If CWD is `"/projects"`
    relativePath("/projects/tests/"); // "./tests/"

    Parameters

    • path: string | Readonly<URL>

      Path to make relative.

    Returns string

    Relative path.

runAndStringifyTests

  • runAndStringifyTests(testsRecord: Readonly<Record<string, Tests<unknown>>>): Promise<void>

  • Run tests in given TestsRecord and return a string with the results.

    example
    runAndStringifyTests({
        "file:///tests/example.test.ts": [
            {
                given: "🟢",
                must: "🟩",
                received: "🟩",
                wanted: "🟩",
            },
        ],
    });
    // "[TEST] file:///tests/example.test.ts
    // [PASS] Given 🟢, must 🟩."

    Parameters

    • testsRecord: Readonly<Record<string, Tests<unknown>>>

      Object with paths and array of tests.

    Returns Promise<void>

    Promise with a readable strings of the test results.

stringifyDifference

  • stringifyDifference<Value>(difference: Difference<Value>): string

  • Takes a Difference object and returns a string using stringifyDifferenceDictionary.

    example
    stringifyDifference({
        kind: "D",
        lhs: "🟢",
        path: ["🟢", "🟩"],
    }); // "🟢.🟩 is missing."

    stringifyDifference({
        kind: "X",
        error: "❌",
    }); // "there was an uncaught error: ❌."

    Type parameters

    • Value

    Parameters

    Returns string

    Formatted string.

stringifyTest

  • stringifyTest<Value>(testResult: TestResult<Value>): string

  • Takes a TestResult and returns a readable string..

    example
    stringifyTest({
        given: "🟢",
        must: "🟩",
    }); // "[PASS] Given 🟢, must 🟩."
    stringifyTest({
        differences: [...],
        given: "🟢",
        must: "🟩",
    }); // "[FAIL] Given 🟢, must 🟩, but..."

    Type parameters

    • Value

    Parameters

    • testResult: TestResult<Value>

      Test result object.

    Returns string

    Readable string.

Test Functions

isTest

  • isTest<Actual>(value: Actual | Test<unknown>): value is Test<unknown>

  • Check if given value is a Test.

    example
    isTest({ given: "🟢", must: "🟩", received: "🟩", wanted: "🟩" }); // true
    isTest({ given: 1, must: 2, received: 3, wanted: 4 }); // false
    isTest(); // false

    Type parameters

    • Actual = unknown

    Parameters

    • value: Actual | Test<unknown>

      Value to check.

    Returns value is Test<unknown>

    true if is a Test, false otherwise.

runAndStringifyTests

  • runAndStringifyTests(testsRecord: Readonly<Record<string, Tests<unknown>>>): Promise<void>

  • Run tests in given TestsRecord and return a string with the results.

    example
    runAndStringifyTests({
        "file:///tests/example.test.ts": [
            {
                given: "🟢",
                must: "🟩",
                received: "🟩",
                wanted: "🟩",
            },
        ],
    });
    // "[TEST] file:///tests/example.test.ts
    // [PASS] Given 🟢, must 🟩."

    Parameters

    • testsRecord: Readonly<Record<string, Tests<unknown>>>

      Object with paths and array of tests.

    Returns Promise<void>

    Promise with a readable strings of the test results.

test

  • Takes a Test object and returns a promise with a TestResult.

    example
    test({
        given: "🟢",
        must: "🟩",
        received: "🟩",
        wanted: "🟩",
    }); // Promise<{ given: "🟢", , must: "🟩" }>
    test({
        given: "🟢",
        must: "🟩",
        received: "❌",
        wanted: "🟩",
    }); // Promise<{ differences: [...], given: "🟢", , must: "🟩" }>

    Type parameters

    • Value

    Parameters

    Returns Promise<TestResult<Value>>

    A promise with a TestResult object.