@khanacademy/wonder-blocks-testing 4.0.4 → 5.0.0

package/src/harness/adapters/__tests__/router.test.js

@@ -0,0 +1,233 @@
+// @flow
+import * as React from "react";
+import {withRouter, Prompt} from "react-router-dom";
+import {render} from "@testing-library/react";
+import * as Router from "../router.js";
+
+describe("Router.adapter", () => {
+    it("should throw if the config does not match any expecations", () => {
+        // Arrange
+        const badConfig: any = {
+            bad: "config",
+        };
+
+        // Act
+        const underTest = () => Router.adapter("CHILDREN", badConfig);
+
+        // Assert
+        expect(underTest).toThrowErrorMatchingInlineSnapshot(
+            `"A location or initial history entries must be provided."`,
+        );
+    });
+
+    describe.each`
+        type          | config
+        ${"string"}   | ${"/math"}
+        ${"location"} | ${{location: "/math"}}
+        ${"full"}     | ${{initialEntries: ["/math"]}}
+    `("with $type config", ({config}) => {
+        it("should allow navigation", () => {
+            // Arrange
+            const historyListen = jest.fn();
+            const HistoryListener = withRouter(({history}): React.Node => {
+                React.useEffect(() => history.listen(historyListen), [history]);
+                if (history.location.pathname === "/math") {
+                    history.push("/math/calculator");
+                }
+                return null;
+            });
+
+            // Act
+            render(Router.adapter(<HistoryListener />, config));
+
+            // Assert
+            expect(historyListen).not.toHaveBeenCalled();
+        });
+
+        it("should have default route match of root /", () => {
+            // Arrange
+            const matchCatcherFn = jest.fn();
+            const MatchCatcher = withRouter(({match, history}): React.Node => {
+                React.useEffect(() => {
+                    if (history.location.pathname === "/math") {
+                        history.push("/math/calculator");
+                    }
+                    matchCatcherFn(match);
+                }, [match, history]);
+                return null;
+            });
+
+            // Act
+            render(Router.adapter(<MatchCatcher />, config));
+
+            // Assert
+            expect(matchCatcherFn).toHaveBeenLastCalledWith(
+                expect.objectContaining({
+                    path: "/",
+                    url: "/",
+                }),
+            );
+        });
+    });
+
+    describe.each`
+        type          | config
+        ${"location"} | ${{location: "/math/calculator", path: "/math/*"}}
+        ${"full"}     | ${{initialEntries: ["/math/calculator"], path: "/math/*"}}
+    `("with $type config including path", ({config}) => {
+        it("should include routing for the given path", () => {
+            // Arrange
+            const matchCatcherFn = jest.fn();
+            const MatchCatcher = withRouter(({match}): React.Node => {
+                React.useEffect(() => {
+                    matchCatcherFn(match);
+                }, [match]);
+                return null;
+            });
+
+            // Act
+            render(Router.adapter(<MatchCatcher />, config));
+
+            // Assert
+            expect(matchCatcherFn).toHaveBeenLastCalledWith(
+                expect.objectContaining({
+                    isExact: true,
+                    path: "/math/*",
+                    url: "/math/calculator",
+                }),
+            );
+        });
+
+        it("should throw if the path does not match the location", () => {
+            // Arrange
+            // This is going to cause an error to be logged, so let's silence
+            // that.
+            jest.spyOn(console, "error").mockImplementation(() => {});
+            const badConfig = {
+                ...config,
+                path: "/something/else/entirely",
+            };
+
+            // Act
+            const underTest = () =>
+                render(Router.adapter("CHILDREN", badConfig));
+
+            // Assert
+            expect(underTest).toThrowErrorMatchingSnapshot();
+        });
+    });
+
+    describe("with forceStatic", () => {
+        it("should not navigate", () => {
+            // Arrange
+            const historyListen = jest.fn();
+            const HistoryListener = withRouter(({history}): React.Node => {
+                React.useEffect(() => history.listen(historyListen), [history]);
+                if (history.location.pathname === "/math") {
+                    history.push("/math/calculator");
+                }
+                return null;
+            });
+
+            // Act
+            render(
+                Router.adapter(<HistoryListener />, {
+                    location: "/math",
+                    forceStatic: true,
+                }),
+            );
+
+            // Assert
+            expect(historyListen).not.toHaveBeenCalled();
+        });
+    });
+
+    describe("with initialEntries", () => {
+        it("should use the defaultConfig location if initialEntries is empty", () => {
+            // Arrange
+            const matchCatcherFn = jest.fn();
+            const MatchCatcher = withRouter(({match, history}): React.Node => {
+                React.useEffect(() => {
+                    matchCatcherFn(match);
+                }, [match, history]);
+                return null;
+            });
+
+            // Act
+            render(
+                Router.adapter(<MatchCatcher />, {
+                    initialEntries: [],
+                }),
+            );
+
+            // Assert
+            expect(matchCatcherFn).toHaveBeenLastCalledWith(
+                expect.objectContaining({
+                    url: Router.defaultConfig.location,
+                }),
+            );
+        });
+
+        it("should set initialIndex prop on MemoryRouter if given in configuration", () => {
+            // Arrange
+            const matchCatcherFn = jest.fn();
+            const MatchCatcher = withRouter(({match}): React.Node => {
+                React.useEffect(() => {
+                    matchCatcherFn(match);
+                }, [match]);
+                return null;
+            });
+
+            // Act
+            render(
+                Router.adapter(<MatchCatcher />, {
+                    initialEntries: ["/location/old", "/location/current"],
+                    initialIndex: 1,
+                    path: "/location/*",
+                }),
+            );
+
+            // Assert
+            expect(matchCatcherFn).toHaveBeenLastCalledWith(
+                expect.objectContaining({
+                    url: "/location/current",
+                }),
+            );
+        });
+
+        it("should set getUserConfirmation prop on MemoryRouter if given in configuration", () => {
+            // Arrange
+            const getUserConfirmationSpy = jest
+                .fn()
+                .mockImplementation((message, cb) => {
+                    cb(true);
+                });
+            const matchCatcherFn = jest.fn();
+            const MatchCatcher = withRouter(({match, history}): React.Node => {
+                React.useEffect(() => {
+                    if (history.location.pathname === "/location/old") {
+                        // Fire off a location change.
+                        history.goForward();
+                    }
+                    matchCatcherFn(match);
+                }, [match, history]);
+                return <Prompt message="Are you sure?" />;
+            });
+
+            // Act
+            render(
+                Router.adapter(<MatchCatcher />, {
+                    initialEntries: ["/location/old", "/location/current"],
+                    getUserConfirmation: getUserConfirmationSpy,
+                    path: "/location/*",
+                }),
+            );
+
+            // Assert
+            expect(getUserConfirmationSpy).toHaveBeenCalledWith(
+                "Are you sure?",
+                expect.any(Function),
+            );
+        });
+    });
+});

package/src/harness/adapters/adapters.js

@@ -0,0 +1,33 @@
+// @flow
+import * as css from "./css.js";
+import * as data from "./data.js";
+import * as portal from "./portal.js";
+import * as router from "./router.js";
+
+import type {TestHarnessConfigs} from "../types.js";
+
+/**
+ * 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 const DefaultAdapters = {
+    css: css.adapter,
+    data: data.adapter,
+    portal: portal.adapter,
+    router: router.adapter,
+};
+
+/**
+ * The default configurations to use with the `DefaultAdapters`.
+ */
+export const DefaultConfigs: TestHarnessConfigs<typeof DefaultAdapters> = {
+    css: css.defaultConfig,
+    data: data.defaultConfig,
+    portal: portal.defaultConfig,
+    router: router.defaultConfig,
+};

package/src/harness/adapters/css.js

@@ -0,0 +1,65 @@
+// @flow
+import * as React from "react";
+
+import type {CSSProperties} from "aphrodite";
+
+import type {TestHarnessAdapter} from "../types.js";
+
+type Config =
+    | string
+    | Array<string>
+    | CSSProperties
+    | {|
+          classes: Array<string>,
+          style: CSSProperties,
+      |};
+
+// The default configuration is to omit this adapter.
+export const defaultConfig: ?Config = null;
+
+const normalizeConfig = (
+    config: Config,
+): {|classes: Array<string>, style: CSSProperties|} => {
+    if (typeof config === "string") {
+        return {classes: [config], style: ({}: $Shape<CSSProperties>)};
+    }
+
+    if (Array.isArray(config)) {
+        return {classes: config, style: ({}: $Shape<CSSProperties>)};
+    }
+
+    if (typeof config === "object") {
+        if (config.classes != null && config.style != null) {
+            // This is a heuristic check and by nature isn't perfect.
+            // So we have to tell flow to just accept it.
+            // $FlowIgnore[prop-missing]
+            return config;
+        }
+
+        // Again, since the previous check is heuristic, so is this outcome
+        // and so we still have to assure flow everything is OK.
+        // $FlowIgnore[prop-missing]
+        return {classes: [], style: config};
+    }
+
+    throw new Error(`Invalid config: ${config}`);
+};
+
+/**
+ * Test harness adapter for adding CSS to the harnessed component wrapper.
+ */
+export const adapter: TestHarnessAdapter<Config> = (
+    children: React.Node,
+    config: Config,
+): React.Element<any> => {
+    const {classes, style} = normalizeConfig(config);
+    return (
+        <div
+            data-test-id="css-adapter-container"
+            className={classes.join(" ")}
+            style={style}
+        >
+            {children}
+        </div>
+    );
+};

package/src/harness/adapters/data.js

@@ -0,0 +1,46 @@
+// @flow
+import * as React from "react";
+import {InterceptRequests} from "@khanacademy/wonder-blocks-data";
+import type {TestHarnessAdapter} from "../types.js";
+
+type Interceptor = React.ElementConfig<typeof InterceptRequests>["interceptor"];
+
+type Config = Interceptor | Array<Interceptor>;
+
+/**
+ * Default configuration for the Wonder Blocks Data adapter.
+ */
+export const defaultConfig = ([]: Array<Interceptor>);
+
+/**
+ * Test harness adapter to mock Wonder Blocks Data usage.
+ *
+ * NOTE: Consumers are responsible for properly defining their intercepts.
+ * This component does not validate the configuration to ensure interceptors
+ * are not overriding one another.
+ */
+export const adapter: TestHarnessAdapter<Config> = (
+    children: React.Node,
+    config: Config,
+): React.Element<any> => {
+    // First we render the cache intercepts.
+    let currentChildren = children;
+
+    const interceptors = Array.isArray(config) ? config : [config];
+
+    // Then we render the data intercepts.
+    for (const interceptor of interceptors) {
+        currentChildren = (
+            <InterceptRequests interceptor={interceptor}>
+                {currentChildren}
+            </InterceptRequests>
+        );
+    }
+
+    /**
+     * `currentChildren` is a `React.Node` but we need it to be a
+     * `React.Element<>`. Return it rendered in a fragment allows us to do
+     * that.
+     */
+    return <>{currentChildren}</>;
+};

package/src/harness/adapters/portal.js

@@ -0,0 +1,26 @@
+// @flow
+import * as React from "react";
+
+import type {TestHarnessAdapter} from "../types.js";
+
+type Config = string;
+
+// The default configuration is to omit this adapter.
+export const defaultConfig: ?Config = null;
+
+/**
+ * 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 const adapter: TestHarnessAdapter<Config> = (
+    children: React.Node,
+    config: Config,
+): React.Element<any> => (
+    <>
+        <div id={config} data-test-id={config} />
+        {children}
+    </>
+);

package/src/harness/adapters/router.js

@@ -0,0 +1,206 @@
+// @flow
+import * as React from "react";
+
+import {StaticRouter, MemoryRouter, Route, Switch} from "react-router-dom";
+
+import type {LocationShape, Location} from "react-router-dom";
+import type {TestHarnessAdapter} from "../types.js";
+
+type MemoryRouterProps = React.ElementConfig<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: string | Location,
+
+                /**
+                 * 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: string | LocationShape,
+
+                /**
+                 * 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.
+    | string;
+
+/**
+ * The default configuration for this adapter.
+ */
+export const defaultConfig = {location: "/"};
+
+const maybeWithRoute = (children: React.Node, path: ?string): React.Node => {
+    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.Node,
+    config: Config,
+): React.Element<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 (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 (typeof 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 flow happy).
+     */
+    if (typeof 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 flow 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/hook-harness.js

@@ -0,0 +1,23 @@
+// @flow
+import * as React from "react";
+
+import {makeHookHarness} from "./make-hook-harness.js";
+import {DefaultAdapters, DefaultConfigs} from "./adapters/adapters.js";
+
+import type {TestHarnessConfigs} from "./types.js";
+
+/**
+ * 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?: $Shape<TestHarnessConfigs<typeof DefaultAdapters>>,
+) => React.AbstractComponent<any, any> = makeHookHarness(
+    DefaultAdapters,
+    DefaultConfigs,
+);

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

@@ -0,0 +1,39 @@
+// @flow
+import * as React from "react";
+
+import {makeTestHarness} from "./make-test-harness.js";
+
+import type {TestHarnessAdapters, TestHarnessConfigs} from "./types.js";
+
+const HookHarness = ({children}) => 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: TestHarnessAdapters>(
+    adapters: TAdapters,
+    defaultConfigs: TestHarnessConfigs<TAdapters>,
+): ((
+    configs?: $Shape<TestHarnessConfigs<TAdapters>>,
+) => React.AbstractComponent<any, 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?: $Shape<TestHarnessConfigs<TAdapters>>) =>
+        testHarness<any, any>(HookHarness, configs);
+};