@khanacademy/wonder-blocks-testing 2.0.7 → 3.0.1

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @khanacademy/wonder-blocks-testing
 
+## 3.0.1
+
+### Patch Changes
+
+-   6e4fbeed: Make sure simplified fixtures call copes with return values from React.forwardRef
+
+## 3.0.0
+
+### Major Changes
+
+-   9a43cc06: Allow for autogenerating titles in Storybook
+
+### Patch Changes
+
+-   222cb8db: Add simplified signature for common usage of `fixtures` function
+
+## 2.0.8
+
+### Patch Changes
+
+-   Updated dependencies [34407c4a]
+    -   @khanacademy/wonder-blocks-data@7.0.0
+
 ## 2.0.7
 
 ### Patch Changes

package/dist/es/index.js

@@ -118,7 +118,10 @@ class Adapter {
  */
 const getAdapter = (MountingComponent = null) => new Adapter("storybook", ({
   title,
-  description: groupDescription
+  description: groupDescription,
+  // We don't use the default title in Storybook as storybook
+  // will generate titles for us if we pass a nullish title.
+  getDefaultTitle: _
 }, adapterOptions, declaredFixtures) => {
   const templateMap = new WeakMap();
 
@@ -262,6 +265,38 @@ const combineOptions = (...toBeCombined) => {
   return combined;
 };
 
+const normalizeOptions = componentOrOptions => {
+  // To differentiate between a React component and a FixturesOptions object,
+  // we have to do some type checking.
+  //
+  // Alternatives I considered were:
+  // - Use an additional parameter for the options and then do an arg number
+  //   check, but that always makes typing a function harder and often breaks
+  //   types. I didn't want that battle today.
+  // - Use a tuple when providing component and options with the first element
+  //   being the component and the second being the options. However that
+  //   feels like an obscure API even though it's really easy to do the
+  //   typing.
+  if ( // Most React components, whether functional or class-based, are
+  // inherently functions in JavaScript, so a check for functions is
+  // usually sufficient.
+  typeof componentOrOptions === "function" || // However, the return of React.forwardRef is not a function,
+  // so we also have to cope with that.
+  // A forwardRef has $$typeof = Symbol(react.forward_ref) and a
+  // render function.
+  // $FlowIgnore[prop-missing]
+  typeof componentOrOptions.render === "function") {
+    return {
+      // $FlowIgnore[incompatible-return]
+      component: componentOrOptions
+    };
+  } // We can't test for React.ComponentType at runtime.
+  // Let's assume our simple heuristic above is sufficient.
+  // $FlowIgnore[incompatible-return]
+
+
+  return componentOrOptions;
+};
 /**
  * Describe a group of fixtures for a given component.
  *
@@ -280,7 +315,9 @@ const combineOptions = (...toBeCombined) => {
  * storybook, the popular framework, uses both default and named exports for
  * its interface.
  */
-const fixtures = (options, fn) => {
+
+
+const fixtures = (componentOrOptions, fn) => {
   var _additionalAdapterOpt;
 
   const {
@@ -293,11 +330,12 @@ const fixtures = (options, fn) => {
     description: groupDescription,
     defaultWrapper,
     additionalAdapterOptions
-  } = options; // 1. Create a new adapter group.
+  } = normalizeOptions(componentOrOptions); // 1. Create a new adapter group.
 
   const group = adapter.declareGroup({
-    title: title || component.displayName || component.name || "Component",
-    description: groupDescription
+    title,
+    description: groupDescription,
+    getDefaultTitle: () => component.displayName || component.name || "Component"
   }); // 2. Invoke fn with a function that can add a new fixture.
 
   const addFixture = (description, props, wrapper = null) => {

package/dist/index.js

@@ -247,7 +247,10 @@ __webpack_require__.r(__webpack_exports__);
  */
 const getAdapter = (MountingComponent = null) => new _adapter_js__WEBPACK_IMPORTED_MODULE_2__[/* Adapter */ "a"]("storybook", ({
   title,
-  description: groupDescription
+  description: groupDescription,
+  // We don't use the default title in Storybook as storybook
+  // will generate titles for us if we pass a nullish title.
+  getDefaultTitle: _
 }, adapterOptions, declaredFixtures) => {
   const templateMap = new WeakMap();
 
@@ -323,6 +326,38 @@ const getAdapter = (MountingComponent = null) => new _adapter_js__WEBPACK_IMPORT
 
 
 
+const normalizeOptions = componentOrOptions => {
+  // To differentiate between a React component and a FixturesOptions object,
+  // we have to do some type checking.
+  //
+  // Alternatives I considered were:
+  // - Use an additional parameter for the options and then do an arg number
+  //   check, but that always makes typing a function harder and often breaks
+  //   types. I didn't want that battle today.
+  // - Use a tuple when providing component and options with the first element
+  //   being the component and the second being the options. However that
+  //   feels like an obscure API even though it's really easy to do the
+  //   typing.
+  if ( // Most React components, whether functional or class-based, are
+  // inherently functions in JavaScript, so a check for functions is
+  // usually sufficient.
+  typeof componentOrOptions === "function" || // However, the return of React.forwardRef is not a function,
+  // so we also have to cope with that.
+  // A forwardRef has $$typeof = Symbol(react.forward_ref) and a
+  // render function.
+  // $FlowIgnore[prop-missing]
+  typeof componentOrOptions.render === "function") {
+    return {
+      // $FlowIgnore[incompatible-return]
+      component: componentOrOptions
+    };
+  } // We can't test for React.ComponentType at runtime.
+  // Let's assume our simple heuristic above is sufficient.
+  // $FlowIgnore[incompatible-return]
+
+
+  return componentOrOptions;
+};
 /**
  * Describe a group of fixtures for a given component.
  *
@@ -341,7 +376,9 @@ const getAdapter = (MountingComponent = null) => new _adapter_js__WEBPACK_IMPORT
  * storybook, the popular framework, uses both default and named exports for
  * its interface.
  */
-const fixtures = (options, fn) => {
+
+
+const fixtures = (componentOrOptions, fn) => {
   var _additionalAdapterOpt;
 
   const {
@@ -354,11 +391,12 @@ const fixtures = (options, fn) => {
     description: groupDescription,
     defaultWrapper,
     additionalAdapterOptions
-  } = options; // 1. Create a new adapter group.
+  } = normalizeOptions(componentOrOptions); // 1. Create a new adapter group.
 
   const group = adapter.declareGroup({
-    title: title || component.displayName || component.name || "Component",
-    description: groupDescription
+    title,
+    description: groupDescription,
+    getDefaultTitle: () => component.displayName || component.name || "Component"
   }); // 2. Invoke fn with a function that can add a new fixture.
 
   const addFixture = (description, props, wrapper = null) => {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@khanacademy/wonder-blocks-testing",
-    "version": "2.0.7",
+    "version": "3.0.1",
     "design": "v1",
     "publishConfig": {
         "access": "public"
@@ -14,7 +14,7 @@
     },
     "dependencies": {
         "@babel/runtime": "^7.16.3",
-        "@khanacademy/wonder-blocks-data": "^6.0.1"
+        "@khanacademy/wonder-blocks-data": "^7.0.0"
     },
     "peerDependencies": {
         "@khanacademy/wonder-stuff-core": "^0.1.2",

package/src/fixtures/__tests__/fixtures.test.js

@@ -1,4 +1,5 @@
 // @flow
+import * as React from "react";
 import * as SetupModule from "../setup.js";
 import * as CombineOptionsModule from "../combine-options.js";
 import {fixtures} from "../fixtures.js";
@@ -11,6 +12,28 @@ describe("#fixtures", () => {
         jest.clearAllMocks();
     });
 
+    it("should declare a group on the configured adapter based off the given component", () => {
+        // Arrange
+        const fakeGroup = {
+            closeGroup: jest.fn(),
+        };
+        const adapter = {
+            declareGroup: jest.fn().mockReturnValue(fakeGroup),
+            name: "testadapter",
+        };
+        jest.spyOn(SetupModule, "getConfiguration").mockReturnValue({
+            adapter,
+        });
+
+        // Act
+        fixtures(() => "COMPONENT", jest.fn());
+
+        // Assert
+        expect(adapter.declareGroup).toHaveBeenCalledWith({
+            getDefaultTitle: expect.any(Function),
+        });
+    });
+
     it("should declare a group on the configured adapter with the given title and description", () => {
         // Arrange
         const fakeGroup = {
@@ -38,6 +61,7 @@ describe("#fixtures", () => {
         expect(adapter.declareGroup).toHaveBeenCalledWith({
             title: "TITLE",
             description: "DESCRIPTION",
+            getDefaultTitle: expect.any(Function),
         });
     });
 
@@ -63,11 +87,11 @@ describe("#fixtures", () => {
             },
             jest.fn(),
         );
+        const {getDefaultTitle} = adapter.declareGroup.mock.calls[0][0];
+        const result = getDefaultTitle();
 
         // Assert
-        expect(adapter.declareGroup).toHaveBeenCalledWith({
-            title: "DISPLAYNAME",
-        });
+        expect(result).toBe("DISPLAYNAME");
     });
 
     it("should default the title to the component.name in the absence of component.displayName", () => {
@@ -87,17 +111,12 @@ describe("#fixtures", () => {
         };
 
         // Act
-        fixtures(
-            {
-                component,
-            },
-            jest.fn(),
-        );
+        fixtures(component, jest.fn());
+        const {getDefaultTitle} = adapter.declareGroup.mock.calls[0][0];
+        const result = getDefaultTitle();
 
         // Assert
-        expect(adapter.declareGroup).toHaveBeenCalledWith({
-            title: "FUNCTIONNAME",
-        });
+        expect(result).toBe("FUNCTIONNAME");
     });
 
     it("should default the title to 'Component' in the absence of component.name", () => {
@@ -114,17 +133,12 @@ describe("#fixtures", () => {
         });
 
         // Act
-        fixtures(
-            {
-                component: ({}: any),
-            },
-            jest.fn(),
-        );
+        fixtures(() => "test", jest.fn());
+        const {getDefaultTitle} = adapter.declareGroup.mock.calls[0][0];
+        const result = getDefaultTitle();
 
         // Assert
-        expect(adapter.declareGroup).toHaveBeenCalledWith({
-            title: "Component",
-        });
+        expect(result).toBe("Component");
     });
 
     it("should invoke the passed fn with function argument", () => {
@@ -271,7 +285,7 @@ describe("#fixtures", () => {
     });
 
     describe("injected fixture fn", () => {
-        it("should call group.declareFixture with description and props getter", () => {
+        it("should call group.declareFixture with description, props getter, and component", () => {
             // Arrange
             const fakeGroup = {
                 declareFixture: jest.fn(),
@@ -306,6 +320,36 @@ describe("#fixtures", () => {
             });
         });
 
+        it("should call group.declareFixture with component if component is forward ref", () => {
+            // Arrange
+            const fakeGroup = {
+                declareFixture: jest.fn(),
+                closeGroup: jest.fn(),
+            };
+            const adapter = {
+                declareGroup: jest.fn().mockReturnValue(fakeGroup),
+                name: "testadapter",
+            };
+            jest.spyOn(SetupModule, "getConfiguration").mockReturnValue({
+                adapter,
+            });
+            const component = React.forwardRef((props, ref) => (
+                <div {...props} ref={ref} />
+            ));
+
+            // Act
+            fixtures(component, (fixture) => {
+                fixture("FIXTURE_DESCRIPTION", {these: "areProps"});
+            });
+
+            // Assert
+            expect(fakeGroup.declareFixture).toHaveBeenCalledWith({
+                description: "FIXTURE_DESCRIPTION",
+                getProps: expect.any(Function),
+                component,
+            });
+        });
+
         it("should pass wrapper component to group.declareFixture", () => {
             // Arrange
             const fakeGroup = {

package/src/fixtures/adapters/__tests__/adapter-group.test.js

@@ -12,6 +12,9 @@ describe("AdapterGroup", () => {
                 new AdapterGroup(badCloseGroupFn, {
                     title: "TITLE",
                     description: null,
+                    getDefaultTitle: () => {
+                        throw new Error("NOT IMPLEMENTED");
+                    },
                 });
 
             expect(act).toThrowErrorMatchingInlineSnapshot(
@@ -40,6 +43,9 @@ describe("AdapterGroup", () => {
             const groupOptions = {
                 title: "TITLE",
                 description: null,
+                getDefaultTitle: () => {
+                    throw new Error("NOT IMPLEMENTED");
+                },
             };
             const adapterGroup = new AdapterGroup(closeGroupFn, groupOptions);
 
@@ -56,6 +62,9 @@ describe("AdapterGroup", () => {
             const groupOptions = {
                 title: "TITLE",
                 description: null,
+                getDefaultTitle: () => {
+                    throw new Error("NOT IMPLEMENTED");
+                },
             };
             const adapterSpecificOptions = {
                 adapterSpecificOption: "adapterSpecificOption",
@@ -79,6 +88,9 @@ describe("AdapterGroup", () => {
             const groupOptions = {
                 title: "TITLE",
                 description: "DESCRIPTION",
+                getDefaultTitle: () => {
+                    throw new Error("NOT IMPLEMENTED");
+                },
             };
             const adapterGroup = new AdapterGroup(closeGroupFn, groupOptions);
             const fixture = {
@@ -103,6 +115,9 @@ describe("AdapterGroup", () => {
             const groupOptions = {
                 title: "TITLE",
                 description: null,
+                getDefaultTitle: () => {
+                    throw new Error("NOT IMPLEMENTED");
+                },
             };
             const adapterGroup = new AdapterGroup(closeGroupFn, groupOptions);
             adapterGroup.closeGroup();
@@ -126,6 +141,9 @@ describe("AdapterGroup", () => {
                 const groupOptions = {
                     title: "TITLE",
                     description: null,
+                    getDefaultTitle: () => {
+                        throw new Error("NOT IMPLEMENTED");
+                    },
                 };
                 const adapterGroup = new AdapterGroup(
                     closeGroupFn,
@@ -147,6 +165,9 @@ describe("AdapterGroup", () => {
             const groupOptions = {
                 title: "TITLE",
                 description: "DESCRIPTION",
+                getDefaultTitle: () => {
+                    throw new Error("NOT IMPLEMENTED");
+                },
             };
             const adapterGroup = new AdapterGroup(closeGroupFn, groupOptions);
             const fixture1 = {
@@ -178,6 +199,9 @@ describe("AdapterGroup", () => {
             const groupOptions = {
                 title: "TITLE",
                 description: null,
+                getDefaultTitle: () => {
+                    throw new Error("NOT IMPLEMENTED");
+                },
             };
             const adapterGroup = new AdapterGroup(closeGroupFn, groupOptions);
             adapterGroup.closeGroup();

package/src/fixtures/adapters/__tests__/adapter.test.js

@@ -56,6 +56,9 @@ describe("Adapter", () => {
             const options = {
                 title: "group_title",
                 description: "group_description",
+                getDefaultTitle: () => {
+                    throw new Error("NOT IMPLEMENTED");
+                },
             };
             const adapterGroupSpy = jest
                 .spyOn(AdapterGroupModule, "AdapterGroup")
@@ -82,6 +85,9 @@ describe("Adapter", () => {
             const result = adapter.declareGroup({
                 title: "group_title",
                 description: "group_description",
+                getDefaultTitle: () => {
+                    throw new Error("NOT IMPLEMENTED");
+                },
             });
 
             // Assert

package/src/fixtures/adapters/storybook.js

@@ -26,7 +26,7 @@ export type StorybookOptions = {|
 |};
 
 type DefaultExport = {|
-    title: string,
+    title?: ?string,
     ...StorybookOptions,
 |};
 
@@ -47,6 +47,9 @@ export const getAdapter: AdapterFactory<StorybookOptions, Exports<any>> = (
             {
                 title,
                 description: groupDescription,
+                // We don't use the default title in Storybook as storybook
+                // will generate titles for us if we pass a nullish title.
+                getDefaultTitle: _,
             }: $ReadOnly<AdapterGroupOptions>,
             adapterOptions: ?$ReadOnly<StorybookOptions>,
             declaredFixtures: $ReadOnlyArray<AdapterFixtureOptions<TProps>>,

package/src/fixtures/fixtures.basic.stories.js

@@ -3,7 +3,7 @@ import * as React from "react";
 
 import {setupFixtures, fixtures, adapters} from "../index.js";
 
-// Normally would call setup from the storybook.main.js for a project.
+// Normally would call setup from the storybook.preview.js for a project.
 setupFixtures({
     adapter: adapters.storybook(),
 });

package/src/fixtures/fixtures.defaultwrapper.stories.js

@@ -3,7 +3,7 @@ import * as React from "react";
 
 import {setupFixtures, fixtures, adapters} from "../index.js";
 
-// Normally would call setup from the storybook.main.js for a project.
+// Normally would call setup from the storybook.preview.js for a project.
 setupFixtures({
     adapter: adapters.storybook(),
 });

package/src/fixtures/fixtures.js

@@ -9,6 +9,45 @@ type FixtureProps<TProps: {...}> =
     | $ReadOnly<TProps>
     | ((options: $ReadOnly<GetPropsOptions>) => $ReadOnly<TProps>);
 
+const normalizeOptions = <TProps: {...}>(
+    componentOrOptions:
+        | React.ComponentType<TProps>
+        | $ReadOnly<FixturesOptions<TProps>>,
+): $ReadOnly<FixturesOptions<TProps>> => {
+    // To differentiate between a React component and a FixturesOptions object,
+    // we have to do some type checking.
+    //
+    // Alternatives I considered were:
+    // - Use an additional parameter for the options and then do an arg number
+    //   check, but that always makes typing a function harder and often breaks
+    //   types. I didn't want that battle today.
+    // - Use a tuple when providing component and options with the first element
+    //   being the component and the second being the options. However that
+    //   feels like an obscure API even though it's really easy to do the
+    //   typing.
+    if (
+        // Most React components, whether functional or class-based, are
+        // inherently functions in JavaScript, so a check for functions is
+        // usually sufficient.
+        typeof componentOrOptions === "function" ||
+        // However, the return of React.forwardRef is not a function,
+        // so we also have to cope with that.
+        // A forwardRef has $$typeof = Symbol(react.forward_ref) and a
+        // render function.
+        // $FlowIgnore[prop-missing]
+        typeof componentOrOptions.render === "function"
+    ) {
+        return {
+            // $FlowIgnore[incompatible-return]
+            component: componentOrOptions,
+        };
+    }
+    // We can't test for React.ComponentType at runtime.
+    // Let's assume our simple heuristic above is sufficient.
+    // $FlowIgnore[incompatible-return]
+    return componentOrOptions;
+};
+
 /**
  * Describe a group of fixtures for a given component.
  *
@@ -28,7 +67,9 @@ type FixtureProps<TProps: {...}> =
  * its interface.
  */
 export const fixtures = <TProps: {...}>(
-    options: $ReadOnly<FixturesOptions<TProps>>,
+    componentOrOptions:
+        | React.ComponentType<TProps>
+        | $ReadOnly<FixturesOptions<TProps>>,
     fn: (
         fixture: (
             description: string,
@@ -38,18 +79,21 @@ export const fixtures = <TProps: {...}>(
     ) => void,
 ): ?$ReadOnly<mixed> => {
     const {adapter, defaultAdapterOptions} = getConfiguration();
+
     const {
         title,
         component,
         description: groupDescription,
         defaultWrapper,
         additionalAdapterOptions,
-    } = options;
+    } = normalizeOptions(componentOrOptions);
 
     // 1. Create a new adapter group.
     const group = adapter.declareGroup<TProps>({
-        title: title || component.displayName || component.name || "Component",
+        title,
         description: groupDescription,
+        getDefaultTitle: () =>
+            component.displayName || component.name || "Component",
     });
 
     // 2. Invoke fn with a function that can add a new fixture.

package/src/fixtures/types.js

@@ -81,13 +81,22 @@ export type AdapterFixtureOptions<TProps: {...}> = {|
 export type AdapterGroupOptions = {|
     /**
      * 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,
+    +title: ?string,
 
     /**
      * Description of the group.
      */
     +description: ?string,
+
+    /**
+     * Function that will generate a default title if an adapter cannot
+     * generate its own.
+     */
+    +getDefaultTitle: () => string,
 |};
 
 /**