@khanacademy/wonder-blocks-testing 4.0.4 → 5.0.0

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

@@ -0,0 +1,23 @@
+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.custom-mount-props.stories.mdx

@@ -0,0 +1,35 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Testing / Fixtures / Types / CustomMountProps<>"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# CustomMountProps&lt;&gt;
+
+```ts
+type CustomMountProps<TProps: {...}> = {|
+    /**
+     * The fixture props for the component to be rendered.
+     */
+    props: TProps,
+
+    /**
+     * The component to render.
+     */
+    component: React.ComponentType<TProps>,
+
+    /**
+     * The log callback for logging information.
+     */
+    log: (message: string, ...args: Array<any>) => mixed,
+|};
+```
+
+When creating a new adapter instance, the [`FixtureAdapterFactory`](/docs/testing-fixtures-types-fixtureadapterfactory--page) can take an optional component to be used as the root component for each fixture, also know as the mounting component.
+
+The `CustomMountProps<>` type defines the props that will be applied to that mounting component. It includes the `component` to be rendered as the fixture, the `props` to pass to that component, and the `log` callback, which the mounting component can use for any logging it may require.

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

@@ -0,0 +1,22 @@
+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

@@ -0,0 +1,18 @@
+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.fixtures-adapter-factory.stories.mdx

@@ -0,0 +1,23 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Testing / Fixtures / Types / FixturesAdapterFactory<>"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# FixturesAdapterFactory&lt;&gt;
+
+```ts
+type FixturesAdapterFactory<
+    TAdapterOptions: {...},
+    TAdapterExports: {...},
+> = (
+    MountingComponent: ?React.ComponentType<CustomWrapperProps<any>>,
+) => FixturesAdapter<TAdapterOptions, TAdapterExports>;
+```
+
+When implementing a custom [`FixturesAdapter<>`](/docs/testing-fixtures-types-fixturesadapter--page), you should provide a factory function for producing instances of the adapter. This type describes the signature of the factory function.

package/src/__docs__/types.fixtures-adapter-fixture-options.stories.mdx

@@ -0,0 +1,35 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Testing / Fixtures / Types / FixturesAdapterFixtureOptions<>"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# FixturesAdapterFixtureOptions&lt;&gt;
+
+```ts
+type FixturesAdapterFixtureOptions<TProps: {...}> = {|
+    /**
+     * Description of the fixture.
+     */
+    +description: string,
+
+    /**
+     * Method to obtain props for the fixture.
+     */
+    +getProps: (options: $ReadOnly<GetPropsOptions>) => $ReadOnly<TProps>,
+
+    /**
+     * The component to render for this fixture.
+     */
+    +component: React.ComponentType<TProps>,
+|};
+```
+
+These options are passed to the `declareFixture()` function of a [`FixturesAdapterGroup<>`](/docs/testing-fixtures-types-fixturesadaptergroup--page).
+
+The `description` property is used to describe the fixture, the `component` is the component that renders the fixture, and the `getProps` method is used to obtain the props for that component.

package/src/__docs__/types.fixtures-adapter-group-options.stories.mdx

@@ -0,0 +1,37 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Testing / Fixtures / Types / FixturesAdapterGroupOptions"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# FixturesAdapterGroupOptions
+
+```ts
+type FixturesAdapterGroupOptions = {|
+    /**
+     * The title of the group.
+     *
+     * If omitted, the adapter is free to generate a default or ask for one
+     * using the passed getDefaultTitle() function.
+     */
+    +title: ?string,
+
+    /**
+     * Description of the group.
+     */
+    +description: ?string,
+
+    /**
+     * Function that will generate a default title if an adapter cannot
+     * generate its own.
+     */
+    +getDefaultTitle: () => string,
+|};
+```
+
+These are options that the fixtures framework provides when `declareGroup()` is called on the configured adapter to create a new [`FixturesAdapterGroup<>`](/docs/testing-fixtures-types-fixturesadaptergroup--page).

package/src/__docs__/types.fixtures-adapter-group.stories.mdx

@@ -0,0 +1,43 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Testing / Fixtures / Types / FixturesAdapterGroup<>"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# FixturesAdapterGroup&lt;&gt;
+
+```ts
+interface FixturesAdapterGroup<
+    TProps: {...},
+    TAdapterOptions: {...},
+    TAdapterExports: {...},
+> {
+    /**
+     * Declare a fixture.
+     */
+    declareFixture(
+        options: $ReadOnly<FixturesAdapterFixtureOptions<TProps>>,
+    ): void;
+
+    /**
+     * Close the group and obtain the exports, if the adapter requires any.
+     *
+     * @param {Options} adapterOptions Some options to pass to the adapter.
+     * Allows callers to tailor things to a specific adapter. How these options
+     * are used is adapter-specific.
+     *
+     * @returns {?Exports} The exports that the adapter requires fixture files
+     * to export.
+     */
+    closeGroup(
+        adapterOptions: $ReadOnly<Partial<TAdapterOptions>>,
+    ): ?$ReadOnly<TAdapterExports>;
+}
+```
+
+Each call to the [`fixtures()`](/docs/testing-fixtures-exports-fixtures--page) function invokes the `declareGroup()` method on the [`FixturesAdapter<>`](/docs/testing-fixtures-types-fixturesadapter--page) instance that has been configured using [`setupFixtures()`](/docs/testing-fixtures-exports-setupfixtures--page). The group that is returned by `declareGroup()` must match this interface.

package/src/__docs__/types.fixtures-adapter-options.stories.mdx

@@ -0,0 +1,21 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Testing / Fixtures / Types / FixturesAdapterOptions"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# FixturesAdapterOptions
+
+```ts
+type FixturesAdapterOptions = {|
+    storybook?: StorybookOptions,
+    [adapterName: string]: {...},
+|};
+```
+
+Defines adapter-specific options. These are used with fixtures when needing to configure them for specific adapters.

package/src/__docs__/types.fixtures-adapter.stories.mdx

@@ -0,0 +1,35 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Testing / Fixtures / Types / FixturesAdapter<>"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# FixturesAdapter&lt;&gt;
+
+```ts
+interface FixturesAdapter<TAdapterOptions: {...}, TAdapterExports: {...}> {
+    /**
+     * The name of the adapter.
+     */
+    get name(): string;
+
+    /**
+     * Declare a fixture group.
+     *
+     * @returns {FixturesAdapterGroup<TProps, TAdapterOptions, TAdapterExports>} The
+     * declared group.
+     */
+    declareGroup<TProps: {...}>(
+        options: $ReadOnly<AdapterGroupOptions>,
+    ): FixturesAdapterGroup<TProps, TAdapterOptions, TAdapterExports>;
+}
+```
+
+This type describes an adapter for use with our fixtures framework.
+
+

package/src/__docs__/types.fixtures-configuration.stories.mdx

@@ -0,0 +1,35 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Testing / Fixtures / Types / FixturesConfiguration<>"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# FixturesConfiguration&lt;&gt;
+
+```ts
+type FixturesConfiguration<
+    TAdapterOptions: {...},
+    TAdapterExports: {...},
+> = {|
+    /**
+     * The adapter to use for declaring fixtures.
+     */
+    +adapter: FixturesAdapter<TAdapterOptions, TAdapterExports>,
+
+    /**
+     * Default options to apply to every fixture group.
+     *
+     * Each top-level option in this object will be merged with the equivalent
+     * top-level option that a specific fixture requests. Where collisions
+     * occur, the fixture options win.
+     */
+    +defaultAdapterOptions?: $ReadOnly<Partial<TAdapterOptions>>,
+|};
+```
+
+The configuration type passed to [`setupFixtures()`](/docs/testing-fixtures-exports-setupfixtures--page).

package/src/__docs__/types.fixtures-options.stories.mdx

@@ -0,0 +1,51 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Testing / Fixtures / Types / FixturesOptions<>"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# FixturesOptions
+
+```ts
+type FixturesOptions<TProps: {...}> = {|
+    /**
+     * The component being tested by the fixtures.
+     */
+    component: React.ComponentType<TProps>,
+
+    /**
+     * Optional title of the fixture collection.
+     *
+     * Adapters may enforce a title, otherwise the component name is used.
+     */
+    title?: string,
+
+    /**
+     * Optional description of the fixture collection.
+     */
+    description?: string,
+
+    /**
+     * Optional default wrapper to apply around the component under test.
+     */
+    defaultWrapper?: React.ComponentType<TProps>,
+
+    /**
+     * Additional options to apply to specific adapters.
+     */
+    additionalAdapterOptions?: FixturesAdapterOptions,
+|};
+```
+
+This type is used to pass options to the [`fixtures()`](/docs/testing-fixtures-types-fixturesoptions--page) method when describing fixtures for a specific component.
+
+It specifies the `component` being rendered and tested by each fixtures. Optionally, it can also specify a `title` and `description` for the fixtures, as well as a `defaultWrapper` component to use by default to wrap the component under test for each fixture, and an `additionalAdapterOptions` object that allows each adapter type to be individually configured for the fixtures.
+
+If the `title` is omitted, the adapter can either request a default title, which will be based off the name of the `component` React component, or it can provide its own title based as necessary. For example, Storybook has a default title based off the file location of the component when the `title` is omitted.
+
+Some adapters may ignore the `description` field.

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

@@ -0,0 +1,25 @@
+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 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 a single `log` property; a callback for logging output in the context of the fixture. This can be useful for logging event handler invocations, for example.

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

@@ -0,0 +1,27 @@
+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

@@ -0,0 +1,26 @@
+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

@@ -0,0 +1,18 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Testing / Mocking / Types / MockResponse<>"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# MockResponse&lt;&gt;
+
+```ts
+opaque type MockResponse<TJson>;
+```
+
+This opaque type specifies a mock response. Values of this type are generated by the [`RespondWith`](/docs/testing-mocking-exports-respondwith--page) API.

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

@@ -0,0 +1,21 @@
+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

@@ -0,0 +1,46 @@
+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

@@ -0,0 +1,18 @@
+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

@@ -0,0 +1,59 @@
+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,5 +1,4 @@
 //@flow
-import type {OperationMock} from "../types.js";
 import type {MockResponse} from "../make-mock-response.js";
 
 export type FetchMockOperation = RegExp | string;
@@ -14,5 +13,3 @@ export type FetchMockFn = {|
     mockOperation: FetchMockOperationFn,
     mockOperationOnce: FetchMockOperationFn,
 |};
-
-export type FetchMock = OperationMock<FetchMockOperation>;