Options
All
  • Public
  • Public/Protected
  • All
Menu

@vangware/test

Index

File System Type aliases

ReadOnlyDirent: Readonly<Dirent>

Read-only {@link Dirent}.

ReadOnlyURL: Readonly<URL>

Read-only {@link URL}.

ReadOnlyURLs: ReadOnlyArray<ReadOnlyURL>

Array of ReadOnlyURL.

TestsImport: Promise<ReadOnlyRecord<Test | Tests>>

Promise import of a file containing Test or Tests.

Test Type aliases

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<Value>: ReadOnlyArray<Difference<Value>>

Array of Difference.

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

Type parameters

  • Value = unknown

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<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<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: Promise<ReadOnlyRecord<Test | Tests>>

Promise import of a file containing Test or Tests.

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

FAIL: string = ...

Fail message with colors.

PASS: string = ...

Pass message with colors.

TEST: string = ...

Test message to be shown next to the test path.

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

Dictionary type->formatter to be used by formatValue.

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

Dictionary Difference kind->formatter.

File System Functions

  • 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(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(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.

  • 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(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(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(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(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<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<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<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(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.

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