@khanacademy/wonder-blocks-testing 7.1.9 → 7.1.11

package/src/__docs__/exports.harness-adapters.stories.mdx

@@ -1,187 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-
-<Meta
-    title="Testing / Test Harness / Exports / harnessAdapters"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# harnessAdapters
-
-```ts
-/**
- * The default adapters provided by Wonder Blocks.
- */
-const DefaultAdapters = {
-    css: css.adapter,
-    data: data.adapter,
-    portal: portal.adapter,
-    router: router.adapter,
-};
-
-/**
- * The default configurations to use with the `DefaultAdapters`.
- */
-const DefaultConfigs: Configs<typeof DefaultAdapters> = {
-    css: css.defaultConfig,
-    data: data.defaultConfig,
-    portal: portal.defaultConfig,
-    router: router.defaultConfig,
-};
-```
-
-These are the adapters available for use with the test harness framework and their default configurations. The [`testHarness()`](/docs/testing-test-harness-exports-testharness--page) and [`hookHarness()`](/docs/testing-test-harness-exports-hookharness--page) methods are constructed using these.
-
-If you want to make your own test harness or hook harness using some of these defaults and some of your own, you can combine them into your call to [`makeTestHarness()`](/docs/testing-test-harness-exports-maketestharness--page) or [`makeHookHarness()`](/docs/testing-test-harness-exports-makehookharness--page).
-
-There are four build-in adapters:
-- [`css`](#css)
-- [`data`](#data)
-- [`portal`](#portal)
-- [`router`](#router)
-
-## css
-
-The `css` adapter can be used to apply CSS classes and adhoc styles around the harnessed component.
-
-```ts
-type Config =
-    | string
-    | Array<string>
-    | CSSProperties
-    | {|
-          classes: Array<string>,
-          style: CSSProperties,
-      |};
-```
-
-The configuration for this adapter can be a class name, an array of class names, an Aphrodite-compatible CSS style object, or an object definining both an array of `classes` and a `style` object.
-
-The default configuration for this adapter is for it to not be used.
-
-## data
-
-The `data` adapter provides a convenient way to intercept Wonder Blocks Data requests. It renders one [`InterceptRequests`](/docs/data-exports-interceptrequests--page) component per configured interceptor.
-
-```ts
-type Interceptor = React.ElementConfig<typeof InterceptRequests>["interceptor"];
-
-type Config = Interceptor | Array<Interceptor>;
-```
-
-The configuration is one or more interceptors, as defined by the `interceptor` prop of the [`InterceptRequests`](/docs/data-exports-interceptrequests--page) component, which is effectively.
-
-The default configuration for this adapter is for there to be no interceptors.
-
-## portal
-
-The `portal` adapter ensures there is a mounting point in the DOM for components that rely on rendering with a React portal.
-
-```ts
-type Config = string;
-```
-
-The configuration is just a string providing the identifier to give the added element. The adapter will then render alongside the harnessed component, an empty `div` element with both the `id` and `data-test-id` attributes set to the configuration value.
-
-The default configuration for this adapter is for it to not be used.
-
-## router
-
-The `router` adapter is useful for testing components that use React Router. It will render either a `MemoryRouter` or `StaticRouter`, depending on configuration. It may also optionally render a `Route` with suitable `path` match, depending on the configuration.
-
-```ts
-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;
-```
-
-There are four distinct shapes to the configuration:
-
-1. An object with `initialEntries` array (see `MemoryRouter` props), optional `initialIndex` and `getUserConfirmation` (see `MemoryRouter` props), and an optional `path` parameter if route matching is required.
-1. An object with `forceStatic` set to true, the location as a `string` or `Location` object, with an optional `path` parameter if route matching is required.
-1. An object specifying the location as a `string` or a `LocationShape` object, with an optional `path` parameter if route matching is required.
-1. A `string` specifying the location to use
-
-The first of these provides the most flexibility, basically supporting full configuration of a `MemoryRouter`, which supports history and navigation. The second configuration type is for scenarios where we absolutely do not want navigation, such as server-side rendering scenarios; it forces the use of a `StaticRouter` instance. The third type is for when you just need to render a single location with a matched route path. The fourth and final type allows you to just provide the location as a string.
-
-By default, the router adapter is configured with `{location: "/"}`.

package/src/__docs__/exports.hook-harness.stories.mdx

@@ -1,22 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-
-<Meta
-    title="Testing / Test Harness / Exports / hookHarness()"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# hookHarness()
-
-```ts
-hookHarness(
-    configs?: $Shape<TestHarnessConfigs<typeof DefaultAdapters>>,
-): React.AbstractComponent<any, any>;
-```
-
-This method can be used to create a test harness for use with the `wrapper` option of calls like `renderHook()` from `@testing-library/react-hooks` when writing tests for React hooks.
-
-This method is created by using [`makeHookHarness`](/docs/testing-test-harness-exports-makehookharness--page) with [`harnessAdapters.DefaultAdapters` and `harnessAdapters.DefaultConfigs`](/docs/testing-test-harness-exports-harnessadapters--page).

package/src/__docs__/exports.make-hook-harness.stories.mdx

@@ -1,25 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-
-<Meta
-    title="Testing / Test Harness / Exports / makeHookHarness()"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# makeHookHarness()
-
-```ts
-makeHookHarness<TAdapters: TestHarnessAdapters>(
-    adapters: TAdapters,
-    defaultConfigs: TestHarnessConfigs<TAdapters>,
-): ((
-    configs?: $Shape<TestHarnessConfigs<TAdapters>>,
-) => React.AbstractComponent<any, any>);
-```
-
-This method takes a set of adapters (such as [`harnessAdapters.DefaultAdapters`](/docs/testing-test-harness-exports-harnessadapters--page)) and a set of default configurations for those adapters (such as [`harnessAdapters.DefaultConfigs`](/docs/testing-test-harness-exports-harnessadapters--page)), and returns a function that can be called to create a component that applys those adapters with those default configs, or overrides to those configs.
-
-This returned method can then be used for the `wrapper` option of calls like `renderHook()` from `@testing-library/react-hooks` when writing tests for React hooks.

package/src/__docs__/exports.make-test-harness.stories.mdx

@@ -1,28 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-
-<Meta
-    title="Testing / Test Harness / Exports / makeTestHarness()"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# makeTestHarness()
-
-```ts
-makeTestHarness<TAdapters: TestHarnessAdapters>(
-    adapters: TAdapters,
-    defaultConfigs: TestHarnessConfigs<TAdapters>,
-): (<-TProps, +Instance = mixed>(
-    Component: React.AbstractComponent<TProps, Instance>,
-    configs?: $Shape<TestHarnessConfigs<TAdapters>>,
-) => React.AbstractComponent<TProps, Instance>);
-```
-
-This method takes a set of adapters (such as [`harnessAdapters.DefaultAdapters`](/docs/testing-test-harness-exports-harnessadapters--page)) and a set of default configurations for those adapters (such as [`harnessAdapters.DefaultConfigs`](/docs/testing-test-harness-exports-harnessadapters--page)), and returns a function that can be called to create a component that applys those adapters with those default configs, or overrides to those configs, around another component.
-
-The returned method will ensure refs are forwarded to the harnessed component, and the component the method returns will have the same props as the component it is harnessing.
-
-The harnessed component can be used in unit tests, such as in Jest, to reduce boilerplate needed to setup the test case. It can also be used as a a wrapper component when defining a fixture for a component in the Wonder Blocks Testing [Fixtures framework](/docs/testing-fixtures-overview--page).

package/src/__docs__/exports.mock-fetch.stories.mdx

@@ -1,40 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-
-<Meta
-    title="Testing / Mocking / Exports / mockFetch()"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# mockFetch()
-
-```ts
-mockFetch(): FetchMockFn;
-```
-
-The `mockFetch` function provides an API to easily mock `fetch()` responses. It follows the similar patterns of `jest.fn()` and jest mocks whereby the returned value is both a proxy for the fetch function as well as an API for modifying the behavior of that function.
-
-# API
-
-Besides being a function that fits the `fetch()` signature, the return value of `mockFetch()` has an API to customize the behavior of that function. Used in conjunction with the [`RespondWith`](/docs/testing-mocking-exports-respondwith--page) API, this can create a variety of responses for tests and stories.
-
-| Function | Purpose |
-| -------- | ------- |
-| `mockOperation` | When called, any request that matches the defined mock will respond with the given response. |
-| `mockOperationOnce` | When called, the first request that matches the defined mock will respond with the given response. The mock is only used once. |
-
-Both of these functions have the same signature:
-
-```ts
-type FetchMockOperationFn = (
-    operation: FetchMockOperation,
-    response: MockResponse<any>,
-) => FetchMockFn;
-```
-
-# Operation Matching
-
-The `FetchMockOperation` type is either of type `string` or `RegExp`. When specified as a string, the URL of the request must match the string exactly. When specified as a regular expression, the URL of the request must match the regular expression.

package/src/__docs__/exports.mock-gql-fetch.stories.mdx

@@ -1,64 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-
-<Meta
-    title="Testing / Mocking / Exports / mockGqlFetch()"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# mockGqlFetch()
-
-```ts
-mockGqlFetch(): GqlFetchMockFn;
-```
-
-The `mockGqlFetch` function provides an API to easily mock GraphQL responses for use with the [Wonder Blocks Data GraphQL API](/docs/data-graphql--page). It follows the similar patterns of `jest.fn()` and jest mocks whereby the returned value is both a proxy for the fetch function that is used by [`GqlRouter`](/docs/data-exports-gqlrouter--page) as well as an API for modifying the behavior of that function.
-
-# API
-
-Besides being a function that fits the [`GqlFetchFn`](/docs/data-types-gqlfetchfn--page) signature, the return value of `mockGqlFetch()` has an API to customize the behavior of that function. Used in conjunction with the [`RespondWith`](/docs/testing-mocking-exports-respondwith--page) API, this can create a variety of GraphQL responses for testing and stories.
-
-| Function | Purpose |
-| -------- | ------- |
-| `mockOperation` | When called, any GraphQL operation that matches the defined mock operation will respond with the given response. |
-| `mockOperationOnce` | When called, the first GraphQL operation that matches the defined mock operation will respond with the given response. The mock is only used once. |
-
-Both of these functions have the same signature:
-
-```ts
-type GqlMockOperationFn = <
-    TData: {...},
-    TVariables: {...},
-    TContext: GqlContext,
-    TResponseData: GraphQLJson<TData>,
->(
-    operation: GqlMockOperation<TData, TVariables, TContext>,
-    response: MockResponse<TResponseData>,
-) => GqlFetchMockFn;
-```
-
-# Operation Matching
-
-The `matchOperation` parameter given to a `mockOperation` or `mockOperationOnce` function is a `GqlMockOperation` defining the actual GraphQL operation to be matched by the mock. The variables and context of the mocked operation change how the mock is matched against requests.
-
-```ts
-type GqlMockOperation<
-    TData: {...},
-    TVariables: {...},
-    TContext: GqlContext,
-> = {|
-    operation: GqlOperation<TData, TVariables>,
-    variables?: TVariables,
-    context?: TContext,
-|};
-```
-
-1. When `matchOperation.operation` is present but `matchOperation.variables` and `matchOperation.context` are not, the mock will match any request for the
-same operation, regardless of variables or context on the request.
-2. When `matchOperation.variables` is present but `matchOperation.context` is not, the mock will match any request for the same operation with matching variables, regardless of context on the request.
-3. When `matchOperation.context` is present but `matchOperation.variables` is not, the mock will match any request for the same operation with matching context, regardless of variables on the request.
-4. When `matchOperation.variables` and `matchOperation.context` are present, the mock will match any request for the same operation with matching variables and context.
-

package/src/__docs__/exports.respond-with.stories.mdx

@@ -1,84 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-
-<Meta
-    title="Testing / Mocking / Exports / RespondWith"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# RespondWith
-
-```ts
-interface RespondWith {
-    /**
-     * Rejects with an AbortError to simulate an aborted request.
-     */
-    abortedRequest: (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 with GraphQL data JSON body and status code 200.
-     */
-    graphQLData: <TData: {...}>(
-        data: TData,
-        signal: ?SettleSignal = null,
-    ) => MockResponse<GraphQLJson<TData>>;
-
-    /**
-     * Response that is a GraphQL errors response with status code 200.
-     */
-    graphQLErrors: (
-        errorMessages: $ReadOnlyArray<string>,
-        signal: ?SettleSignal = null,
-    ) => MockResponse<any>;
-
-    /**
-     * Response with JSON body and status code 200.
-     */
-    json: <TJson: {...}>(
-        json: TJson,
-        signal: ?SettleSignal = null,
-    ): MockResponse<TJson>;
-
-    /**
-     * Response body that is valid JSON but not a valid GraphQL response.
-     */
-    nonGraphQLBody: (signal: ?SettleSignal = null) => MockResponse<any>;
-
-    /**
-     * Rejects with the given error.
-     */
-    reject: (error: Error, signal: ?SettleSignal = null) => MockResponse<any>;
-
-    /**
-     * Response with text body and status code.
-     * Status code defaults to 200.
-     */
-    text: <TData = string>(
-        text: string,
-        statusCode: number = 200,
-        signal: ?SettleSignal = null,
-    ) => MockResponse<TData>;
-
-    /**
-     * Response with body that will not parse as JSON and status code 200.
-     */
-    unparseableBody: (signal: ?SettleSignal = null) => MockResponse<any>;
-});
-```
-
-The `RespondWith` object is a helper for defining mock responses to use with
-mock request methods such as [`mockGqlFetch`](/docs/testing-mocking-exports-mockgqlfetch--page).
-
-Each call takes an optional `signal` that can be used to control when the promise generated from the call resolves. See [`SettleController`](/docs/testing-mocking-exports-settlecontroller--page) for related information.

package/src/__docs__/exports.settle-controller.stories.mdx

@@ -1,32 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-
-<Meta
-    title="Testing / Mocking / Exports / SettleController"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# SettleController
-
-```ts
-class SettleController {
-    /**
-     * 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;
-}
-```
-
-The `SettleController` is used to control the settling of a signal. This is specifically created to work with the [`RespondWith`](/docs/testing-mocking-exports-respondwith--page) API. The `signal` property it exposes can be passed to `RespondWith` methods and then the `settle` method can be invoked to settle the signal, causing the related responses to either reject or resolve as appropriate.
-
-This can be useful for tests where the order of operations needs to be controlled in order to verify the expected behaviour of the system under test.

package/src/__docs__/exports.test-harness.stories.mdx

@@ -1,23 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-
-<Meta
-    title="Testing / Test Harness / Exports / testHarness()"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# testHarness()
-
-```ts
-testHarness<-TProps, +Instance = mixed>(
-    Component: React.AbstractComponent<TProps, Instance>,
-    configs?: $Shape<TestHarnessConfigs<typeof DefaultAdapters>>,
-): React.AbstractComponent<TProps, Instance>
-```
-
-This method can be used to create a test harness for a given component. The resultant harnessed component will take the same props as the original component, but will render that component nested inside whatever boilerplate the various harness adapters provide for the given or default configurations.
-
-This method is created by using [`makeTestHarness`](/docs/testing-test-harness-exports-maketestharness--page) with [`harnessAdapters.DefaultAdapters` and `harnessAdapters.DefaultConfigs`](/docs/testing-test-harness-exports-harnessadapters--page).

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

@@ -1,22 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-
-<Meta
-    title="Testing / Mocking / Types / FetchMockFn"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# FetchMockFn
-
-```ts
-type FetchMockFn = {|
-    (input: RequestInfo, init?: RequestOptions): Promise<Response>,
-    mockOperation: FetchMockOperationFn,
-    mockOperationOnce: FetchMockOperationFn,
-|};
-```
-
-This type represents the mocking API for `fetch()`. It is the type of the function returned by the [`mockFetch()`](/docs/testing-mocking-exports-mockfetch--page), which is both a drop in replacement for a `fetch()`-like method, but also exposes the mocking API for configuration additional mocks.

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

@@ -1,18 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-
-<Meta
-    title="Testing / Mocking / Types / FetchMockOperation"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# FetchMockOperation
-
-```ts
-type FetchMockOperation = RegExp | string;
-```
-
-This defines the operation that a fetch mock will respond to. See [`mockFetch()`](/docs/testing-mocking-exports-mockfetch--page) for more details.

package/src/__docs__/types.fixture-fn.stories.mdx

@@ -1,46 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-
-<Meta
-    title="Testing / Fixtures / Types / FixtureFn"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# FixtureFn
-
-```ts
-/**
- * A function for defining a fixture.
- */
-type FixtureFn<TProps: {...}> = (
-    /**
-     * The name of the fixture.
-     */
-    description: string,
-
-    /**
-     * The props for the fixture or a function that returns the props.
-     * The function is injected with an API to facilitate logging.
-     */
-    props: FixtureProps<TProps>,
-
-    /**
-     * An alternative component to render for the fixture.
-     * Useful if the fixture requires some additional setup for testing the
-     * component.
-     */
-    wrapper?: React.ComponentType<TProps>,
-) => mixed;
-
-```
-
-The [`fixtures`](/docs/testing-fixtures-exports-fixtures--page) method returns a method of this type, specific to the component that was passed into `fixtures`.
-
-This function takes two or three arguments:
-
-- `description: string`: A string describing the fixture. This should be used to explain what the fixture is expected to show.
-- `props: FixtureProps<TProps>`: The props that the fixture should be rendered with. See [`FixtureProps`](/docs/testing-fixtures-types-fixtureprops--page).
-- `wrapper?: React.ComponentType<TProps>`: An optional component that will be rendered for the fixture. This can be used to wrap the fixture in a component that adds additional functionality, such as a test harness (see [`makeTestHarness`](/docs/testing-test-harness-exports-maketestharness--page)).

package/src/__docs__/types.fixture-props.stories.mdx

@@ -1,20 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-
-<Meta
-    title="Testing / Fixtures / Types / FixtureProps"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# FixtureProps
-
-```ts
-type FixtureProps<TProps: {...}> =
-    | $ReadOnly<TProps>
-    | ((options: $ReadOnly<GetPropsOptions>) => $ReadOnly<TProps>);
-```
-
-This type describes how props can be provided to a fixture as either a plain object, or a function that returns a plain object. The function will be called with an API to assist in generating the props (see [`GetPropsOptions`](/docs/testing-fixtures-types-getpropsoptions--page)).

package/src/__docs__/types.get-props-options.stories.mdx

@@ -1,52 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-
-<Meta
-    title="Testing / Fixtures / Types / GetPropsOptions"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# GetPropsOptions
-
-```ts
-type GetPropsOptions = {|
-    /**
-     * A function to call that will log output.
-     */
-    log: (message: string, ...args: Array<any>) => void,
-
-    /**
-     * A function to make a handler that will log all arguments with the given
-     * name or message. Useful for logging events as it avoids the boilerplate
-     * of the `log` function.
-     */
-    logHandler: (name: string) => (...args: Array<any>) => void,
-|};
-```
-
-A fixture can provide a callback that the framework invokes to obtain the props for the fixture component. This callback takes a single argument of type `GetPropsOptions`.
-
-This has two calls available.
-
-The `log` callback is for logging output in the context of the fixture. This can be useful for logging information during your fixture. However, in many situations, it is easier to use the `logHandler` callback. The `logHandler` callback takes a single argument of type `string` and returns a function that logs all arguments with the given name or message, allowing easy creation of event handlers that will log that event and its arguments.
-
-For example:
-
-```ts
-    fixture("My fixture that does logging", ({logHandler}) => ({
-        onClick: logHandler("onClick"),
-    }));
-```
-
-is equivalent to:
-
-```ts
-    fixture("My fixture that does logging", ({log}) => ({
-        onClick: (...args) => log("onClick", ...args),
-    }));
-```
-
-