@khanacademy/wonder-blocks-testing 8.0.7 → 8.0.9

package/src/harness/adapters/adapters.ts

@@ -1,3 +1,6 @@
+// WARNING: If you modify this file you may need to update adapters.js.flow
+// to ensure that the Flow types are still correct.
+
 import * as css from "./css";
 import * as data from "./data";
 import * as portal from "./portal";
@@ -29,4 +32,4 @@ export const DefaultConfigs: TestHarnessConfigs<typeof DefaultAdapters> = {
     data: data.defaultConfig,
     portal: portal.defaultConfig,
     router: router.defaultConfig,
-};
+} as const;

package/src/harness/adapters/router.jsx.flow

@@ -0,0 +1,112 @@
+/**
+ * @flow
+ */
+import * as React from "react";
+import { MemoryRouter } from "react-router-dom";
+import type { LocationShape } from "react-router-dom";
+import type { TestHarnessAdapter } from "../types";
+declare type MemoryRouterProps = React.ElementConfig<typeof MemoryRouter>;
+
+/**
+ * Configuration for the withLocation test harness adapter.
+ */
+declare type Config =
+  | $ReadOnly<
+      | {|
+          /**
+           * See MemoryRouter prop for initialEntries.
+           */
+          initialEntries: $PropertyType<MemoryRouterProps, "initialEntries">,
+
+          /**
+           * See MemoryRouter prop for initialIndex.
+           */
+          initialIndex?: $PropertyType<MemoryRouterProps, "initialIndex">,
+
+          /**
+           * See MemoryRouter prop for getUserConfirmation.
+           */
+          getUserConfirmation?: $PropertyType<
+            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 | LocationShape,
+
+          /**
+           * 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,
+        |}
+    >
+  | string;
+/**
+ * The default configuration for this adapter.
+ */
+declare export var defaultConfig: {|
+  +location: "/",
+|};
+/**
+ * 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.
+ */
+declare export var adapter: TestHarnessAdapter<Config>;

package/src/harness/adapters/router.tsx

@@ -1,9 +1,10 @@
+// WARNING: If you modify this file you may need to update router.jsx.flow
+// to ensure that the Flow types are still correct.
 import * as React from "react";
 
 import {StaticRouter, MemoryRouter, Route, Switch} from "react-router-dom";
 
-// @ts-expect-error [FEI-5019] - TS2305 - Module '"react-router-dom"' has no exported member 'LocationShape'. | TS2305 - Module '"react-router-dom"' has no exported member 'Location'.
-import type {LocationShape, Location} from "react-router-dom";
+import type {LocationDescriptor} from "history";
 import type {TestHarnessAdapter} from "../types";
 
 type MemoryRouterProps = JSX.LibraryManagedAttributes<
@@ -48,7 +49,7 @@ type Config = // The initial location to use.
                     /**
                      * The location to use.
                      */
-                    location: string | Location;
+                    location: LocationDescriptor;
                     /**
                      * Force the use of a StaticRouter, instead of MemoryRouter.
                      */
@@ -71,7 +72,7 @@ type Config = // The initial location to use.
                     /**
                      * The initial location to use.
                      */
-                    location: string | LocationShape;
+                    location: LocationDescriptor;
                     /**
                      * A path match to use.
                      *

package/src/harness/types.js.flow

@@ -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/harness/types.ts

@@ -1,7 +1,9 @@
+// WARNING: If you modify this file you may need to update types.js.flow
+// to ensure that the Flow types are still correct.
 import * as React from "react";
 
 /**
- * A adapter to be composed with our test harnass infrastructure.
+ * A adapter to be composed with our test harness infrastructure.
  */
 export type TestHarnessAdapter<TConfig> = (
     children: React.ReactNode,
@@ -21,24 +23,17 @@ export type TestHarnessAdapter<TConfig> = (
  * the adapters.
  */
 export type TestHarnessAdapters = {
-    [adapterID: string]: TestHarnessAdapter<any>;
+    readonly [adapterID: string]: TestHarnessAdapter<any>;
 };
 
-/**
- * Mapping functions from a adapter-like function to config type.
- */
-type ExtractConfig = <TConfig>(arg1: TestHarnessAdapter<TConfig>) => TConfig;
-type ExtractMaybeConfig = <TConfig>(
-    arg1: TestHarnessAdapter<TConfig>,
-) => TConfig | null | undefined;
-
 /**
  * Type for easily defining an adapter's config type.
- *
- * This is the `TestHarnessAdapter` equivalent of `React.ElementConfig`.
  */
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-export type TestHarnessConfig<TAdapter> = ReturnType<ExtractConfig>;
+export type TestHarnessConfig<TAdapter> = TAdapter extends TestHarnessAdapter<
+    infer TConfig
+>
+    ? TConfig
+    : never;
 
 /**
  * The `TestHarnessConfigs` type as defined by parsing a given set of adapters.
@@ -47,13 +42,8 @@ export type TestHarnessConfig<TAdapter> = ReturnType<ExtractConfig>;
  * 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>` - TypeScript 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.
+ * marked as `TestHarnessAdapter<TConfig>`
  */
-export type TestHarnessConfigs<TAdapters extends TestHarnessAdapters> = ObjMap<
-    TAdapters,
-    ExtractMaybeConfig
->;
+export type TestHarnessConfigs<TAdapters extends TestHarnessAdapters> = {
+    [K in keyof TAdapters]: TestHarnessConfig<TAdapters[K]> | null | undefined;
+};