@everyonesoftware/common 5.0.0 → 7.0.0

package/outputs/testIndex.d.cts

@@ -0,0 +1,476 @@
+import { f as JavascriptIterable, S as SyncResult, P as PromiseAsyncResult, k as Type, I as Iterable, A as AsyncResult, C as CharacterWriteStream } from './characterWriteStream-ogvZec-U.cjs';
+
+/**
+ * A type that can be used to make assertions during a test.
+ */
+declare abstract class Test {
+    /**
+     * Fail the current test with the provided message.
+     * @param message The message that explains why this test failed.
+     */
+    abstract fail(message: string): never;
+    /**
+     * Assert that the provided value is undefined;
+     * @param value The value to check.
+     */
+    assertUndefined(value: unknown): asserts value is undefined;
+    /**
+     * Assert that the provided value is undefined.
+     * @param test The current {@link Test}.
+     * @param value The value to check.
+     */
+    static assertUndefined(test: Test, value: unknown): asserts value is undefined;
+    /**
+     * Assert that the provided value is not undefined;
+     * @param value The value to check.
+     */
+    assertNotUndefined<T>(value: T): asserts value is NonNullable<T>;
+    /**
+     * Assert that the provided value is not undefined.
+     * @param test The current {@link Test}.
+     * @param value The value to check.
+     */
+    static assertNotUndefined<T>(test: Test, value: unknown): asserts value is NonNullable<T>;
+    /**
+     * Assert that the provided value is null.
+     * @param value The value to check.
+     */
+    assertNull(value: unknown): asserts value is null;
+    /**
+     * Assert that the provided value is null.
+     * @param value The value to check.
+     */
+    static assertNull(test: Test, value: unknown): asserts value is null;
+    /**
+     * Assert that the provided value is not null.
+     * @param value The value to check.
+     */
+    assertNotNull<T>(value: T): asserts value is NonNullable<T>;
+    /**
+     * Assert that the provided value is not null.
+     * @param value The value to check.
+     */
+    static assertNotNull<T>(test: Test, value: T): asserts value is NonNullable<T>;
+    /**
+     * Assert that the provided value is not undefined and not null.
+     * @param value The value to check.
+     */
+    assertNotUndefinedAndNotNull<T>(value: T): asserts value is NonNullable<T>;
+    /**
+     * Assert that the provided value is not undefined and not null.
+     * @param value The value to check.
+     */
+    static assertNotUndefinedAndNotNull<T>(test: Test, value: T): asserts value is NonNullable<T>;
+    /**
+     * Assert that the provided collection is not undefined, not null, and not empty.
+     * @param value The value to check.
+     */
+    assertNotEmpty(value: JavascriptIterable<unknown>): void;
+    static assertNotEmpty(test: Test, value: JavascriptIterable<unknown>): void;
+    /**
+     * Assert that the provided values point to the same object.
+     * @param left The first value.
+     * @param right The second value.
+     */
+    abstract assertSame<T>(left: T, right: T): void;
+    /**
+     * Assert that the provided values don't point to the same object.
+     * @param left The first value.
+     * @param right The second value.
+     */
+    abstract assertNotSame<T>(left: T, right: T): void;
+    /**
+     * Assert that the provided values are equal.
+     * @param left The first value.
+     * @param right The second value.
+     * @param message A message that will be shown when the values are not equal.
+     */
+    abstract assertEqual<T>(left: T, right: T, message?: string): void;
+    /**
+     * Assert that the provided values are not equal.
+     * @param left The first value.
+     * @param right The second value.
+     */
+    abstract assertNotEqual<T>(left: T, right: T): void;
+    /**
+     * Assert that the provided value is false.
+     * @param value The value to check.
+     */
+    assertFalse(value: boolean): asserts value is false;
+    static assertFalse(test: Test, value: boolean): asserts value is false;
+    /**
+     * Assert that the provided value is true.
+     * @param value The value to check.
+     */
+    assertTrue(value: boolean): asserts value is true;
+    /**
+     * Assert that the provided value is true.
+     * @param value The value to check.
+     */
+    static assertTrue(test: Test, value: boolean): asserts value is true;
+    /**
+     * Assert that the provided action throws the provided {@link Error} when it is run.
+     * @param action The action to run.
+     * @param expectedError The optional expected {@link Error} to compare against the thrown
+     * {@link Error}. If the expected {@link Error} is not provided, then any {@link Error} will
+     * satisfy this assertion.
+     */
+    abstract assertThrows(action: SyncResult<unknown> | (() => void), expectedError?: Error): void;
+    /**
+     * Assert that the provided action throws the provided {@link Error} when it is run.
+     * @param action The action to run.
+     * @param expectedError The expected {@link Error}.
+     */
+    abstract assertThrowsAsync(action: PromiseLike<unknown> | (() => PromiseLike<unknown>), expectedError: Error): PromiseAsyncResult<void>;
+    /**
+     * Assert that the provided value is an instance of the provided {@link Type}.
+     * @param value The value to check.
+     * @param type The {@link Type} to check.
+     * @param expression The expression that produced the value.
+     * @param message An optional error message.
+     */
+    assertInstanceOf<T>(value: unknown, type: Type<T>, typeCheck?: (value: unknown) => value is T): asserts value is T;
+    /**
+     * Assert that the provided value is an instance of the provided {@link Type}.
+     * @param value The value to check.
+     * @param type The {@link Type} to check.
+     * @param expression The expression that produced the value.
+     * @param message An optional error message.
+     */
+    static assertInstanceOf<T>(test: Test, value: unknown, type: Type<T>, typeCheck?: (value: unknown) => value is T): asserts value is T;
+}
+
+/**
+ * A {@link Test} type that uses the standard "assert" module to make assertions.
+ */
+declare class AssertTest implements Test {
+    private readonly name;
+    protected constructor(name: string);
+    /**
+     * Create a new {@link AssertTest} object.
+     */
+    static create(name: string): AssertTest;
+    fail(message: string): never;
+    assertUndefined(value: unknown): asserts value is undefined;
+    assertNotUndefined<T>(value: T): asserts value is NonNullable<T>;
+    assertNull(value: unknown): asserts value is null;
+    assertNotNull<T>(value: T): asserts value is NonNullable<T>;
+    assertNotUndefinedAndNotNull<T>(value: T): asserts value is NonNullable<T>;
+    assertNotEmpty(value: JavascriptIterable<unknown>): void;
+    assertSame<T>(left: T, right: T): void;
+    assertNotSame<T>(left: T, right: T): void;
+    assertEqual<T>(left: T, right: T, message?: string): void;
+    assertNotEqual<T>(left: T, right: T): void;
+    assertFalse(value: boolean): void;
+    assertTrue(value: boolean): void;
+    assertThrows(action: SyncResult<unknown> | (() => void), expectedError?: Error): void;
+    assertThrowsAsync(action: Promise<unknown> | (() => Promise<unknown>), expectedError: Error): PromiseAsyncResult<void>;
+    assertInstanceOf<T>(value: unknown, type: Type<T>, typeCheck?: (value: unknown) => value is T): asserts value is T;
+}
+
+/**
+ * A type that is used to mark that a test group or a test should be skipped.
+ */
+declare abstract class TestSkip {
+    protected constructor();
+    /**
+     * Create a new {@link TestSkip} with the provided properties.
+     * @param shouldSkip Whether the tests associated with the new {@link TestSkip}
+     * should be skipped.
+     * @param message The message that explains why the tests associated with this {@link TestSkip}
+     * should be skipped.
+     */
+    static create(shouldSkip?: boolean, message?: string): TestSkip;
+    /**
+     * Get whether the tests associated with this {@link TestSkip} should be skipped.
+     */
+    abstract getShouldSkip(): boolean;
+    /**
+     * Get the message that explains why the tests associated with this {@link TestSkip}
+     * should be skipped.
+     */
+    abstract getMessage(): string;
+}
+
+/**
+ * A type that can be used to run tests.
+ */
+declare abstract class TestRunner {
+    /**
+     * Get a {@link string} that concatenates the {@link string} representation of each
+     * of the provided values into an "and-list".
+     * @param values The values to concatenate.
+     */
+    andList(values: unknown[] | Iterable<unknown>): string;
+    /**
+     * Get a {@link string} that concatenates the {@link string} representation of each
+     * of the provided values into an "and-list".
+     * @param values The values to concatenate.
+     */
+    static andList(runner: TestRunner, values: unknown[] | Iterable<unknown>): string;
+    /**
+     * Get the {@link string} representation of the provided value.
+     * @param value The value to get the {@link string} representation of.
+     */
+    toString(value: unknown): string;
+    /**
+     * Get the {@link string} representation of the provided value.
+     * @param value The value to get the {@link string} representation of.
+     */
+    static toString(_runner: TestRunner, value: unknown): string;
+    skip(message?: string): TestSkip;
+    /**
+     * Create a {@link TestSkip} object that will prevent tests from being run.
+     * @param shouldSkip Whether these tests should be skipped.
+     * @param message The message that explains why the tests are being skipped.
+     */
+    skip(shouldSkip: boolean, message?: string): TestSkip;
+    /**
+     * Create a {@link TestSkip} object that will prevent tests from being run.
+     * @param shouldSkip Whether these tests should be skipped.
+     * @param message The message that explains why the tests are being skipped.
+     */
+    static skip(_runner: TestRunner, shouldSkip?: boolean, message?: string): TestSkip;
+    /**
+     * Create a test group that will test the provided file.
+     * @param fileName The name of the file that is being tested.
+     * @param testAction The action that will run the tests.
+     */
+    abstract testFile(fileName: string, testAction: (() => void) | ((test: Test) => void)): void;
+    /**
+     * Create a test group that will test the provided file.
+     * @param fileName The name of the file that is being tested.
+     * @param skip A value that indicates whether these tests should be skipped.
+     * @param testAction The action that will run the tests.
+     */
+    abstract testFile(fileName: string, skip: TestSkip | undefined, testAction: (() => void) | ((test: Test) => void)): void;
+    /**
+     * Create a test group that will test the provided type.
+     * @param type The {@link Type} or name of the type that is being tested.
+     * @param testAction The action that will run the tests.
+     */
+    abstract testType(typeNameOrType: string | Type<unknown>, testAction: (() => void) | ((test: Test) => void)): void;
+    /**
+     * Create a test group that will test the provided type.
+     * @param type The {@link Type} or name of the type that is being tested.
+     * @param skip A value that indicates whether these tests should be skipped.
+     * @param testAction The action that will run the tests.
+     */
+    abstract testType(typeNameOrType: string | Type<unknown>, skip: TestSkip | undefined, testAction: (() => void) | ((test: Test) => void)): void;
+    /**
+     * Create a test group that will test the provided function.
+     * @param functionSignature The signature of the function that is being tested.
+     * @param testAction The action that will run the tests.
+     */
+    abstract testFunction(functionSignature: string, testAction: (() => void) | ((test: Test) => void)): void;
+    /**
+     * Create a test group that will test the provided function.
+     * @param functionSignature The signature of the function that is being tested.
+     * @param testAction The action that will run the tests.
+     */
+    abstract testFunction(functionSignature: string, skip: TestSkip | undefined, testAction: (() => void) | ((test: Test) => void)): void;
+    /**
+     * Create and run a test group with the provided name.
+     * @param testGroupName The name of the test group to run.
+     * @param testAction The action that runs the test group.
+     */
+    abstract testGroup(testGroupName: string, testAction: () => void): void;
+    /**
+     * Create and run a test group with the provided name.
+     * @param testGroupName The name of the test group to run.
+     * @param testAction The action that runs the test group.
+     */
+    abstract testGroup(testGroupName: string, skip: TestSkip | undefined, testAction: () => void): void;
+    /**
+     * Create and run a test with the provided name.
+     * @param testName The name of the test to run.
+     * @param testAction The action that runs the test.
+     */
+    abstract test(testName: string, testAction: (test: Test) => void): void;
+    /**
+     * Create and run a test with the provided name.
+     * @param testName The name of the test to run.
+     * @param testAction The action that runs the test.
+     */
+    abstract test(testName: string, skip: TestSkip | undefined, testAction: (test: Test) => void): void;
+}
+
+declare function test(runner: TestRunner): void;
+
+/**
+ * A type that is used to mark that a test group or a test should be skipped.
+ */
+declare class BasicTestSkip implements TestSkip {
+    private readonly shouldSkip;
+    private readonly message;
+    private constructor();
+    /**
+     * Create a new {@link TestSkip} with the provided properties.
+     * @param shouldSkip Whether the tests associated with the new {@link TestSkip}
+     * should be skipped.
+     * @param message The message that explains why the tests associated with this {@link TestSkip}
+     * should be skipped.
+     */
+    static create(shouldSkip?: boolean, message?: string): BasicTestSkip;
+    getShouldSkip(): boolean;
+    getMessage(): string;
+}
+
+type TestActionType = "file" | "type" | "function" | "group" | "test";
+declare class TestAction {
+    private readonly parent;
+    private readonly name;
+    private readonly type;
+    private readonly skip;
+    private readonly action;
+    private constructor();
+    static create(parent: TestAction | undefined, name: string, type: TestActionType, skip: TestSkip | undefined, action: () => (void | Promise<void>)): TestAction;
+    getParent(): TestAction | undefined;
+    getName(): string;
+    getFullNameParts(): JavascriptIterable<string>;
+    getFullName(): string;
+    getType(): TestActionType;
+    getSkip(): TestSkip | undefined;
+    shouldSkip(): boolean;
+    getAction(): () => (void | Promise<void>);
+    runAsync(): void | Promise<void>;
+}
+
+declare class FailedTest {
+    private readonly testAction;
+    private readonly error;
+    private constructor();
+    static create(testAction: TestAction, error: unknown): FailedTest;
+    getTestAction(): TestAction;
+    getError(): unknown;
+    getErrorMessage(): string;
+}
+
+declare class SkippedTest {
+    private readonly skip;
+    private readonly testAction;
+    private constructor();
+    static create(skip: TestSkip, testAction: TestAction): SkippedTest;
+    getSkipMessage(): string;
+    getTestAction(): TestAction;
+}
+
+type ConsoleTestRunnerStyle = TestActionType | "passed" | "skipped" | "failed";
+declare abstract class ConsoleTestRunnerUI {
+    private writeStream?;
+    private readonly styles;
+    protected constructor();
+    static flat(): FlatConsoleTestRunnerUI;
+    static tree(): TreeConsoleTestRunnerUI;
+    setWriteStream(writeStream: CharacterWriteStream): this;
+    setStyle(style: ConsoleTestRunnerStyle, styleFunction: (text: string) => string): this;
+    setStyles(styles: Partial<Record<ConsoleTestRunnerStyle, (text: string) => string>>): this;
+    private applyStyle;
+    protected addIndentation(): void;
+    protected removeIndentation(): void;
+    protected indent(action: () => number | void | PromiseLike<number | void>): AsyncResult<number>;
+    protected writeString(text: string): AsyncResult<number>;
+    protected writeLine(text?: string): AsyncResult<number>;
+    protected writeTestActionName(testAction: TestAction): AsyncResult<number>;
+    protected writeFullTestActionName(testAction: TestAction): AsyncResult<number>;
+    beforeTestGroup(testGroup: TestAction): AsyncResult<void>;
+    afterTestGroup(testGroup: TestAction): AsyncResult<void>;
+    beforeTest(testAction: TestAction): AsyncResult<void>;
+    afterPassedTest(testAction: TestAction): AsyncResult<void>;
+    afterSkippedTest(testAction: TestAction, skip: TestSkip): AsyncResult<void>;
+    afterFailedTest(currentTestAction: TestAction, error: unknown): AsyncResult<void>;
+    writeSummary(passedTestCount: number, skippedTests: Iterable<SkippedTest>, failedTests: Iterable<FailedTest>): AsyncResult<void>;
+}
+declare class FlatConsoleTestRunnerUI extends ConsoleTestRunnerUI {
+    protected constructor();
+    static create(): FlatConsoleTestRunnerUI;
+    beforeTest(testAction: TestAction): AsyncResult<void>;
+}
+declare class TreeConsoleTestRunnerUI extends ConsoleTestRunnerUI {
+    private testActions;
+    private testActionWrittenDepth;
+    protected constructor();
+    static create(): TreeConsoleTestRunnerUI;
+    beforeTestGroup(testGroup: TestAction): AsyncResult<void>;
+    afterTestGroup(testGroup: TestAction): AsyncResult<void>;
+    beforeTest(testAction: TestAction): AsyncResult<void>;
+}
+
+type ConsoleTestFunction = (runner: ConsoleTestRunner) => (void | Promise<void>);
+type ConsoleTestFunctionContainer = {
+    test: ConsoleTestFunction;
+};
+declare class ConsoleTestRunner implements TestRunner {
+    private writeStream;
+    private readonly testActions;
+    private testActionInsertIndex;
+    private currentTestAction;
+    private currentTest;
+    private passedTestCount;
+    private readonly skippedTests;
+    private readonly testFailures;
+    private readonly ui;
+    constructor(ui?: ConsoleTestRunnerUI);
+    static create(ui?: ConsoleTestRunnerUI): ConsoleTestRunner;
+    static run(testFunction: ConsoleTestFunction | ConsoleTestFunctionContainer): Promise<void>;
+    static run(testFunctions: JavascriptIterable<ConsoleTestFunction | ConsoleTestFunctionContainer>): Promise<void>;
+    setWriteStream(writeStream: CharacterWriteStream): this;
+    setStyle(style: ConsoleTestRunnerStyle, styleFunction: (text: string) => string): this;
+    setStyles(styles: Partial<Record<ConsoleTestRunnerStyle, (text: string) => string>>): this;
+    /**
+     * Get the number of {@link TestAction}s that have yet to be executed.
+     */
+    getTestActionCount(): number;
+    /**
+     * Get the index in the {@link TestAction} list that new {@link TestAction}s will be
+     * inserted at.
+     */
+    getTestActionInsertIndex(): number;
+    private resetTestActionInsertIndex;
+    private insertTestAction;
+    /**
+     * Get the number of tests that have been skipped.
+     */
+    getSkippedTestCount(): number;
+    getSkippedTests(): Iterable<SkippedTest>;
+    /**
+     * Get the number of tests that have passed.
+     */
+    getPassedTestCount(): number;
+    getFailedTestCount(): number;
+    getFailedTests(): Iterable<FailedTest>;
+    /**
+     * Get the {@link TestAction} that is currently executing or undefined if no {@link TestAction}
+     * is executing.
+     */
+    getCurrentTestAction(): TestAction | undefined;
+    getCurrentTest(): Test | undefined;
+    private assertNoCurrentTest;
+    beforeTestGroup(testAction: TestAction): AsyncResult<void>;
+    afterTestGroup(testAction: TestAction): AsyncResult<void>;
+    beforeTest(testAction: TestAction): AsyncResult<void>;
+    afterPassedTest(testAction: TestAction): AsyncResult<void>;
+    afterSkippedTest(testAction: TestAction, skip: TestSkip): AsyncResult<void>;
+    afterFailedTest(testAction: TestAction, error: unknown): AsyncResult<void>;
+    andList(values: unknown[] | Iterable<unknown>): string;
+    toString(value: unknown): string;
+    skip(message?: string): TestSkip;
+    skip(shouldSkip: boolean, message?: string): TestSkip;
+    testFile(fileName: string, testAction: (() => void) | ((test: Test) => void)): void;
+    testFile(fileName: string, skip: TestSkip | undefined, testAction: (() => void) | ((test: Test) => void)): void;
+    testType(typeNameOrType: string | Type<unknown>, testAction: (() => void) | ((test: Test) => void)): void;
+    testType(typeNameOrType: string | Type<unknown>, skip: TestSkip | undefined, testAction: (() => void) | ((test: Test) => void)): void;
+    testFunction(functionSignature: string, testAction: (() => void) | ((test: Test) => void)): void;
+    testFunction(functionSignature: string, skip: TestSkip | undefined, testAction: (() => void) | ((test: Test) => void)): void;
+    testGroup(testGroupName: string, testAction: () => (void | Promise<void>)): void;
+    testGroup(testGroupName: string, skip: TestSkip | undefined, testAction: () => (void | Promise<void>)): void;
+    test(testName: string, testAction: (test: Test) => (void | Promise<void>)): void;
+    test(testName: string, skip: TestSkip | undefined, testAction: (test: Test) => (void | Promise<void>)): void;
+    private innerTestGroup;
+    private innerTest;
+    private testGroupOrTest;
+    runAsync(): Promise<void>;
+    printSummary(): AsyncResult<void>;
+}
+
+export { AssertTest, BasicTestSkip, type ConsoleTestFunction, type ConsoleTestFunctionContainer, ConsoleTestRunner, FailedTest, SkippedTest, Test, TestAction, type TestActionType, TestRunner, TestSkip, test };