@khanacademy/wonder-blocks-testing 6.1.0 → 7.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@khanacademy/wonder-blocks-testing",
-    "version": "6.1.0",
+    "version": "7.0.2",
     "design": "v1",
     "publishConfig": {
         "access": "public"
@@ -13,7 +13,7 @@
         "test": "echo \"Error: no test specified\" && exit 1"
     },
     "dependencies": {
-        "@babel/runtime": "^7.16.3",
+        "@babel/runtime": "^7.18.6",
         "@khanacademy/wonder-blocks-data": "^8.0.3"
     },
     "peerDependencies": {

package/src/__docs__/_overview_fixtures.stories.mdx

@@ -11,12 +11,8 @@ import {Meta} from "@storybook/addon-docs";
 
 # Fixtures
 
-The fixtures framework provides an agnostic way to declare component fixtures that can then be adapted via runtime configuration to the fixture rendering environment of choice.
+The fixtures framework provides a way to declare CSF/Storybook-compatible stories with props type checking (something that is easy to forget when using the standard story API).
 
-To use the framework for defining fixtures, import the [`fixtures()`](/docs/testing-fixtures-exports-fixtures--page) method. You can configure the framework for your specific environment (such as Storybook) using the [`setupFixtures()`](/docs/testing-fixtures-exports-setupfixtures--page) method.
-
-An adapter to output fixtures for [Storybook](/docs/testing-fixtures-exports-fixtureadapters--page) is included.
+To use the framework for defining fixtures, import the [`fixtures()`](/docs/testing-fixtures-exports-fixtures--page) method.
 
 Some examples of this framework in use with Storybook can be seen [here](/docs/testing-fixtures-basic--f-1).
-
-Types are also exported to enable the creation of adapters for other environments as you may need.

package/src/__docs__/exports.fixtures.stories.mdx

@@ -16,38 +16,16 @@ type FixtureProps<TProps: {...}> =
     | $ReadOnly<TProps>
     | ((options: $ReadOnly<GetPropsOptions>) => $ReadOnly<TProps>);
 
-fixtures<TProps: {...}>(
-    component: React.ComponentType<TProps>,
-    fn: (
-        fixture: (
-            description: string,
-            props: FixtureProps<TProps>,
-            wrapper?: React.ComponentType<TProps>,
-        ) => void,
-    ) => void,
-): ?$ReadOnly<mixed>;
-
-
-fixtures<TProps: {...}>(
-    options: $ReadOnly<FixturesOptions<TProps>>,
-    fn: (
-        fixture: (
-            description: string,
-            props: FixtureProps<TProps>,
-            wrapper?: React.ComponentType<TProps>,
-        ) => void,
-    ) => void,
-): ?$ReadOnly<mixed>;
+fixtures<
+    TComponent: React.ComponentType<any>,
+    TProps: React.ElementConfig<TComponent>,
+>(
+    Component: TComponent,
+): FixtureFn<TProps>;
 ```
 
-The `fixtures()` method is used to define a set of fixtures for a component. It provides a way to describe fixtures as one might describe unit tests. Fixtures are like stories in Storybook (and, if the fixtures framework is configured for storybook, will be stories).
-
-The return value provides the module exports that your fixture file should export. If your build system supports CommonJS syntax, this can be exported using `module.exports = returnValue`; however, if you need to use ESM syntax, you may need to do something like we do in [our Fixtures Framework example stories](/docs/testing-fixtures-basic--f-1).
-
-There are two ways to call the `fixtures()` function; with a component and callback, or with a set of [options](/docs/testing-fixtures-types-fixtureoptions--page) and callback.
+The `fixtures()` method is used to define a set of fixtures for a component. Each fixture is a story compatible with the CSF format used by Storybook.
 
-The second argument is a callback in which you should define your fixture susing the passed `fixture` function (the first and only argument of the callback). The `fixture` function takes two or three arguments:
+The method returned by `fixtures(Component)` is a strongly-typed call for generating a named story with the given args, and using the given wrapper component, if provided. See [our Fixtures Framework example stories](/docs/testing-fixtures-basic--f-1) for examples.
 
-- `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. This can be 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)).
-- `wrapper?: React.ComponentType<TProps>`: An optional component that will be rendered around 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)).
+The returned `fixture` function is of type [`FixtureFn<TProps>`](/docs/testing-fixtures-types-fixturefn--page).

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

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

@@ -0,0 +1,20 @@
+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)).