@khanacademy/wonder-blocks-testing 5.0.2 → 7.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@khanacademy/wonder-blocks-testing",
-    "version": "5.0.2",
+    "version": "7.0.0",
     "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,37 +16,23 @@ 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,
+): (
+    description: string,
+    props: FixtureProps<TProps>,
+    wrapper?: React.ComponentType<TProps>,
+) => void;
 ```
 
-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 `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 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).
+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.
 
-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 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 `fixture` 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. 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)).

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

@@ -17,9 +17,36 @@ 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 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.
+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),
+    }));
+```
+
+