@khanacademy/wonder-blocks-testing 6.1.0 → 7.0.2

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

@@ -1,23 +1,14 @@
 // @flow
 import * as React from "react";
 
-import {
-    setupFixtures,
-    fixtures,
-    fixtureAdapters as adapters,
-} from "../index.js";
-
-// Normally would call setup from the storybook.preview.js for a project.
-setupFixtures({
-    adapter: adapters.storybook(),
-});
+import {fixtures} from "../index.js";
 
 type Props = {|
     propA: string,
     propB?: string,
 |};
 
-const MyComponent = (props: Props) =>
+const MyComponent = (props: Props): React.Node =>
     `I am a component. Here are my props: ${JSON.stringify(props, null, 2)}`;
 
 const Wrapper = (props) => (
@@ -28,46 +19,35 @@ const Wrapper = (props) => (
     </>
 );
 
-const stories: Array<mixed> = Object.values(
-    fixtures<typeof MyComponent, _>(
-        {
-            component: MyComponent,
-            title: "Testing / Fixtures / Basic",
-        },
-        (fixture) => {
-            fixture("This is a fixture with some regular props", {
-                propA: "this is a prop",
-                propB: "this is another",
-            });
+const fixture = fixtures(MyComponent);
 
-            fixture(
-                "This is a fixture with props from functions, and a bit of logging",
-                ({log}) => {
-                    log(
-                        "This is a log from a fixture during props generation",
-                        {
-                            and: "some data",
-                        },
-                    );
-                    return {
-                        propA: "prop was made from a function",
-                    };
-                },
-            );
+export const F1: mixed = fixture("This is a fixture with some regular props", {
+    propA: "this is a prop",
+    propB: "this is another",
+});
+
+export const F2: mixed = fixture(
+    "This is a fixture with props from functions, and a bit of logging",
+    ({log}) => {
+        log("This is a log from a fixture during props generation", {
+            and: "some data",
+        });
+        return {
+            propA: "prop was made from a function",
+        };
+    },
+);
 
-            fixture(
-                "This fixture uses a custom wrapper",
-                {
-                    propA: "some props again",
-                    propB: "this one",
-                },
-                Wrapper,
-            );
-        },
-    ) ?? {},
+export const F3: mixed = fixture(
+    "This fixture uses a custom wrapper",
+    {
+        propA: "some props again",
+        propB: "this one",
+    },
+    Wrapper,
 );
 
-export default stories[0];
-export const F1 = stories[1];
-export const F2 = stories[2];
-export const F3 = stories[3];
+export default {
+    title: "Testing / Fixtures / Basic",
+    component: MyComponent,
+};

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

@@ -1,18 +1,12 @@
 // @flow
 import * as React from "react";
 
-import {
-    setupFixtures,
-    fixtures,
-    fixtureAdapters as adapters,
-} from "../index.js";
+import {fixtures} from "../index.js";
 
-// Normally would call setup from the storybook.preview.js for a project.
-setupFixtures({
-    adapter: adapters.storybook(),
-});
+type Props = {...};
 
-const MyComponent = (props) => `My props: ${JSON.stringify(props, null, 2)}`;
+const MyComponent = (props: Props) =>
+    `My props: ${JSON.stringify(props, null, 2)}`;
 
 const Wrapper = (props) => (
     <>
@@ -22,7 +16,7 @@ const Wrapper = (props) => (
     </>
 );
 
-const DefaultWrapper = (props) => (
+const DefaultWrapper = (props: Props): React.Node => (
     <>
         DefaultWrapper &gt;&gt;&gt;
         <MyComponent {...props} />
@@ -30,34 +24,26 @@ const DefaultWrapper = (props) => (
     </>
 );
 
-const stories: Array<mixed> = Object.values(
-    fixtures<typeof MyComponent, _>(
-        {
-            component: MyComponent,
-            title: "Testing / Fixtures / DefaultWrapper",
-            defaultWrapper: DefaultWrapper,
-        },
-        (fixture) => {
-            fixture(
-                "This is a fixture with some regular props and the default wrapper",
-                {
-                    see: "this is a prop",
-                    and: "this is another",
-                },
-            );
-
-            fixture(
-                "This fixture uses a custom wrapper",
-                {
-                    just: "some props again",
-                    like: "this one",
-                },
-                Wrapper,
-            );
-        },
-    ) ?? {},
+const fixture = fixtures(DefaultWrapper);
+
+export const F1: mixed = fixture(
+    "This is a fixture with some regular props and the default wrapper",
+    {
+        see: "this is a prop",
+        and: "this is another",
+    },
+);
+
+export const F2: mixed = fixture(
+    "This fixture uses a custom wrapper",
+    {
+        just: "some props again",
+        like: "this one",
+    },
+    Wrapper,
 );
 
-export default stories[0];
-export const F1 = stories[1];
-export const F2 = stories[2];
+export default {
+    title: "Testing / Fixtures / DefaultWrapper",
+    component: DefaultWrapper,
+};

package/src/fixtures/fixtures.js

@@ -1,55 +1,8 @@
 // @flow
 import * as React from "react";
-import {getConfiguration} from "./setup.js";
-import {combineOptions} from "./combine-options.js";
+import {action} from "@storybook/addon-actions";
 
-import type {FixturesOptions, GetPropsOptions} from "./types.js";
-
-type FixtureProps<TProps: {...}> =
-    | $ReadOnly<TProps>
-    | ((options: $ReadOnly<GetPropsOptions>) => $ReadOnly<TProps>);
-
-const normalizeOptions = <
-    TComponent: React.ComponentType<any>,
-    TProps: React.ElementConfig<TComponent>,
->(
-    componentOrOptions:
-        | TComponent
-        | $ReadOnly<FixturesOptions<TComponent, TProps>>,
-): $ReadOnly<FixturesOptions<TComponent, 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;
-};
+import type {FixtureFn, FixtureProps} from "./types.js";
 
 /**
  * Describe a group of fixtures for a given component.
@@ -57,71 +10,65 @@ const normalizeOptions = <
  * Only one `fixtures` call should be used per fixture file as it returns
  * the exports for that file.
  *
- * @param {FixtureOptions<TProps>} options Options describing the
+ * @param {component: React.ComponentType<any>} options Options describing the
  * fixture group.
  * @param {FixtureFn<TProps> => void} fn A function that provides a `fixture`
  * function for defining fixtures.
- * @returns {Exports} The object to be exported as `module.exports`.
- *
- * TODO(somewhatabstract): Determine a way around this requirement so we
- * can support named exports and default exports via the adapters in a
- * deterministic way. Currently this is imposed on us because of how
- * storybook, the popular framework, uses both default and named exports for
- * its interface.
+ * @returns {(
+ *    description: string,
+ *    props: FixtureProps<TProps>,
+ *    wrapper?: React.ComponentType<TProps>,
+ * ) => mixed} A function to create a CSF compatible story.
  */
 export const fixtures = <
     TComponent: React.ComponentType<any>,
     TProps: React.ElementConfig<TComponent>,
 >(
-    componentOrOptions:
-        | TComponent
-        | $ReadOnly<FixturesOptions<TComponent, TProps>>,
-    fn: (
-        fixture: (
-            description: string,
-            props: FixtureProps<TProps>,
-            wrapper?: React.ComponentType<TProps>,
-        ) => void,
-    ) => void,
-): ?$ReadOnly<mixed> => {
-    const {adapter, defaultAdapterOptions} = getConfiguration();
+    Component: TComponent,
+): FixtureFn<TProps> => {
+    const templateMap = new WeakMap();
+    // We use this to make sure each story gets a unique name.
+    let storyNumber = 1;
 
-    const {
-        title,
-        component,
-        description: groupDescription,
-        defaultWrapper,
-        additionalAdapterOptions,
-    } = normalizeOptions<TComponent, TProps>(componentOrOptions);
+    const getPropsOptions = {
+        log: (message, ...args) => action(message)(...args),
+        logHandler: action,
+    };
 
-    // 1. Create a new adapter group.
-    const group = adapter.declareGroup<TProps>({
-        title,
-        description: groupDescription,
-        getDefaultTitle: () =>
-            component.displayName || component.name || "Component",
-    });
+    const makeStory = (
+        description: string,
+        props: FixtureProps<TProps>,
+        wrapper: ?React.ComponentType<TProps> = null,
+    ): mixed => {
+        const storyName = `${storyNumber++} ${description}`;
+        const getProps = (options) =>
+            typeof props === "function" ? props(options) : props;
 
-    // 2. Invoke fn with a function that can add a new fixture.
-    const addFixture = (description, props, wrapper = null): void => {
-        group.declareFixture({
-            description,
-            getProps: (options) =>
-                typeof props === "function" ? props(options) : props,
-            component: wrapper ?? defaultWrapper ?? component,
-        });
-    };
-    fn(addFixture);
+        const RealComponent = wrapper || Component;
 
-    // 3. Combine the adapter options from the fixture group with the
-    //    defaults from our setup.
-    const groupAdapterOverrides =
-        additionalAdapterOptions?.[adapter.name] ?? {};
-    const combinedAdapterOptions = combineOptions(
-        defaultAdapterOptions,
-        groupAdapterOverrides,
-    );
+        // We create a “template” of how args map to rendering
+        // for each type of component as the component here could
+        // be the component under test, or wrapped in a wrapper
+        // component. We don't use decorators for the wrapper
+        // because we may not be in a storybook context and it
+        // keeps the framework API simpler this way.
+        let Template = templateMap.get((RealComponent: any));
+        if (Template == null) {
+            Template = (args) => <RealComponent {...args} />;
+            templateMap.set((RealComponent: any), Template);
+        }
 
-    // 4. Call close on the group and return the result.
-    return group.closeGroup(combinedAdapterOptions);
+        // Each story that shares that component then reuses that
+        // template.
+        const story = Template.bind({});
+        story.args = getProps(getPropsOptions);
+        // Adding a story name here means that we don't have to
+        // care about naming the exports correctly, if we don't
+        // want (useful if we need to autogenerate or manually
+        // expose ESM exports).
+        story.storyName = storyName;
+
+        return story;
+    };
+    return makeStory;
 };

package/src/fixtures/types.js

@@ -1,6 +1,5 @@
 // @flow
 import * as React from "react";
-import type {StorybookOptions} from "./adapters/storybook.js";
 
 /**
  * Options injected to the function that returns the fixture props.
@@ -19,194 +18,29 @@ export type GetPropsOptions = {|
     logHandler: (name: string) => (...args: Array<any>) => void,
 |};
 
-/**
- * Adapter options keyed by the adapter name.
- */
-export type FixturesAdapterOptions = {|
-    storybook?: StorybookOptions,
-    [adapterName: string]: {...},
-|};
+export type FixtureProps<TProps: {...}> =
+    | $ReadOnly<TProps>
+    | ((options: $ReadOnly<GetPropsOptions>) => $ReadOnly<TProps>);
 
 /**
- * Options to describe a collection of fixtures.
+ * A function for defining a fixture.
  */
-export type FixturesOptions<
-    TComponent: React.ComponentType<any>,
-    TProps: React.ElementConfig<TComponent>,
-> = {|
-    /**
-     * The component being tested by the fixtures.
-     */
-    component: TComponent,
-
+export type FixtureFn<TProps: {...}> = (
     /**
-     * Optional title of the fixture collection.
-     *
-     * Adapters may enforce a title, otherwise the component name is used.
+     * The name of the fixture.
      */
-    title?: string,
+    description: string,
 
     /**
-     * Optional description of the fixture collection.
+     * The props for the fixture or a function that returns the props.
+     * The function is injected with an API to facilitate logging.
      */
-    description?: string,
+    props: FixtureProps<TProps>,
 
     /**
-     * Optional default wrapper to apply around the component under test.
+     * An alternative component to render for the fixture.
+     * Useful if the fixture requires some additional setup for testing the
+     * component.
      */
-    defaultWrapper?: React.ComponentType<TProps>,
-
-    /**
-     * Additional options to apply to specific adapters.
-     */
-    additionalAdapterOptions?: FixturesAdapterOptions,
-|};
-
-/**
- * Describes a single fixture.
- */
-export type FixturesAdapterFixtureOptions<TProps: {...}> = {|
-    /**
-     * Description of the fixture.
-     */
-    +description: string,
-
-    /**
-     * Method to obtain props for the fixture.
-     */
-    +getProps: (options: $ReadOnly<GetPropsOptions>) => $ReadOnly<TProps>,
-
-    /**
-     * The component to render for this fixture.
-     */
-    +component: React.ComponentType<TProps>,
-|};
-
-// TODO(somewhatabstract): Allow for adapters to extend group/fixture options
-// with specific support. For example, storybook subcomponents, etc.?
-
-/**
- * Describes a group of fixtures.
- */
-export type FixturesAdapterGroupOptions = {|
-    /**
-     * 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,
-
-    /**
-     * Description of the group.
-     */
-    +description: ?string,
-
-    /**
-     * Function that will generate a default title if an adapter cannot
-     * generate its own.
-     */
-    +getDefaultTitle: () => string,
-|};
-
-/**
- * Describes props that an adapter will inject for custom mounting components.
- */
-export type CustomMountProps<TProps: {...}> = {|
-    /**
-     * The fixture props for the component to be rendered.
-     */
-    props: TProps,
-
-    /**
-     * The component to render.
-     */
-    component: React.ComponentType<TProps>,
-
-    /**
-     * The log callback for logging information.
-     */
-    log: (message: string, ...args: Array<any>) => mixed,
-|};
-
-/**
- * Declares the API for describing a fixture group provided by an adapter.
- */
-export interface FixturesAdapterGroup<
-    TProps: {...},
-    TAdapterOptions: {...},
-    TAdapterExports: {...},
-> {
-    /**
-     * Declare a fixture.
-     */
-    declareFixture(
-        options: $ReadOnly<FixturesAdapterFixtureOptions<TProps>>,
-    ): void;
-
-    /**
-     * Close the group and obtain the exports, if the adapter requires any.
-     *
-     * @param {Options} adapterOptions Some options to pass to the adapter.
-     * Allows callers to tailor things to a specific adapter. How these options
-     * are used is adapter-specific.
-     *
-     * @returns {?Exports} The exports that the adapter requires fixture files
-     * to export.
-     */
-    closeGroup(
-        adapterOptions: $ReadOnly<Partial<TAdapterOptions>>,
-    ): ?$ReadOnly<TAdapterExports>;
-}
-
-/**
- * Declares the API for an adapter.
- */
-export interface FixturesAdapter<
-    TAdapterOptions: {...},
-    TAdapterExports: {...},
-> {
-    /**
-     * The name of the adapter.
-     */
-    get name(): string;
-
-    /**
-     * Declare a fixture group.
-     *
-     * @returns {AdapterGroup<TProps, TAdapterOptions, TAdapterExports>} The
-     * declared group.
-     */
-    declareGroup<TProps: {...}>(
-        options: $ReadOnly<FixturesAdapterGroupOptions>,
-    ): FixturesAdapterGroup<TProps, TAdapterOptions, TAdapterExports>;
-}
-
-/**
- * Describes the configuration for the fixture framework.
- */
-export type FixturesConfiguration<
-    TAdapterOptions: {...},
-    TAdapterExports: {...},
-> = {|
-    /**
-     * The adapter to use for declaring fixtures.
-     */
-    +adapter: FixturesAdapter<TAdapterOptions, TAdapterExports>,
-
-    /**
-     * Default options to apply to every fixture group.
-     *
-     * Each top-level option in this object will be merged with the equivalent
-     * top-level option that a specific fixture requests. Where collisions
-     * occur, the fixture options win.
-     */
-    +defaultAdapterOptions?: $ReadOnly<Partial<TAdapterOptions>>,
-|};
-
-export type FixturesAdapterFactory<
-    TAdapterOptions: {...},
-    TAdapterExports: {...},
-> = (
-    MountingComponent: ?React.ComponentType<CustomMountProps<any>>,
-) => FixturesAdapter<TAdapterOptions, TAdapterExports>;
+    wrapper?: React.ComponentType<TProps>,
+) => mixed;

package/src/index.js

@@ -1,19 +1,10 @@
 // @flow
 
 // Fixtures framework
-export * as fixtureAdapters from "./fixtures/adapters/adapters.js";
 export {fixtures} from "./fixtures/fixtures.js";
-export {setup as setupFixtures} from "./fixtures/setup.js";
 export type {
-    CustomMountProps,
-    FixturesAdapter,
-    FixturesAdapterFactory,
-    FixturesAdapterFixtureOptions,
-    FixturesAdapterGroup,
-    FixturesAdapterGroupOptions,
-    FixturesAdapterOptions,
-    FixturesConfiguration,
-    FixturesOptions,
+    FixtureFn,
+    FixtureProps,
     GetPropsOptions,
 } from "./fixtures/types.js";
 

package/src/__docs__/exports.fixture-adapters.stories.mdx

@@ -1,49 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-
-<Meta
-    title="Testing / Fixtures / Exports / fixtureAdapters"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# fixtureAdapters
-
-```ts
-type StoryContext = {|
-    args: $ReadOnly<any>,
-    argTypes: $ReadOnly<any>,
-    globals: $ReadOnlyArray<any>,
-    hooks: $ReadOnlyArray<any>,
-    parameters: $ReadOnly<any>,
-    viewMode: mixed,
-|};
-
-type StorybookOptions = {|
-    decorators?: Array<
-        (story: React.ComponentType<any>, context: StoryContext) => React.Node,
-    >,
-    parameters?: $ReadOnly<any>,
-|};
-
-type DefaultExport = {|
-    title?: ?string,
-    ...StorybookOptions,
-|};
-
-type Exports<TProps: {...}> = {|
-    default: DefaultExport,
-    [story: string]: React.ComponentType<TProps>,
-|};
-
-
-const fixtureAdapters = {
-    storybook: AdapterFactory<StorybookOptions, Exports<any>>,
-}
-```
-
-These are the adapters available for use with the fixtures framework. If an adapter is not listed here for the framework you want, you can create your own conforming to the [`FixturesAdapterFactory`](/docs/testing-fixtures-types-fixturesadapterfactory--page) type.
-
-To configure the fixtures framework, use an adapter with the [`setupFixtures`](/docs/testing-fixtures-exports-setupfixtures--page) function.

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

@@ -1,22 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-
-<Meta
-    title="Testing / Fixtures / Exports / setupFixtures()"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# setupFixtures()
-
-```ts
-setupFixtures<TAdapterOptions: {...}, TAdapterExports: {...}>(
-    configuration: $ReadOnly<
-        FixturesConfiguration<TAdapterOptions, TAdapterExports>,
-    >,
-);
-```
-
-This method configures the fixtures framework so that it can adapt defined fixtures to the framework that is to be supported. The configuration is of type [`FixturesConfiguration`](/docs/testing-fixtures-types-fixturesconfiguration--page).