@khanacademy/wonder-blocks-testing 7.1.9 → 7.1.11

package/src/__docs__/types.gql-fetch-mock-fn.stories.mdx

@@ -1,27 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-
-<Meta
-    title="Testing / Mocking / Types / GqlFetchMockFn"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# GqlFetchMockFn
-
-```ts
-type GqlFetchMockFn = {|
-    (
-        operation: GqlOperation<any, any>,
-        variables: ?{...},
-        context: GqlContext,
-    ): Promise<Response>,
-    mockOperation: GqlMockOperationFn,
-    mockOperationOnce: GqlMockOperationFn,
-|};
-```
-
-This type represents the mocking API for use with the [Wonder Blocks Data GraphQL API](/docs/data-graphql--page). It is the type of the function returned by the [`mockGqlFetch()`](/docs/testing-mocking-exports-mockgqlfetch--page).
-

package/src/__docs__/types.gql-mock-operation.stories.mdx

@@ -1,26 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-
-<Meta
-    title="Testing / Mocking / Types / GqlMockOperation<>"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# GqlMockOperation&lt;&gt;
-
-```ts
-type GqlMockOperation<
-    TData: {...},
-    TVariables: {...},
-    TContext: GqlContext,
-> = {|
-    operation: GqlOperation<TData, TVariables>,
-    variables?: TVariables,
-    context?: TContext,
-|};
-```
-
-This defines the operation that a GraphQL mock will respond to. See [`mockGqlFetch`](/docs/testing-mocking-exports-mockgqlfetch--page) for more details.

package/src/__docs__/types.mock-response.stories.mdx

@@ -1,22 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-
-<Meta
-    title="Testing / Mocking / Types / MockResponse<>"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# MockResponse&lt;&gt;
-
-```ts
-type MockResponse<TJson> = {|
-    toPromise: () => Promise<Response>,
-|};
-```
-
-This type specifies a mock response. Values of this type are generated by the [`RespondWith`](/docs/testing-mocking-exports-respondwith--page) API. The type parameter is included to allow uses to enforce if they only support `MockResponses` that resolve to a specific JSON pattern.
-
-The `toPromise` method can be used to generate a new promise from the mocked response definition. Note that `toPromise` will always generate a new promise and any promise created will settle according to any signal passed to the corresponding `RespondWith` API call.

package/src/__docs__/types.test-harness-adapter.stories.mdx

@@ -1,21 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-
-<Meta
-    title="Testing / Test Harness / Types / TestHarnessAdapter<>"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# TestHarnessAdapter&lt;&gt;
-
-```ts
-type TestHarnessAdapter<TConfig> = (
-    children: React.Node,
-    config: TConfig,
-) => React.Element<any>;
-```
-
-This type represents the signature of a an adapter function for use with the test harness framework methods, [`makeTestHarness()`](/docs/testing-test-harness-exports-maketestharness--page) and [`makeHookHarness()`](/docs/testing-test-harness-exports-makehookharness--page).

package/src/__docs__/types.test-harness-adapters.stories.mdx

@@ -1,46 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-
-<Meta
-    title="Testing / Test Harness / Types / TestHarnessAdapters"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# TestHarnessAdapters
-
-```ts
-type TestHarnessAdapters = {|
-    [adapterID: string]: TestHarnessAdapter<any>,
-|};
-```
-
-Defines a generic collection of test harness adapters.
-
-Only use `TestHarnessAdapters` in input locations to verify a set of adapters conforms to that type, but avoid using it in output locations as it can erase useful type information.
-
-For example, the [`harnessAdapters.DefaultAdapters`](/docs/testing-test-harness-exports-harnessadapters--page) type is specific to the adapters it contains.
-
-```ts
-const DefaultAdapters = {
-    css: css.adapter,
-    data: data.adapter,
-    portal: portal.adapter,
-    router: router.adapter,
-};
-```
-
-`DefaultAdapters` is not strongly typed to `TestHarnessAdapters`. Instead, its type is:
-
-```ts
-type DefaultAdaptersType = {|
-   css: typeof css.adapter,
-   data: typeof data.adapter,
-   portal: typeof portal.adapter,
-   router: typeof router.adapter,
-|};
-```
-
-It conforms to the `TestHarnessAdapters` type because each key is a string and the value of each property is a variation of `TestHarnessAdapter<TConfig>` with a different type for `TConfig` in each case, but it is not equivalent to the `TestHarnessAdapters` type where each key is a string and each value is exactly `TestHarnessAdapter<any>`.

package/src/__docs__/types.test-harness-config.stories.mdx

@@ -1,18 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-
-<Meta
-    title="Testing / Test Harness / Types / TestHarnessConfig<>"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# TestHarnessConfig&lt;&gt;
-
-```ts
-type TestHarnessConfig<TAdapter>;
-```
-
-When given an adapter type conforming to [`TestHarnessAdapter`](/docs/testing-test-harness-types-testharnessadapter--page), this type will represent that adapter type's configuration type.

package/src/__docs__/types.test-harness-configs.stories.mdx

@@ -1,59 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-
-<Meta
-    title="Testing / Test Harness / Types / TestHarnessConfigs<>"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# TestHarnessConfigs&lt;&gt;
-
-```ts
-type TestHarnessConfigs<TAdapters: TestHarnessAdapters>;
-```
-
-When given the type of a set of adapters conforming to [`TestHarnessAdapters`](/docs/testing-test-harness-types-testharnessadapters--page), this type will represent a set of configurations for those adapters.
-
-It is important to note here that if the `TAdapters` type passed in is the actual `TestHarnessAdapters` type, then the resulting configuration type will have each adapter's config being set to `any`. Instead of using the `TestHarnessAdapters` type directly, the passed object should not be typed as that, but should merely conform to that type.
-
-For example, the [`harnessAdapters.DefaultAdapters`](/docs/testing-test-harness-exports-harnessadapters--page) type is specific to the adapters it contains.
-
-```ts
-const DefaultAdapters = {
-    css: css.adapter,
-    data: data.adapter,
-    portal: portal.adapter,
-    router: router.adapter,
-};
-```
-
-`DefaultAdapters` is not strongly typed to `TestHarnessAdapters`. Instead, its type is:
-
-```ts
-type DefaultAdaptersType = {|
-   css: typeof css.adapter,
-   data: typeof data.adapter,
-   portal: typeof portal.adapter,
-   router: typeof router.adapter,
-|};
-```
-
-It conforms to the `TestHarnessAdapters` type, but it is not equivalent to the `TestHarnessAdapters` type. This is important when we consider the companion export, [`harnessAdapters.DefaultConfigs`](/docs/testing-test-harness-exports-harnessadapters--page).
-
-```ts
-const DefaultConfigs: TestHarnessConfigs<typeof DefaultAdapters> = {
-    css: css.defaultConfig,
-    data: data.defaultConfig,
-    portal: portal.defaultConfig,
-    router: router.defaultConfig,
-};
-```
-
-`DefaultConfigs` is typed using `TestHarnessConfigs<typeof DefaultAdapters>`. Because `DefaultAdapters` is strongly typed specifically to each adapter it contains, the type that `TestHarnessConfigs<>` creates ensures that there is one configuration per adapter key, and that the configuration type for each adapter key is correct for the corresponding adapter.
-
-If we had typed `DefaultAdapters` as `TestHarnessAdapters`, then although we would still enforce one configuration per adapter key, we would allow `any` type to provide that configuration, which does not give us any real type safety.
-
-So, to summarize, use `TestHarnessAdapters` in input locations to verify a set of adapters conforms to that type, but avoid using it in output locations as it can erase useful type information.

package/src/fetch/types.js

@@ -1,15 +0,0 @@
-//@flow
-import type {MockResponse} from "../respond-with.js";
-
-export type FetchMockOperation = RegExp | string;
-
-type FetchMockOperationFn = (
-    operation: FetchMockOperation,
-    response: MockResponse<any>,
-) => FetchMockFn;
-
-export type FetchMockFn = {|
-    (input: RequestInfo, init?: RequestOptions): Promise<Response>,
-    mockOperation: FetchMockOperationFn,
-    mockOperationOnce: FetchMockOperationFn,
-|};

package/src/gql/mock-gql-fetch.js

@@ -1,18 +0,0 @@
-// @flow
-import {gqlRequestMatchesMock} from "./gql-request-matches-mock.js";
-import {mockRequester} from "../mock-requester.js";
-import type {GqlFetchMockFn, GqlMockOperation} from "./types.js";
-
-/**
- * A mock for the fetch function passed to GqlRouter.
- */
-export const mockGqlFetch = (): GqlFetchMockFn =>
-    mockRequester<GqlMockOperation<any, any, any>, _>(
-        gqlRequestMatchesMock,
-        (operation, variables, context) =>
-            `Operation: ${operation.type} ${operation.id}
-    Variables: ${
-        variables == null ? "None" : JSON.stringify(variables, null, 2)
-    }
-    Context: ${JSON.stringify(context, null, 2)}`,
-    );

package/src/gql/types.js

@@ -1,34 +0,0 @@
-//@flow
-import type {GqlOperation, GqlContext} from "@khanacademy/wonder-blocks-data";
-import type {GraphQLJson} from "../types.js";
-import type {MockResponse} from "../respond-with.js";
-
-export type GqlMockOperation<
-    TData: {...},
-    TVariables: {...},
-    TContext: GqlContext,
-> = {|
-    operation: GqlOperation<TData, TVariables>,
-    variables?: TVariables,
-    context?: TContext,
-|};
-
-type GqlMockOperationFn = <
-    TData: {...},
-    TVariables: {...},
-    TContext: GqlContext,
-    TResponseData: GraphQLJson<TData>,
->(
-    operation: GqlMockOperation<TData, TVariables, TContext>,
-    response: MockResponse<TResponseData>,
-) => GqlFetchMockFn;
-
-export type GqlFetchMockFn = {|
-    (
-        operation: GqlOperation<any, any>,
-        variables: ?{...},
-        context: GqlContext,
-    ): Promise<Response>,
-    mockOperation: GqlMockOperationFn,
-    mockOperationOnce: GqlMockOperationFn,
-|};

package/src/harness/adapters/router.js

@@ -1,206 +0,0 @@
-// @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/test-harness.js

@@ -1,24 +0,0 @@
-// @flow
-import * as React from "react";
-
-import {makeTestHarness} from "./make-test-harness.js";
-import {DefaultAdapters, DefaultConfigs} from "./adapters/adapters.js";
-
-import type {TestHarnessConfigs} from "./types.js";
-
-/**
- * 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: <-TProps, +Instance = mixed>(
-    Component: React.AbstractComponent<TProps, Instance>,
-    configs?: $Shape<TestHarnessConfigs<typeof DefaultAdapters>>,
-) => React.AbstractComponent<TProps, Instance> = makeTestHarness(
-    DefaultAdapters,
-    DefaultConfigs,
-);

package/src/index.js

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

package/src/settle-controller.js

@@ -1,35 +0,0 @@
-// @flow
-import {SettleSignal} from "./settle-signal.js";
-
-/**
- * A controller for the `RespondWith` API to control response settlement.
- */
-export class SettleController {
-    #settleFn: () => void;
-    #signal: SettleSignal;
-
-    constructor() {
-        // Create our signal.
-        // We pass in a method to capture it's settle function so that
-        // only we can call it.
-        this.#signal = new SettleSignal(
-            (settleFn) => (this.#settleFn = settleFn),
-        );
-    }
-
-    /**
-     * The signal to pass to the `RespondWith` API.
-     */
-    get signal(): SettleSignal {
-        return this.#signal;
-    }
-
-    /**
-     * Settle the signal and therefore any associated responses.
-     *
-     * @throws {Error} if the signal has already been settled.
-     */
-    settle(): void {
-        this.#settleFn();
-    }
-}

package/src/types.js

@@ -1,39 +0,0 @@
-// @flow
-import type {MockResponse} from "./respond-with.js";
-
-/**
- * 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: {...}> =
-    | {|
-          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: TOperationType>(
-    operation: TOperation,
-    response: MockResponse<any>,
-) => MockFn<TOperationType>;