@khanacademy/wonder-blocks-testing 7.1.10 → 7.1.12

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),
-    }));
-```
-
-

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/gql/types.js

@@ -1,34 +0,0 @@
-//@flow
-import type {GqlOperation, GqlContext} from "@khanacademy/wonder-blocks-data";
-import type {GraphQLJson} from "../types";
-import type {MockResponse} from "../respond-with";
-
-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,
-|};