@khanacademy/wonder-blocks-testing 10.1.0 → 11.0.0

package/dist/harness/adapters/adapters.d.ts

@@ -1,36 +0,0 @@
-/// <reference path="../../../types/aphrodite.d.ts" />
-import type { TestHarnessConfigs } from "../types";
-/**
- * NOTE: We do not type `DefaultAdapters` with `Adapters` here because we want
- * the individual config types of each adapter to remain intact rather than
- * getting changed to `any`.
- */
-/**
- * The default adapters provided by Wonder Blocks.
- */
-export declare const DefaultAdapters: {
-    readonly css: import("../types").TestHarnessAdapter<string | string[] | import("aphrodite").CSSProperties | {
-        classes: string[];
-        style: import("aphrodite").CSSProperties;
-    }>;
-    readonly data: import("../types").TestHarnessAdapter<((requestId: string) => Promise<import("@khanacademy/wonder-blocks-data").ValidCacheData> | null | undefined) | ((requestId: string) => Promise<import("@khanacademy/wonder-blocks-data").ValidCacheData> | null | undefined)[]>;
-    readonly portal: import("../types").TestHarnessAdapter<string>;
-    readonly router: import("../types").TestHarnessAdapter<string | Readonly<{
-        initialEntries: import("history").LocationDescriptor<unknown>[] | undefined;
-        initialIndex?: number | undefined;
-        getUserConfirmation?: ((message: string, callback: (ok: boolean) => void) => void) | undefined;
-        path?: string | undefined;
-    } | {
-        location: import("history").LocationDescriptor<unknown>;
-        forceStatic: true;
-        path?: string | undefined;
-    } | {
-        location: import("history").LocationDescriptor<unknown>;
-        path?: string | undefined;
-    }>>;
-    readonly ssr: import("../types").TestHarnessAdapter<true>;
-};
-/**
- * The default configurations to use with the `DefaultAdapters`.
- */
-export declare const DefaultConfigs: TestHarnessConfigs<typeof DefaultAdapters>;

package/dist/harness/adapters/css.d.ts

@@ -1,12 +0,0 @@
-import type { CSSProperties } from "aphrodite";
-import type { TestHarnessAdapter } from "../types";
-type Config = string | Array<string> | CSSProperties | {
-    classes: Array<string>;
-    style: CSSProperties;
-};
-export declare const defaultConfig: Config | null | undefined;
-/**
- * Test harness adapter for adding CSS to the harnessed component wrapper.
- */
-export declare const adapter: TestHarnessAdapter<Config>;
-export {};

package/dist/harness/adapters/portal.d.ts

@@ -1,12 +0,0 @@
-import type { TestHarnessAdapter } from "../types";
-type Config = string;
-export declare const defaultConfig: Config | null | undefined;
-/**
- * Test harness adapter for supporting portals.
- *
- * Some components rely on rendering with a React Portal. This adapter ensures
- * that the DOM contains a mounting point for the portal with the expected
- * identifier.
- */
-export declare const adapter: TestHarnessAdapter<Config>;
-export {};

package/dist/harness/adapters/router.d.ts

@@ -1,94 +0,0 @@
-import * as React from "react";
-import { MemoryRouter } from "react-router-dom";
-import type { LocationDescriptor } from "history";
-import type { TestHarnessAdapter } from "../types";
-type MemoryRouterProps = JSX.LibraryManagedAttributes<typeof MemoryRouter, React.ComponentProps<typeof MemoryRouter>>;
-/**
- * Configuration for the withLocation test harness adapter.
- */
-type Config = Readonly<{
-    /**
-     * See MemoryRouter prop for initialEntries.
-     */
-    initialEntries: MemoryRouterProps["initialEntries"];
-    /**
-     * See MemoryRouter prop for initialIndex.
-     */
-    initialIndex?: MemoryRouterProps["initialIndex"];
-    /**
-     * See MemoryRouter prop for getUserConfirmation.
-     */
-    getUserConfirmation?: MemoryRouterProps["getUserConfirmation"];
-    /**
-     * A path match to use.
-     *
-     * When this is specified, the harnessed component will be
-     * rendered inside a `Route` handler with this path.
-     *
-     * If the path matches the location, then the route will
-     * render the component.
-     *
-     * If the path does not match the location, then the route
-     * will not render the component.
-     */
-    path?: string;
-} | {
-    /**
-     * The location to use.
-     */
-    location: LocationDescriptor;
-    /**
-     * Force the use of a StaticRouter, instead of MemoryRouter.
-     */
-    forceStatic: true;
-    /**
-     * A path match to use.
-     *
-     * When this is specified, the harnessed component will be
-     * rendered inside a `Route` handler with this path.
-     *
-     * If the path matches the location, then the route will
-     * render the component.
-     *
-     * If the path does not match the location, then the route
-     * will not render the component.
-     */
-    path?: string;
-} | {
-    /**
-     * The initial location to use.
-     */
-    location: LocationDescriptor;
-    /**
-     * A path match to use.
-     *
-     * When this is specified, the harnessed component will be
-     * rendered inside a `Route` handler with this path.
-     *
-     * If the path matches the location, then the route will
-     * render the component.
-     *
-     * If the path does not match the location, then the route
-     * will not render the component.
-     */
-    path?: string;
-}> | string;
-/**
- * The default configuration for this adapter.
- */
-export declare const defaultConfig: {
-    readonly location: "/";
-};
-/**
- * Adapter that sets up a router and AppShell location-specific contexts.
- *
- * This allows you to ensure that components are being tested in the
- * AppShell world.
- *
- * NOTE(somewhatabstract): The AppShell component itself already does
- * the work of setting up routing and the AppShellContext and so using this
- * adapter with the App component will have zero-effect since AppShell will
- * override it.
- */
-export declare const adapter: TestHarnessAdapter<Config>;
-export {};

package/dist/harness/get-named-adapter-component.d.ts

@@ -1,16 +0,0 @@
-import * as React from "react";
-import type { TestHarnessAdapter } from "./types";
-type Props<TConfig = any> = {
-    children: React.ReactNode;
-    config: TConfig;
-    adapter: TestHarnessAdapter<TConfig>;
-};
-/**
- * Get a component tagged with the given name for rendering an adapter.
- *
- * We can share these across invocations because only the name is used.
- * The rest is configured at render time. This way we don't recreate new
- * components on the fly and cause remounting to occur.
- */
-export declare const getNamedAdapterComponent: (name: string) => React.FunctionComponent<Props<any>>;
-export {};

package/dist/harness/hook-harness.d.ts

@@ -1,13 +0,0 @@
-import * as React from "react";
-import { DefaultAdapters } from "./adapters/adapters";
-import type { TestHarnessConfigs } from "./types";
-/**
- * Create test wrapper for hook testing with Wonder Blocks default adapters.
- *
- * This is primarily useful for tests within Wonder Blocks.
- *
- * If you want to expand the range of adapters or change the default
- * configurations, use `makeHookHarness` to create a new `hookHarness`
- * function.
- */
-export declare const hookHarness: (configs?: Partial<TestHarnessConfigs<typeof DefaultAdapters>>) => React.ForwardRefExoticComponent<any>;

package/dist/harness/make-hook-harness.d.ts

@@ -1,17 +0,0 @@
-import * as React from "react";
-import type { TestHarnessAdapters, TestHarnessConfigs } from "./types";
-/**
- * Create a test harness method for use with React hooks.
- *
- * This returns a test harness method that applies the default configurations
- * to the given adapters, wrapping a given component.
- *
- * @param {TAdapters} adapters All the adapters to be supported by the returned
- * test harness.
- * @param {TestHarnessConfigs<TAdapters>} defaultConfigs Default configuration values for
- * the adapters.
- * @returns {(
- *     configs?: $Shape<TestHarnessConfigs<TAdapters>>,
- * ) => React.AbstractComponent<any, any>} A test harness.
- */
-export declare const makeHookHarness: <TAdapters extends TestHarnessAdapters>(adapters: TAdapters, defaultConfigs: TestHarnessConfigs<TAdapters>) => (configs?: Partial<TestHarnessConfigs<TAdapters>> | undefined) => React.ForwardRefExoticComponent<any>;

package/dist/harness/make-test-harness.d.ts

@@ -1,15 +0,0 @@
-import * as React from "react";
-import type { TestHarnessAdapters, TestHarnessConfigs } from "./types";
-/**
- * Create a test harness method for use with React components.
- *
- * This returns a test harness method that applies the default configurations
- * to the given adapters, wrapping a given component.
- *
- * @param {TAdapters} adapters All the adapters to be supported by the returned
- * test harness.
- * @param {Configs<TAdapters>} defaultConfigs Default configuration values for
- * the adapters.
- * @returns A test harness.
- */
-export declare const makeTestHarness: <TAdapters extends TestHarnessAdapters>(adapters: TAdapters, defaultConfigs: TestHarnessConfigs<TAdapters>) => <TProps extends object>(Component: React.ComponentType<TProps>, configs?: Partial<TestHarnessConfigs<TAdapters>> | undefined) => React.ForwardRefExoticComponent<React.PropsWithoutRef<TProps> & React.RefAttributes<unknown>>;

package/dist/harness/test-harness.d.ts

@@ -1,33 +0,0 @@
-/// <reference path="../../types/aphrodite.d.ts" />
-/// <reference types="react" />
-/**
- * Wrap a component with a test harness using Wonder Blocks default adapters.
- *
- * This is primarily useful for tests within Wonder Blocks.
- *
- * If you want to expand the range of adapters or change the default
- * configurations, use `makeTestHarness` to create a new `testHarness`
- * function.
- */
-export declare const testHarness: <TProps extends object>(Component: import("react").ComponentType<TProps>, configs?: Partial<import("./types").TestHarnessConfigs<{
-    readonly css: import("./types").TestHarnessAdapter<string | string[] | import("aphrodite").CSSProperties | {
-        classes: string[];
-        style: import("aphrodite").CSSProperties;
-    }>;
-    readonly data: import("./types").TestHarnessAdapter<((requestId: string) => Promise<import("@khanacademy/wonder-blocks-data").ValidCacheData> | null | undefined) | ((requestId: string) => Promise<import("@khanacademy/wonder-blocks-data").ValidCacheData> | null | undefined)[]>;
-    readonly portal: import("./types").TestHarnessAdapter<string>;
-    readonly router: import("./types").TestHarnessAdapter<string | Readonly<{
-        initialEntries: import("history").LocationDescriptor<unknown>[] | undefined;
-        initialIndex?: number | undefined;
-        getUserConfirmation?: ((message: string, callback: (ok: boolean) => void) => void) | undefined;
-        path?: string | undefined;
-    } | {
-        location: import("history").LocationDescriptor<unknown>;
-        forceStatic: true;
-        path?: string | undefined;
-    } | {
-        location: import("history").LocationDescriptor<unknown>;
-        path?: string | undefined;
-    }>>;
-    readonly ssr: import("./types").TestHarnessAdapter<true>;
-}>> | undefined) => import("react").ForwardRefExoticComponent<import("react").PropsWithoutRef<TProps> & import("react").RefAttributes<unknown>>;

package/dist/harness/types.d.ts

@@ -1,36 +0,0 @@
-import * as React from "react";
-/**
- * A adapter to be composed with our test harness infrastructure.
- */
-export type TestHarnessAdapter<TConfig> = (children: React.ReactNode, config: TConfig) => React.ReactElement;
-/**
- * A general map of adapters by their identifiers.
- *
- * It's OK that this has `any` for the config type as this is the very base
- * version of a adapter set. In reality, a more specific type will be used
- * with the harness functions that use more specific definitions of known
- * adapters. This is just to support the base reality of not knowing.
- *
- * Use this on input positions only. Output positions for adapters
- * should infer their type in most cases to ensure the strongest typing of
- * the adapters.
- */
-export type TestHarnessAdapters = {
-    readonly [adapterID: string]: TestHarnessAdapter<any>;
-};
-/**
- * Type for easily defining an adapter's config type.
- */
-export type TestHarnessConfig<TAdapter> = TAdapter extends TestHarnessAdapter<infer TConfig> ? TConfig : never;
-/**
- * The `TestHarnessConfigs` type as defined by parsing a given set of adapters.
- *
- * NOTE: This only works if the properties of the passed `TAdapters` type
- * are explicitly typed as `TestHarnessAdapter<TConfig>` so if passing in a
- * non-Adapters type (which we should be, to get strong `TConfig` types instead
- * of `any`), then that object should make sure that each adapter is strongly
- * marked as `TestHarnessAdapter<TConfig>`
- */
-export type TestHarnessConfigs<TAdapters extends TestHarnessAdapters> = {
-    [K in keyof TAdapters]: TestHarnessConfig<TAdapters[K]> | null | undefined;
-};

package/dist/mock-requester.d.ts

@@ -1,5 +0,0 @@
-import type { OperationMatcher, MockFn } from "./types";
-/**
- * A generic mock request function for using when mocking fetch or gqlFetch.
- */
-export declare const mockRequester: <TOperationType>(operationMatcher: OperationMatcher<any>, operationToString: (...args: Array<any>) => string) => MockFn<TOperationType>;

package/dist/respond-with.d.ts

@@ -1,75 +0,0 @@
-import { SettleSignal } from "./settle-signal";
-import type { GraphQLJson } from "./types";
-/**
- * This symbol is used so we can create an opaque type, using a custom field
- * that cannot be directly referenced since folks won't have access to the
- * symbol.
- *
- * See https://stackoverflow.com/a/56749647/23234
- */
-declare const opaque: unique symbol;
-/**
- * Describes a mock response to a fetch request.
- */
-export type MockResponse<TData> = {
-    /**
-     * This is used to enforce the use of the TData type parameter. We won't
-     * actually attach anything to this field. Doing this makes sure that
-     * TData is relevant to the response. Without it, it will get ignored
-     * and a value of type MockResponse<string> will be considered the same
-     * type as a value of type MockResponse<number> (or any other type
-     * constraint).
-     */
-    [opaque]: TData;
-    /**
-     * Create a promise from the mocked response.
-     *
-     * If a signal was provided when the mock response was created, the promise
-     * will only settle to resolution or rejection if the signal is raised.
-     */
-    readonly toPromise: () => Promise<Response>;
-};
-/**
- * Helpers to define mock responses for mocked requests.
- */
-export declare const RespondWith: Readonly<{
-    /**
-     * Response with text body and status code.
-     * Status code defaults to 200.
-     */
-    text: <TData = string>(text: string, statusCode?: number, signal?: SettleSignal | null) => MockResponse<TData>;
-    /**
-     * Response with JSON body and status code 200.
-     */
-    json: <TJson extends Record<any, any>>(json: TJson, signal?: SettleSignal | null) => MockResponse<TJson>;
-    /**
-     * Response with GraphQL data JSON body and status code 200.
-     */
-    graphQLData: <TData_1 extends Record<any, any>>(data: TData_1, signal?: SettleSignal | null) => MockResponse<GraphQLJson<TData_1>>;
-    /**
-     * Response with body that will not parse as JSON and status code 200.
-     */
-    unparseableBody: (signal?: SettleSignal | null) => MockResponse<any>;
-    /**
-     * Rejects with an AbortError to simulate an aborted request.
-     */
-    abortedRequest: (signal?: SettleSignal | null) => MockResponse<any>;
-    /**
-     * Rejects with the given error.
-     */
-    reject: (error: Error, signal?: SettleSignal | null) => MockResponse<any>;
-    /**
-     * A non-200 status code with empty text body.
-     * Equivalent to calling `ResponseWith.text("", statusCode)`.
-     */
-    errorStatusCode: (statusCode: number, signal?: SettleSignal | null) => MockResponse<any>;
-    /**
-     * Response body that is valid JSON but not a valid GraphQL response.
-     */
-    nonGraphQLBody: (signal?: SettleSignal | null) => MockResponse<any>;
-    /**
-     * Response that is a GraphQL errors response with status code 200.
-     */
-    graphQLErrors: (errorMessages: ReadonlyArray<string>, signal?: SettleSignal | null) => MockResponse<GraphQLJson<any>>;
-}>;
-export {};

package/dist/response-impl.d.ts

@@ -1 +0,0 @@
-export declare const ResponseImpl: typeof Response;

package/dist/settle-controller.d.ts

@@ -1,19 +0,0 @@
-import { SettleSignal } from "./settle-signal";
-/**
- * A controller for the `RespondWith` API to control response settlement.
- */
-export declare class SettleController {
-    private _settleFn;
-    private _signal;
-    constructor();
-    /**
-     * The signal to pass to the `RespondWith` API.
-     */
-    get signal(): SettleSignal;
-    /**
-     * Settle the signal and therefore any associated responses.
-     *
-     * @throws {Error} if the signal has already been settled.
-     */
-    settle(): void;
-}

package/dist/settle-signal.d.ts

@@ -1,18 +0,0 @@
-/**
- * A signal for controlling the `RespondWith` API responses.
- *
- * This provide finely-grained control over the promise lifecycle to support
- * complex test scenarios.
- */
-export declare class SettleSignal extends EventTarget {
-    private _settled;
-    constructor(setSettleFn?: ((settleFn: () => void) => unknown) | null);
-    /**
-     * An already settled signal.
-     */
-    static settle(): SettleSignal;
-    /**
-     * Has this signal been settled yet?
-     */
-    get settled(): boolean;
-}

package/dist/types.d.ts

@@ -1,25 +0,0 @@
-import type { MockResponse } from "./respond-with";
-/**
- * A valid GraphQL response as supported by our mocking framework.
- * Note that we don't currently support both data and errors being set.
- */
-export type GraphQLJson<TData extends Record<any, any>> = {
-    data: TData;
-} | {
-    errors: Array<{
-        message: string;
-    }>;
-};
-export type MockFn<TOperationType> = {
-    (...args: Array<any>): Promise<Response>;
-    mockOperation: MockOperationFn<TOperationType>;
-    mockOperationOnce: MockOperationFn<TOperationType>;
-};
-export type OperationMock<TOperation> = {
-    operation: TOperation;
-    onceOnly: boolean;
-    used: boolean;
-    response: () => Promise<Response>;
-};
-export type OperationMatcher<TOperation> = (operation: TOperation, ...args: Array<any>) => boolean;
-export type MockOperationFn<TOperationType> = <TOperation extends TOperationType>(operation: TOperation, response: MockResponse<any>) => MockFn<TOperationType>;

package/src/__tests__/mock-requester.test.ts

@@ -1,212 +0,0 @@
-import {RespondWith} from "../respond-with";
-import {mockRequester} from "../mock-requester";
-
-describe("#mockRequester", () => {
-    it("should return a function", () => {
-        // Arrange
-
-        // Act
-        const result = mockRequester(jest.fn(), jest.fn());
-
-        // Assert
-        expect(result).toBeInstanceOf(Function);
-    });
-
-    it("should provide mockOperation API", () => {
-        // Arrange
-
-        // Act
-        const result = mockRequester(jest.fn(), jest.fn());
-
-        // Assert
-        expect(result).toHaveProperty("mockOperation", expect.any(Function));
-    });
-
-    it("should provide mockOperationOnce API", () => {
-        // Arrange
-
-        // Act
-        const result = mockRequester(jest.fn(), jest.fn());
-
-        // Assert
-        expect(result).toHaveProperty(
-            "mockOperationOnce",
-            expect.any(Function),
-        );
-    });
-
-    it("should throw with helpful details formatted by operationToString if no matching mock is found", async () => {
-        // Arrange
-        const mockFn = mockRequester(
-            jest.fn(),
-            (...args: any) => `TEST FORMATTING: ${JSON.stringify(args)}`,
-        );
-
-        // Act
-        const underTest = mockFn("any", "arguments", {we: {want: 42}});
-
-        // Assert
-        await expect(underTest).rejects.toThrowErrorMatchingInlineSnapshot(`
-            "No matching mock response found for request:
-                TEST FORMATTING: ["any","arguments",{"we":{"want":42}}]"
-        `);
-    });
-
-    describe("mockOperation", () => {
-        it("should invoke matcher with mock for a request", async () => {
-            // Arrange
-            const matcher = jest.fn().mockReturnValue(true);
-            const operationToString = jest.fn();
-            const mockFn = mockRequester(matcher, operationToString);
-
-            // Act
-            mockFn.mockOperation(
-                "THE MOCK DESCRIPTION",
-                RespondWith.text("TADA!"),
-            );
-            await mockFn("any", "arguments", {we: {want: 42}});
-
-            // Assert
-            expect(matcher).toHaveBeenCalledWith(
-                "THE MOCK DESCRIPTION",
-                "any",
-                "arguments",
-                {
-                    we: {want: 42},
-                },
-            );
-        });
-
-        it("should return mocked operation response if matcher returns true", async () => {
-            // Arrange
-            const matcher = jest.fn().mockReturnValue(true);
-            const operationToString = jest.fn();
-            const mockFn = mockRequester(matcher, operationToString);
-
-            // Act
-            mockFn.mockOperation(
-                "THE MOCK DESCRIPTION",
-                RespondWith.text("TADA!"),
-            );
-            const response = await mockFn("DO SOMETHING");
-            const result = response.text();
-
-            // Assert
-            await expect(result).resolves.toBe("TADA!");
-        });
-
-        it("should skip mock if matcher returns false and try more mocks", async () => {
-            // Arrange
-            const matcher = jest
-                .fn()
-                .mockReturnValueOnce(false)
-                .mockReturnValueOnce(true);
-            const operationToString = jest.fn();
-            const mockFn = mockRequester(matcher, operationToString);
-
-            // Act
-            mockFn.mockOperation(
-                "THE MOCK DESCRIPTION 1",
-                RespondWith.text("ONE"),
-            );
-            mockFn.mockOperation(
-                "THE MOCK DESCRIPTION 2",
-                RespondWith.text("TWO"),
-            );
-            const response = await mockFn("DO SOMETHING");
-            const result = response.text();
-
-            // Assert
-            await expect(result).resolves.toBe("TWO");
-        });
-    });
-
-    describe("mockOperationOnce", () => {
-        it("should invoke matcher with mock for a request", async () => {
-            // Arrange
-            const matcher = jest.fn().mockReturnValue(true);
-            const operationToString = jest.fn();
-            const mockFn = mockRequester(matcher, operationToString);
-
-            // Act
-            mockFn.mockOperationOnce(
-                "THE MOCK DESCRIPTION",
-                RespondWith.text("TADA!"),
-            );
-            await mockFn("any", "arguments", {we: {want: 42}});
-
-            // Assert
-            expect(matcher).toHaveBeenCalledWith(
-                "THE MOCK DESCRIPTION",
-                "any",
-                "arguments",
-                {
-                    we: {want: 42},
-                },
-            );
-        });
-
-        it("should match once", async () => {
-            // Arrange
-            const matcher = jest.fn().mockReturnValue(true);
-            const operationToString = jest.fn();
-            const mockFn = mockRequester(matcher, operationToString);
-
-            // Act
-            mockFn.mockOperationOnce(
-                "THE MOCK DESCRIPTION",
-                RespondWith.text("TADA!"),
-            );
-            const response = await mockFn("DO SOMETHING");
-            const result = response.text();
-
-            // Assert
-            await expect(result).resolves.toBe("TADA!");
-        });
-
-        it("should only match once", async () => {
-            // Arrange
-            const matcher = jest.fn().mockReturnValue(true);
-            const operationToString = jest.fn();
-            const mockFn = mockRequester(matcher, operationToString);
-
-            // Act
-            mockFn.mockOperationOnce(
-                "THE MOCK DESCRIPTION",
-                RespondWith.text("TADA!"),
-            );
-            const result = Promise.all([
-                mockFn("DO SOMETHING"),
-                mockFn("DO SOMETHING"),
-            ]);
-
-            // Assert
-            await expect(result).rejects.toThrowError();
-        });
-
-        it("should skip mock if matcher returns false and try more mocks", async () => {
-            // Arrange
-            const matcher = jest
-                .fn()
-                .mockReturnValueOnce(false)
-                .mockReturnValueOnce(true);
-            const operationToString = jest.fn();
-            const mockFn = mockRequester(matcher, operationToString);
-
-            // Act
-            mockFn.mockOperationOnce(
-                "THE MOCK DESCRIPTION 1",
-                RespondWith.text("ONE"),
-            );
-            mockFn.mockOperationOnce(
-                "THE MOCK DESCRIPTION 2",
-                RespondWith.text("TWO"),
-            );
-            const response = await mockFn("DO SOMETHING");
-            const result = response.text();
-
-            // Assert
-            await expect(result).resolves.toBe("TWO");
-        });
-    });
-});