@khanacademy/wonder-blocks-testing 4.0.4 → 5.0.0

package/src/harness/make-test-harness.js

@@ -0,0 +1,68 @@
+// @flow
+import * as React from "react";
+
+import {renderAdapters} from "./render-adapters.js";
+
+import type {TestHarnessAdapters, TestHarnessConfigs} from "./types.js";
+
+/**
+ * Create a test harness method for use with React components.
+ *
+ * This returns a test harness method that applies the default configurations
+ * to the given adapters, wrapping a given component.
+ *
+ * @param {TAdapters} adapters All the adapters to be supported by the returned
+ * test harness.
+ * @param {Configs<TAdapters>} defaultConfigs Default configuration values for
+ * the adapters.
+ * @returns {<-TProps, +Instance = mixed>(
+ *     Component: React.AbstractComponent<TProps, Instance>,
+ *     configs?: $Shape<Configs<TAdapters>>,
+ * ) => React.AbstractComponent<TProps, Instance>} A test harness.
+ */
+export const makeTestHarness = <TAdapters: TestHarnessAdapters>(
+    adapters: TAdapters,
+    defaultConfigs: TestHarnessConfigs<TAdapters>,
+): (<-TProps, +Instance = mixed>(
+    Component: React.AbstractComponent<TProps, Instance>,
+    configs?: $Shape<TestHarnessConfigs<TAdapters>>,
+) => React.AbstractComponent<TProps, Instance>) => {
+    /**
+     * Create a harnessed version of the given component.
+     *
+     * @param {React.AbstractComponent<TProps, Instance>} component The
+     * component to be wrapped.
+     * @param {$Shape<Configs<TAdapters>>} [configs] Any adapter
+     * configuration that you want to override from the `defaultConfigs` values.
+     */
+    return <-TProps, +Instance = mixed>(
+        Component: React.AbstractComponent<TProps, Instance>,
+        configs?: $Shape<TestHarnessConfigs<TAdapters>>,
+    ): React.AbstractComponent<TProps, Instance> => {
+        /**
+         * $FlowIgnore[cannot-spread-indexer]
+         * We know `configs` may overwrite `DefaultConfigs` and we're ok with it.
+         * The interface definition handles the typing for us so we're ok
+         * with it not being inferred here.
+         */
+        const fullConfig: TestHarnessConfigs<TAdapters> = {
+            ...defaultConfigs,
+            ...configs,
+        };
+        const harnessedComponent = React.forwardRef((props, ref) =>
+            renderAdapters<TAdapters>(
+                adapters,
+                fullConfig,
+                <Component {...props} ref={ref} />,
+            ),
+        );
+
+        // We add a name for the component here so that we can detect that
+        // later and also see it in traces and what have you.
+        harnessedComponent.displayName = `testHarness(${
+            Component.displayName || Component.name || "Component"
+        })`;
+
+        return harnessedComponent;
+    };
+};

package/src/harness/render-adapters.js

@@ -0,0 +1,27 @@
+// @flow
+import * as React from "react";
+
+import type {TestHarnessConfigs, TestHarnessAdapters} from "./types.js";
+
+/**
+ * Render test adapters around a child component.
+ */
+export const renderAdapters = <TAdapters: TestHarnessAdapters>(
+    adapters: TAdapters,
+    configs: TestHarnessConfigs<TAdapters>,
+    children: React.Node,
+): React.Node => {
+    let currentChildren = children;
+    for (const adapterName of Object.keys(adapters)) {
+        const adapter = adapters[adapterName];
+        const config = configs[adapterName];
+        /**
+         * Some adapters support a null config, some don't, either way
+         * we always assume that null config means no adapter.
+         */
+        if (config != null) {
+            currentChildren = adapter(currentChildren, config);
+        }
+    }
+    return currentChildren;
+};

package/src/harness/test-harness.js

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

@@ -0,0 +1,57 @@
+// @flow
+import * as React from "react";
+
+/**
+ * A adapter to be composed with our test harnass infrastructure.
+ */
+export type TestHarnessAdapter<-TConfig> = (
+    children: React.Node,
+    config: TConfig,
+) => React.Element<any>;
+
+/**
+ * A general map of adapters by their identifiers.
+ *
+ * It's OK that this has `any` for the config type as this is the very base
+ * version of a adapter set. In reality, a more specific type will be used
+ * with the harness functions that use more specific definitions of known
+ * adapters. This is just to support the base reality of not knowing.
+ *
+ * Use this on input positions only. Output positions for adapters
+ * should infer their type in most cases to ensure the strongest typing of
+ * the adapters.
+ */
+export type TestHarnessAdapters = {|
+    [adapterID: string]: TestHarnessAdapter<any>,
+|};
+
+/**
+ * Mapping functions from a adapter-like function to config type.
+ */
+type ExtractConfig = <TConfig>(TestHarnessAdapter<TConfig>) => TConfig;
+type ExtractMaybeConfig = <TConfig>(TestHarnessAdapter<TConfig>) => ?TConfig;
+
+/**
+ * Type for easily defining an adapter's config type.
+ *
+ * This is the `TestHarnessAdapter` equivalent of `React.ElementConfig`.
+ */
+export type TestHarnessConfig<-TAdapter> = $Call<ExtractConfig, TAdapter>;
+
+/**
+ * The `TestHarnessConfigs` type as defined by parsing a given set of adapters.
+ *
+ * NOTE: This only works if the properties of the passed `TAdapters` type
+ * are explicitly typed as `TestHarnessAdapter<TConfig>` so if passing in a
+ * non-Adapters type (which we should be, to get strong `TConfig` types instead
+ * of `any`), then that object should make sure that each adapter is strongly
+ * marked as `TestHarnessAdapter<TConfig>` - flow does not appear to pattern
+ * match against the type definition when invoking the `ExtractConfig` type and I
+ * haven't worked out how to get it to multi-dispatch so that it matches
+ * functions too. Even worse, if the type doesn't match, it just allows `any`
+ * in the `Configs` object, rather than indicating any kind of problem.
+ */
+export type TestHarnessConfigs<-TAdapters: TestHarnessAdapters> = $ObjMap<
+    TAdapters,
+    ExtractMaybeConfig,
+>;

package/src/index.js

@@ -1,30 +1,34 @@
 // @flow
 
 // Fixtures framework
-export * as adapters from "./fixtures/adapters/adapters.js";
+export * as fixtureAdapters from "./fixtures/adapters/adapters.js";
 export {fixtures} from "./fixtures/fixtures.js";
 export {setup as setupFixtures} from "./fixtures/setup.js";
 export type {
-    Adapter,
-    AdapterFactory,
-    AdapterFixtureOptions,
-    AdapterGroup,
-    AdapterGroupOptions,
-    AdapterOptions,
-    Configuration,
-    CustomWrapperProps,
-    GetPropsOptions,
+    CustomMountProps,
+    FixturesAdapter,
+    FixturesAdapterFactory,
+    FixturesAdapterFixtureOptions,
+    FixturesAdapterGroup,
+    FixturesAdapterGroupOptions,
+    FixturesAdapterOptions,
+    FixturesConfiguration,
     FixturesOptions,
+    GetPropsOptions,
 } from "./fixtures/types.js";
 
 // Fetch mocking framework
-export type {MockResponse} from "./make-mock-response.js";
-export {RespondWith} from "./make-mock-response.js";
 export {mockFetch} from "./fetch/mock-fetch.js";
-export type {
-    FetchMockFn,
-    FetchMock,
-    FetchMockOperation,
-} from "./fetch/types.js";
 export {mockGqlFetch} from "./gql/mock-gql-fetch.js";
-export type {GqlFetchMockFn, GqlMock, GqlMockOperation} from "./gql/types.js";
+export {RespondWith} from "./make-mock-response.js";
+export type {MockResponse} from "./make-mock-response.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";