@khanacademy/wonder-blocks-testing 7.1.9 → 7.1.11

package/src/harness/adapters/router.tsx

@@ -0,0 +1,218 @@
+import * as React from "react";
+
+import {StaticRouter, MemoryRouter, Route, Switch} from "react-router-dom";
+
+// @ts-expect-error [FEI-5019] - TS2305 - Module '"react-router-dom"' has no exported member 'LocationShape'. | TS2305 - Module '"react-router-dom"' has no exported member 'Location'.
+import type {LocationShape, Location} from "react-router-dom";
+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: 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;
+                }
+          >
+        | 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) {
+        // @ts-expect-error [FEI-5019] - TS2322 - Type 'ReactNode' is not assignable to type 'ReactElement<any, string | JSXElementConstructor<any>>'.
+        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);
+    // @ts-expect-error [FEI-5019] - TS2339 - Property 'forceStatic' does not exist on type 'Readonly<{ initialEntries: LocationDescriptor<unknown>[] | undefined; initialIndex?: number | undefined; getUserConfirmation?: ((message: string, callback: (ok: boolean) => void) => void) | undefined; path?: string | undefined; } | { ...; } | { ...; }>'.
+    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 (
+            // @ts-expect-error [FEI-5019] - TS2339 - Property 'location' does not exist on type 'Readonly<{ initialEntries: LocationDescriptor<unknown>[] | undefined; initialIndex?: number | undefined; getUserConfirmation?: ((message: string, callback: (ok: boolean) => void) => void) | undefined; path?: string | undefined; } | { ...; } | { ...; }>'.
+            <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.
+     */
+    // @ts-expect-error [FEI-5019] - TS2339 - Property 'location' does not exist on type 'Readonly<{ initialEntries: LocationDescriptor<unknown>[] | undefined; initialIndex?: number | undefined; getUserConfirmation?: ((message: string, callback: (ok: boolean) => void) => void) | undefined; path?: string | undefined; } | { ...; } | { ...; }>'.
+    if (typeof config.location !== "undefined") {
+        return (
+            // @ts-expect-error [FEI-5019] - TS2339 - Property 'location' does not exist on type 'Readonly<{ initialEntries: LocationDescriptor<unknown>[] | undefined; initialIndex?: number | undefined; getUserConfirmation?: ((message: string, callback: (ok: boolean) => void) => void) | undefined; path?: string | undefined; } | { ...; } | { ...; }>'.
+            <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).
+     */
+    // @ts-expect-error [FEI-5019] - TS2339 - Property 'initialEntries' does not exist on type 'Readonly<{ initialEntries: LocationDescriptor<unknown>[] | undefined; initialIndex?: number | undefined; getUserConfirmation?: ((message: string, callback: (ok: boolean) => void) => void) | undefined; path?: string | undefined; } | { ...; } | { ...; }>'.
+    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 =
+        // @ts-expect-error [FEI-5019] - TS2339 - Property 'initialEntries' does not exist on type 'Readonly<{ initialEntries: LocationDescriptor<unknown>[] | undefined; initialIndex?: number | undefined; getUserConfirmation?: ((message: string, callback: (ok: boolean) => void) => void) | undefined; path?: string | undefined; } | { ...; } | { ...; }>'.
+        config.initialEntries.length === 0
+            ? [defaultConfig.location]
+            : // @ts-expect-error [FEI-5019] - TS2339 - Property 'initialEntries' does not exist on type 'Readonly<{ initialEntries: LocationDescriptor<unknown>[] | undefined; initialIndex?: number | undefined; getUserConfirmation?: ((message: string, callback: (ok: boolean) => void) => void) | undefined; path?: string | undefined; } | { ...; } | { ...; }>'.
+              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,
+    };
+    // @ts-expect-error [FEI-5019] - TS2339 - Property 'initialIndex' does not exist on type 'Readonly<{ initialEntries: LocationDescriptor<unknown>[] | undefined; initialIndex?: number | undefined; getUserConfirmation?: ((message: string, callback: (ok: boolean) => void) => void) | undefined; path?: string | undefined; } | { ...; } | { ...; }>'.
+    if (config.initialIndex != null) {
+        // @ts-expect-error [FEI-5019] - TS2339 - Property 'initialIndex' does not exist on type 'Readonly<{ initialEntries: LocationDescriptor<unknown>[] | undefined; initialIndex?: number | undefined; getUserConfirmation?: ((message: string, callback: (ok: boolean) => void) => void) | undefined; path?: string | undefined; } | { ...; } | { ...; }>'.
+        routerProps.initialIndex = config.initialIndex;
+    }
+    // @ts-expect-error [FEI-5019] - TS2339 - Property 'getUserConfirmation' does not exist on type 'Readonly<{ initialEntries: LocationDescriptor<unknown>[] | undefined; initialIndex?: number | undefined; getUserConfirmation?: ((message: string, callback: (ok: boolean) => void) => void) | undefined; path?: string | undefined; } | { ...; } | { ...; }>'.
+    if (config.getUserConfirmation != null) {
+        // @ts-expect-error [FEI-5019] - TS2339 - Property 'getUserConfirmation' does not exist on type 'Readonly<{ initialEntries: LocationDescriptor<unknown>[] | undefined; initialIndex?: number | undefined; getUserConfirmation?: ((message: string, callback: (ok: boolean) => void) => void) | undefined; path?: string | undefined; } | { ...; } | { ...; }>'.
+        routerProps.getUserConfirmation = config.getUserConfirmation;
+    }
+
+    return <MemoryRouter {...routerProps}>{wrappedWithRoute}</MemoryRouter>;
+};

package/src/harness/{hook-harness.js → hook-harness.ts}

@@ -1,10 +1,9 @@
-// @flow
 import * as React from "react";
 
-import {makeHookHarness} from "./make-hook-harness.js";
-import {DefaultAdapters, DefaultConfigs} from "./adapters/adapters.js";
+import {makeHookHarness} from "./make-hook-harness";
+import {DefaultAdapters, DefaultConfigs} from "./adapters/adapters";
 
-import type {TestHarnessConfigs} from "./types.js";
+import type {TestHarnessConfigs} from "./types";
 
 /**
  * Create test wrapper for hook testing with Wonder Blocks default adapters.
@@ -16,8 +15,8 @@ import type {TestHarnessConfigs} from "./types.js";
  * function.
  */
 export const hookHarness: (
-    configs?: $Shape<TestHarnessConfigs<typeof DefaultAdapters>>,
-) => React.AbstractComponent<any, any> = makeHookHarness(
+    configs?: Partial<TestHarnessConfigs<typeof DefaultAdapters>>,
+) => React.ForwardRefExoticComponent<any> = makeHookHarness(
     DefaultAdapters,
     DefaultConfigs,
 );

package/src/harness/{make-hook-harness.js → make-hook-harness.ts}

@@ -1,10 +1,10 @@
-// @flow
 import * as React from "react";
 
-import {makeTestHarness} from "./make-test-harness.js";
+import {makeTestHarness} from "./make-test-harness";
 
-import type {TestHarnessAdapters, TestHarnessConfigs} from "./types.js";
+import type {TestHarnessAdapters, TestHarnessConfigs} from "./types";
 
+// @ts-expect-error [FEI-5019] - TS7031 - Binding element 'children' implicitly has an 'any' type.
 const HookHarness = ({children}) => children;
 
 /**
@@ -21,12 +21,12 @@ const HookHarness = ({children}) => children;
  *     configs?: $Shape<TestHarnessConfigs<TAdapters>>,
  * ) => React.AbstractComponent<any, any>} A test harness.
  */
-export const makeHookHarness = <TAdapters: TestHarnessAdapters>(
+export const makeHookHarness = <TAdapters extends TestHarnessAdapters>(
     adapters: TAdapters,
     defaultConfigs: TestHarnessConfigs<TAdapters>,
 ): ((
-    configs?: $Shape<TestHarnessConfigs<TAdapters>>,
-) => React.AbstractComponent<any, any>) => {
+    configs?: Partial<TestHarnessConfigs<TAdapters>>,
+) => React.ForwardRefExoticComponent<any>) => {
     const testHarness = makeTestHarness<TAdapters>(adapters, defaultConfigs);
     /**
      * Create a harness to use as a wrapper when rendering hooks.
@@ -34,6 +34,6 @@ export const makeHookHarness = <TAdapters: TestHarnessAdapters>(
      * @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);
+    return (configs?: Partial<TestHarnessConfigs<TAdapters>>) =>
+        testHarness<any>(HookHarness, configs);
 };

package/src/harness/{make-test-harness.js → make-test-harness.tsx}

@@ -1,9 +1,8 @@
-// @flow
 import * as React from "react";
 
-import {renderAdapters} from "./render-adapters.js";
+import {renderAdapters} from "./render-adapters";
 
-import type {TestHarnessAdapters, TestHarnessConfigs} from "./types.js";
+import type {TestHarnessAdapters, TestHarnessConfigs} from "./types";
 
 /**
  * Create a test harness method for use with React components.
@@ -20,40 +19,38 @@ import type {TestHarnessAdapters, TestHarnessConfigs} from "./types.js";
  *     configs?: $Shape<Configs<TAdapters>>,
  * ) => React.AbstractComponent<TProps, Instance>} A test harness.
  */
-export const makeTestHarness = <TAdapters: TestHarnessAdapters>(
+export const makeTestHarness = <TAdapters extends TestHarnessAdapters>(
     adapters: TAdapters,
     defaultConfigs: TestHarnessConfigs<TAdapters>,
-): (<-TProps, +Instance = mixed>(
-    Component: React.AbstractComponent<TProps, Instance>,
-    configs?: $Shape<TestHarnessConfigs<TAdapters>>,
-) => React.AbstractComponent<TProps, Instance>) => {
+): (<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.AbstractComponent<TProps, Instance>} component The
+     * @param {React.ComponentType<TProps>} component The
      * component to be wrapped.
-     * @param {$Shape<Configs<TAdapters>>} [configs] Any adapter
+     * @param {Partial<TestHarnessConfigs<TAdapters>>} [configs] Any adapter
      * configuration that you want to override from the `defaultConfigs` values.
      */
-    return <-TProps, +Instance = mixed>(
-        Component: React.AbstractComponent<TProps, Instance>,
-        configs?: $Shape<TestHarnessConfigs<TAdapters>>,
-    ): React.AbstractComponent<TProps, Instance> => {
-        /**
-         * $FlowIgnore[cannot-spread-indexer]
-         * We know `configs` may overwrite `DefaultConfigs` and we're ok with it.
-         * The interface definition handles the typing for us so we're ok
-         * with it not being inferred here.
-         */
+    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, ref) =>
+        const harnessedComponent = React.forwardRef((props: TProps, ref) =>
             renderAdapters<TAdapters>(
                 adapters,
                 fullConfig,
-                <Component {...props} ref={ref} />,
+                <Component {...(props as TProps)} ref={ref} />,
             ),
         );
 

package/src/harness/{render-adapters.js → render-adapters.ts}

@@ -1,16 +1,15 @@
-// @flow
 import * as React from "react";
 
-import type {TestHarnessConfigs, TestHarnessAdapters} from "./types.js";
+import type {TestHarnessConfigs, TestHarnessAdapters} from "./types";
 
 /**
  * Render test adapters around a child component.
  */
-export const renderAdapters = <TAdapters: TestHarnessAdapters>(
+export const renderAdapters = <TAdapters extends TestHarnessAdapters>(
     adapters: TAdapters,
     configs: TestHarnessConfigs<TAdapters>,
-    children: React.Node,
-): React.Node => {
+    children: React.ReactNode,
+): React.ReactElement => {
     let currentChildren = children;
     for (const adapterName of Object.keys(adapters)) {
         const adapter = adapters[adapterName];
@@ -23,5 +22,6 @@ export const renderAdapters = <TAdapters: TestHarnessAdapters>(
             currentChildren = adapter(currentChildren, config);
         }
     }
+    // @ts-expect-error [FEI-5019] - TS2322 - Type 'ReactNode' is not assignable to type 'ReactElement<any, string | JSXElementConstructor<any>>'.
     return currentChildren;
 };

package/src/harness/test-harness.ts

@@ -0,0 +1,13 @@
+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.js → types.ts}

@@ -1,13 +1,12 @@
-// @flow
 import * as React from "react";
 
 /**
  * A adapter to be composed with our test harnass infrastructure.
  */
 export type TestHarnessAdapter<TConfig> = (
-    children: React.Node,
+    children: React.ReactNode,
     config: TConfig,
-) => React.Element<any>;
+) => React.ReactElement<any>;
 
 /**
  * A general map of adapters by their identifiers.
@@ -21,22 +20,25 @@ export type TestHarnessAdapter<TConfig> = (
  * should infer their type in most cases to ensure the strongest typing of
  * the adapters.
  */
-export type TestHarnessAdapters = {|
-    [adapterID: string]: TestHarnessAdapter<any>,
-|};
+export type TestHarnessAdapters = {
+    [adapterID: string]: TestHarnessAdapter<any>;
+};
 
 /**
  * Mapping functions from a adapter-like function to config type.
  */
-type ExtractConfig = <TConfig>(TestHarnessAdapter<TConfig>) => TConfig;
-type ExtractMaybeConfig = <TConfig>(TestHarnessAdapter<TConfig>) => ?TConfig;
+type ExtractConfig = <TConfig>(arg1: TestHarnessAdapter<TConfig>) => TConfig;
+type ExtractMaybeConfig = <TConfig>(
+    arg1: TestHarnessAdapter<TConfig>,
+) => TConfig | null | undefined;
 
 /**
  * Type for easily defining an adapter's config type.
  *
  * This is the `TestHarnessAdapter` equivalent of `React.ElementConfig`.
  */
-export type TestHarnessConfig<TAdapter> = $Call<ExtractConfig, TAdapter>;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+export type TestHarnessConfig<TAdapter> = ReturnType<ExtractConfig>;
 
 /**
  * The `TestHarnessConfigs` type as defined by parsing a given set of adapters.
@@ -45,13 +47,13 @@ export type TestHarnessConfig<TAdapter> = $Call<ExtractConfig, TAdapter>;
  * 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>` - flow does not appear to pattern
+ * marked as `TestHarnessAdapter<TConfig>` - TypeScript does not appear to pattern
  * match against the type definition when invoking the `ExtractConfig` type and I
  * haven't worked out how to get it to multi-dispatch so that it matches
  * functions too. Even worse, if the type doesn't match, it just allows `any`
  * in the `Configs` object, rather than indicating any kind of problem.
  */
-export type TestHarnessConfigs<TAdapters: TestHarnessAdapters> = $ObjMap<
+export type TestHarnessConfigs<TAdapters extends TestHarnessAdapters> = ObjMap<
     TAdapters,
-    ExtractMaybeConfig,
+    ExtractMaybeConfig
 >;

package/src/index.ts

@@ -0,0 +1,20 @@
+// Fixtures framework
+export {fixtures} from "./fixtures/fixtures";
+export type {FixtureFn, FixtureProps, GetPropsOptions} from "./fixtures/types";
+
+// Fetch mocking framework
+export {mockFetch} from "./fetch/mock-fetch";
+export {mockGqlFetch} from "./gql/mock-gql-fetch";
+export {RespondWith} from "./respond-with";
+export {SettleController} from "./settle-controller";
+export type {MockResponse} from "./respond-with";
+export type {FetchMockFn, FetchMockOperation} from "./fetch/types";
+export type {GqlFetchMockFn, GqlMockOperation} from "./gql/types";
+
+// Test harness framework
+export * from "./harness/types";
+export * as harnessAdapters from "./harness/adapters/adapters";
+export {makeHookHarness} from "./harness/make-hook-harness";
+export {makeTestHarness} from "./harness/make-test-harness";
+export {hookHarness} from "./harness/hook-harness";
+export {testHarness} from "./harness/test-harness";

package/src/{mock-requester.js → mock-requester.ts}

@@ -1,13 +1,12 @@
-// @flow
-import type {MockResponse} from "./respond-with.js";
-import type {OperationMock, OperationMatcher, MockFn} from "./types.js";
+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,
-    TOperationMock: OperationMock<TOperationType>,
+    TOperationMock extends OperationMock<TOperationType> = OperationMock<TOperationType>,
 >(
     operationMatcher: OperationMatcher<any>,
     operationToString: (
@@ -39,9 +38,11 @@ export const mockRequester = <
 
         // Default is to reject with some helpful info on what request
         // we rejected.
+        // @ts-expect-error [FEI-5019] - TS2556 - A spread argument must either have a tuple type or be passed to a rest parameter.
+        const operation = operationToString(...args);
         return Promise.reject(
             new Error(`No matching mock response found for request:
-    ${operationToString(...args)}`),
+    ${operation}`),
         );
     };