@khanacademy/wonder-blocks-testing 10.1.0 → 11.0.0

package/src/harness/adapters/router.tsx

@@ -1,205 +0,0 @@
-import * as React from "react";
-
-import {StaticRouter, MemoryRouter, Route, Switch} 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 = // The initial location to use.
-
-        | 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 const defaultConfig = {location: "/"} as const;
-
-const maybeWithRoute = (
-    children: React.ReactNode,
-    path?: string | null,
-): React.ReactElement => {
-    if (path == null) {
-        return <>{children}</>;
-    }
-
-    return (
-        <Switch>
-            <Route exact={true} path={path}>
-                {children}
-            </Route>
-            <Route
-                path="*"
-                render={() => {
-                    throw new Error(
-                        "The configured path must match the configured location or your harnessed component will not render.",
-                    );
-                }}
-            />
-        </Switch>
-    );
-};
-
-/**
- * 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 const adapter: TestHarnessAdapter<Config> = (
-    children: React.ReactNode,
-    config: Config,
-): React.ReactElement<any> => {
-    if (typeof config === "string") {
-        config = {
-            location: config,
-        };
-    }
-
-    // Wrap children with the various contexts and routes, as per the config.
-    const wrappedWithRoute = maybeWithRoute(children, config.path);
-    if ("forceStatic" in config && config.forceStatic) {
-        /**
-         * There may be times (SSR testing comes to mind) where we will be
-         * really strict about not permitting client-side navigation events.
-         */
-        return (
-            <StaticRouter location={config.location} context={{}}>
-                {wrappedWithRoute}
-            </StaticRouter>
-        );
-    }
-
-    /**
-     * OK, we must be OK with a memory router.
-     *
-     * There are two flavors of config for this. The easy one with just a
-     * location, and the complex one for those gnarlier setups.
-     *
-     * First, the easy one.
-     */
-    if ("location" in config && config.location !== undefined) {
-        return (
-            <MemoryRouter initialEntries={[config.location]}>
-                {wrappedWithRoute}
-            </MemoryRouter>
-        );
-    }
-
-    /**
-     * If it's not the easy one, it should be the complex one.
-     * Let's make sure we have good data (also keeps TypeScript happy).
-     */
-    if (!("initialEntries" in config) || config.initialEntries === undefined) {
-        throw new Error(
-            "A location or initial history entries must be provided.",
-        );
-    }
-
-    /**
-     * What should happen if no entries were in the array?
-     * It likely uses the root one anyway, but a consistent API is what
-     * we want, so let's ensure we always have our default location at least.
-     */
-    const entries =
-        config.initialEntries.length === 0
-            ? [defaultConfig.location]
-            : config.initialEntries;
-
-    // Memory router doesn't allow us to pass maybe types in its TypeScript types.
-    // So let's build props then spread them.
-    const routerProps: MemoryRouterProps = {
-        initialEntries: entries,
-    };
-    if (config.initialIndex != null) {
-        routerProps.initialIndex = config.initialIndex;
-    }
-    if (config.getUserConfirmation != null) {
-        routerProps.getUserConfirmation = config.getUserConfirmation;
-    }
-
-    return <MemoryRouter {...routerProps}>{wrappedWithRoute}</MemoryRouter>;
-};

package/src/harness/get-named-adapter-component.tsx

@@ -1,36 +0,0 @@
-import * as React from "react";
-
-import type {TestHarnessAdapter} from "./types";
-
-type Props<TConfig = any> = {
-    children: React.ReactNode;
-    config: TConfig;
-    adapter: TestHarnessAdapter<TConfig>;
-};
-
-const componentCache = new Map<string, React.FunctionComponent<Props>>();
-
-/**
- * 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 const getNamedAdapterComponent = (name: string) => {
-    // If we already have this component, just return it.
-    const existing = componentCache.get(name);
-    if (existing != null) {
-        return existing;
-    }
-
-    // Otherwise, create a new component, name it, cache it, and return it.
-    const newComponent: React.FunctionComponent<Props> = ({
-        children,
-        config,
-        adapter,
-    }: any) => adapter(children, config);
-    newComponent.displayName = `Adapter(${name})`;
-    componentCache.set(name, newComponent);
-    return newComponent;
-};

package/src/harness/hook-harness.ts

@@ -1,22 +0,0 @@
-import * as React from "react";
-
-import {makeHookHarness} from "./make-hook-harness";
-import {DefaultAdapters, DefaultConfigs} 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 const hookHarness: (
-    configs?: Partial<TestHarnessConfigs<typeof DefaultAdapters>>,
-) => React.ForwardRefExoticComponent<any> = makeHookHarness(
-    DefaultAdapters,
-    DefaultConfigs,
-);

package/src/harness/make-hook-harness.tsx

@@ -1,40 +0,0 @@
-import * as React from "react";
-
-import {makeTestHarness} from "./make-test-harness";
-
-import type {TestHarnessAdapters, TestHarnessConfigs} from "./types";
-
-const HookHarness = ({
-    children,
-}: React.PropsWithChildren<unknown>): React.ReactElement => <>{children}</>;
-
-/**
- * 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 const makeHookHarness = <TAdapters extends TestHarnessAdapters>(
-    adapters: TAdapters,
-    defaultConfigs: TestHarnessConfigs<TAdapters>,
-): ((
-    configs?: Partial<TestHarnessConfigs<TAdapters>>,
-) => React.ForwardRefExoticComponent<any>) => {
-    const testHarness = makeTestHarness<TAdapters>(adapters, defaultConfigs);
-    /**
-     * Create a harness to use as a wrapper when rendering hooks.
-     *
-     * @param {$Shape<Configs<typeof DefaultAdapters>>} [configs] Any adapter
-     * configuration that you want to override from the DefaultConfigs values.
-     */
-    return (configs?: Partial<TestHarnessConfigs<TAdapters>>) =>
-        testHarness<any>(HookHarness, configs);
-};

package/src/harness/make-test-harness.tsx

@@ -1,60 +0,0 @@
-import * as React from "react";
-
-import {Adapt} from "./adapt";
-
-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 const makeTestHarness = <TAdapters extends TestHarnessAdapters>(
-    adapters: TAdapters,
-    defaultConfigs: TestHarnessConfigs<TAdapters>,
-): (<TProps extends object>(
-    Component: React.ComponentType<TProps>,
-    configs?: Partial<TestHarnessConfigs<TAdapters>>,
-) => React.ForwardRefExoticComponent<
-    React.PropsWithoutRef<TProps> & React.RefAttributes<unknown>
->) => {
-    /**
-     * Create a harnessed version of the given component.
-     *
-     * @param {React.ComponentType<TProps>} component The
-     * component to be wrapped.
-     * @param {Partial<TestHarnessConfigs<TAdapters>>} [configs] Any adapter
-     * configuration that you want to override from the `defaultConfigs` values.
-     */
-    return <TProps extends object>(
-        Component: React.ComponentType<TProps>,
-        configs?: Partial<TestHarnessConfigs<TAdapters>>,
-    ): React.ForwardRefExoticComponent<
-        React.PropsWithoutRef<TProps> & React.RefAttributes<unknown>
-    > => {
-        const fullConfig: TestHarnessConfigs<TAdapters> = {
-            ...defaultConfigs,
-            ...configs,
-        };
-        const harnessedComponent = React.forwardRef((props: TProps, ref) => (
-            <Adapt adapters={adapters} configs={fullConfig}>
-                <Component {...(props as TProps)} ref={ref} />
-            </Adapt>
-        ));
-
-        // We add a name for the component here so that we can detect that
-        // later and also see it in traces and what have you.
-        harnessedComponent.displayName = `testHarness(${
-            Component.displayName || Component.name || "Component"
-        })`;
-
-        return harnessedComponent;
-    };
-};

package/src/harness/test-harness.ts

@@ -1,13 +0,0 @@
-import {makeTestHarness} from "./make-test-harness";
-import {DefaultAdapters, DefaultConfigs} from "./adapters/adapters";
-
-/**
- * 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 const testHarness = makeTestHarness(DefaultAdapters, DefaultConfigs);

package/src/harness/types.ts

@@ -1,47 +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/src/mock-requester.ts

@@ -1,68 +0,0 @@
-import type {MockResponse} from "./respond-with";
-import type {OperationMock, OperationMatcher, MockFn} from "./types";
-
-/**
- * A generic mock request function for using when mocking fetch or gqlFetch.
- */
-export const mockRequester = <TOperationType>(
-    operationMatcher: OperationMatcher<any>,
-    operationToString: (...args: Array<any>) => string,
-): MockFn<TOperationType> => {
-    // We want this to work in jest and in fixtures to make life easy for folks.
-    // This is the array of mocked operations that we will traverse and
-    // manipulate.
-    const mocks: Array<OperationMock<any>> = [];
-
-    // What we return has to be a drop in replacement for the mocked function
-    // which is how folks will then use this mock.
-    const mockFn: MockFn<TOperationType> = (
-        ...args: Array<any>
-    ): Promise<Response> => {
-        // Iterate our mocked operations and find the first one that matches.
-        for (const mock of mocks) {
-            if (mock.onceOnly && mock.used) {
-                // This is a once-only mock and it has been used, so skip it.
-                continue;
-            }
-            if (operationMatcher(mock.operation, ...args)) {
-                mock.used = true;
-                return mock.response();
-            }
-        }
-
-        // Default is to reject with some helpful info on what request
-        // we rejected.
-        const operation = operationToString(...args);
-        return Promise.reject(
-            new Error(`No matching mock response found for request:
-    ${operation}`),
-        );
-    };
-
-    const addMockedOperation = <TOperation>(
-        operation: TOperation,
-        response: MockResponse<any>,
-        onceOnly: boolean,
-    ): MockFn<TOperationType> => {
-        const mockResponse = () => response.toPromise();
-        mocks.push({
-            operation,
-            response: mockResponse,
-            onceOnly,
-            used: false,
-        });
-        return mockFn;
-    };
-
-    mockFn.mockOperation = <TOperation>(
-        operation: TOperation,
-        response: MockResponse<any>,
-    ): MockFn<TOperationType> => addMockedOperation(operation, response, false);
-
-    mockFn.mockOperationOnce = <TOperation>(
-        operation: TOperation,
-        response: MockResponse<any>,
-    ): MockFn<TOperationType> => addMockedOperation(operation, response, true);
-
-    return mockFn;
-};