@khanacademy/wonder-blocks-testing 0.0.2

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

@@ -0,0 +1,88 @@
+// @flow
+import type {
+    AdapterGroup as AdapterGroupInterface,
+    AdapterGroupOptions,
+    AdapterFixtureOptions,
+} from "../types.js";
+
+export type CloseGroupFn<TProps: {...}, Options: {...}, Exports: {...}> = (
+    options: $ReadOnly<AdapterGroupOptions>,
+    adapterOptions: ?$ReadOnly<Options>,
+    declaredFixtures: $ReadOnlyArray<AdapterFixtureOptions<TProps>>,
+) => ?$ReadOnly<Exports>;
+
+/**
+ * Simple adapter group implementation.
+ */
+export class AdapterGroup<TProps: {...}, Options: {...}, Exports: {...}>
+    implements AdapterGroupInterface<TProps, Options, Exports>
+{
+    _closeGroupFn: ?CloseGroupFn<TProps, Options, Exports>;
+    +_fixtures: Array<AdapterFixtureOptions<TProps>>;
+    +_options: $ReadOnly<AdapterGroupOptions>;
+
+    /**
+     * Create an adapter group.
+     *
+     * @param {CloseGroupFn<TProps, Options, Exports>} closeGroupFn A function
+     * to invoke when the group is closed.
+     * @param {AdapterGroupOptions} options The options for the group.
+     */
+    constructor(
+        closeGroupFn: CloseGroupFn<TProps, Options, Exports>,
+        options: $ReadOnly<AdapterGroupOptions>,
+    ) {
+        if (typeof closeGroupFn !== "function") {
+            throw new TypeError("closeGroupFn must be a function");
+        }
+        if (typeof options !== "object" || options === null) {
+            throw new TypeError("options must be an object");
+        }
+        this._closeGroupFn = closeGroupFn;
+        this._options = options;
+        this._fixtures = [];
+    }
+
+    /**
+     * Close the group.
+     *
+     * This declares that no more fixtures are to be added to the group,
+     * and will call the parent adapter with the declared fixtures so that they
+     * can be adapted for the target fixture framework, such as Storybook.
+     */
+    +closeGroup: (
+        adapterOptions: ?$ReadOnly<Partial<Options>>,
+    ) => ?$ReadOnly<Exports> = (adapterOptions = null) => {
+        if (this._closeGroupFn == null) {
+            throw new Error("Group already closed");
+        }
+
+        try {
+            return this._closeGroupFn(
+                this._options,
+                adapterOptions,
+                this._fixtures,
+            );
+        } finally {
+            this._closeGroupFn = null;
+        }
+    };
+
+    /**
+     * Declare a fixture within the group.
+     *
+     * @param {AdapterFixtureOptions<Config>} fixtureOptions The options
+     * describing the fixture.
+     */
+    +declareFixture: (
+        options: $ReadOnly<AdapterFixtureOptions<TProps>>,
+    ) => void = (options) => {
+        if (typeof options !== "object" || options === null) {
+            throw new TypeError("options must be an object");
+        }
+        if (this._closeGroupFn == null) {
+            throw new Error("Cannot declare fixtures after closing the group");
+        }
+        this._fixtures.push(options);
+    };
+}

package/src/fixtures/adapters/adapter.js

@@ -0,0 +1,63 @@
+// @flow
+import {AdapterGroup, type CloseGroupFn} from "./adapter-group.js";
+import type {
+    Adapter as AdapterInterface,
+    AdapterGroup as AdapterGroupInterface,
+    AdapterGroupOptions,
+} from "../types.js";
+
+/**
+ * Class for implementing a custom adapter.
+ */
+export class Adapter<Options: {...}, Exports: {...}>
+    implements AdapterInterface<Options, Exports>
+{
+    +_name: string;
+    +_closeGroupFn: CloseGroupFn<any, Options, Exports>;
+
+    /**
+     * @param {string} name The name of the adapter.
+     * @param {CloseGroupFn<any, Options, Exports>} closeGroupFn The function
+     * an adapter group should call when the group is closed. This is invoked
+     * by an adapter group when it is closed. This function is where an
+     * adapter implements the logic to generate the actual fixtures for the
+     * adapter's target framework.
+     */
+    constructor(
+        name: string,
+        closeGroupFn: CloseGroupFn<any, Options, Exports>,
+    ) {
+        if (typeof name !== "string") {
+            throw new TypeError("name must be a string");
+        }
+        if (name.trim() === "") {
+            throw new Error("name must be a non-empty string");
+        }
+        if (typeof closeGroupFn !== "function") {
+            throw new TypeError("closeGroupFn must be a function");
+        }
+
+        this._name = name;
+        this._closeGroupFn = closeGroupFn;
+    }
+
+    /**
+     * The name of the adapter.
+     */
+    get name(): string {
+        return this._name;
+    }
+
+    /**
+     * Declare a new fixture group.
+     *
+     * @param {AdapterGroupOptions} options The options describing the fixture
+     * group.
+     * @returns {AdapterGroupInterface} The new fixture group.
+     */
+    declareGroup<Config: {...}>(
+        options: $ReadOnly<AdapterGroupOptions>,
+    ): AdapterGroupInterface<Config, Options, Exports> {
+        return new AdapterGroup(this._closeGroupFn, options);
+    }
+}

package/src/fixtures/adapters/adapters.js

@@ -0,0 +1,2 @@
+// @flow
+export {getAdapter as storybook} from "./storybook.js";

package/src/fixtures/adapters/storybook.js

@@ -0,0 +1,119 @@
+// @flow
+import * as React from "react";
+import {action} from "@storybook/addon-actions";
+import {Adapter} from "./adapter.js";
+
+import type {
+    AdapterGroupOptions,
+    AdapterFixtureOptions,
+    AdapterFactory,
+} from "../types.js";
+
+type StoryContext = {|
+    args: $ReadOnly<any>,
+    argTypes: $ReadOnly<any>,
+    globals: $ReadOnlyArray<any>,
+    hooks: $ReadOnlyArray<any>,
+    parameters: $ReadOnly<any>,
+    viewMode: mixed,
+|};
+
+export 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>,
+|};
+
+/**
+ * Get a fixture framework adapter for Storybook support.
+ */
+export const getAdapter: AdapterFactory<StorybookOptions, Exports<any>> = (
+    MountingComponent = null,
+) =>
+    new Adapter<StorybookOptions, Exports<any>>(
+        "storybook",
+        <TProps: {...}>(
+            {
+                title,
+                description: groupDescription,
+            }: $ReadOnly<AdapterGroupOptions>,
+            adapterOptions: ?$ReadOnly<StorybookOptions>,
+            declaredFixtures: $ReadOnlyArray<AdapterFixtureOptions<TProps>>,
+        ): ?$ReadOnly<Exports<TProps>> => {
+            const templateMap = new WeakMap();
+
+            const log = (message, ...args) => action(message)(...args);
+
+            const exports = declaredFixtures.reduce(
+                (acc, {description, getProps, component: Component}, i) => {
+                    const storyName = `${i + 1} ${description}`;
+                    const exportName = storyName
+                        // Make word boundaries start with an upper case letter.
+                        .replace(/\b\w/g, (c) => c.toUpperCase())
+                        // Remove all non-alphanumeric characters.
+                        .replace(/[^\w]+/g, "")
+                        // Remove all underscores.
+                        .replace(/[_]+/g, "");
+
+                    // 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(Component);
+                    if (Template == null) {
+                        // The MountingComponent is a bit different than just a
+                        // Storybook decorator. It's a React component that
+                        // takes over rendering the component in the fixture
+                        // with the given args, allowing for greater
+                        // customization in a platform-agnostic manner (i.e.
+                        // not just story format).
+                        Template = MountingComponent
+                            ? (args) => (
+                                  <MountingComponent
+                                      component={Component}
+                                      props={args}
+                                      log={log}
+                                  />
+                              )
+                            : (args) => <Component {...args} />;
+                        templateMap.set(Component, Template);
+                    }
+
+                    // Each story that shares that component then reuses that
+                    // template.
+                    acc[exportName] = Template.bind({});
+                    acc[exportName].args = getProps({log});
+                    // 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).
+                    acc[exportName].storyName = storyName;
+
+                    return acc;
+                },
+                {
+                    default: {
+                        title,
+                        // TODO(somewhatabstract): Use groupDescription
+                        // Possibly via a decorator?
+                        ...adapterOptions,
+                    },
+                },
+            );
+
+            return Object.freeze(exports);
+        },
+    );

package/src/fixtures/combine-options.js

@@ -0,0 +1,25 @@
+// @flow
+import {combineTopLevel} from "./combine-top-level.js";
+
+/**
+ * Combine one or more objects into a single object.
+ *
+ * Objects later in the argument list take precedence over those that are
+ * earlier. Object and array values at the root level are merged.
+ */
+export const combineOptions = <Options: {...}>(
+    ...toBeCombined: $ReadOnlyArray<Partial<Options>>
+): $ReadOnly<Partial<Options>> => {
+    const combined = toBeCombined.filter(Boolean).reduce((acc, cur) => {
+        for (const key of Object.keys(cur)) {
+            // We always call combine, even if acc[key] is undefined
+            // because we need to make sure we clone values.
+            acc[key] = combineTopLevel(acc[key], cur[key]);
+        }
+        return acc;
+    }, {});
+
+    // We know that we are creating a compatible return type.
+    // $FlowIgnore[incompatible-return]
+    return combined;
+};

package/src/fixtures/combine-top-level.js

@@ -0,0 +1,44 @@
+// @flow
+import {clone} from "@khanacademy/wonder-stuff-core";
+
+/**
+ * Combine two values.
+ *
+ * This method clones val2 before using any of its properties to try to ensure
+ * the combined object is not linked back to the original.
+ *
+ * If the values are objects, it will merge them at the top level. Properties
+ * themselves are not merged; val2 properties will overwrite val1 where there
+ * are conflicts
+ *
+ * If the values are arrays, it will concatenate and dedupe them.
+ * NOTE: duplicates in either val1 or val2 will also be deduped.
+ *
+ * If the values are any other type, or val2 has a different type to val1, val2
+ * will be returned.
+ */
+export const combineTopLevel = (
+    val1: $ReadOnly<any>,
+    val2: $ReadOnly<any>,
+): any => {
+    const obj2Clone = clone(val2);
+
+    // Only merge if they're both arrays or both objects.
+    // If not, we will just return val2.
+    if (
+        val1 !== null &&
+        val2 !== null &&
+        typeof val1 === "object" &&
+        typeof val2 === "object"
+    ) {
+        const val1IsArray = Array.isArray(val1);
+        const val2IsArray = Array.isArray(val2);
+
+        if (val1IsArray && val2IsArray) {
+            return Array.from(new Set([...val1, ...obj2Clone]));
+        } else if (!val1IsArray && !val2IsArray) {
+            return {...val1, ...obj2Clone};
+        }
+    }
+    return obj2Clone;
+};

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

@@ -0,0 +1,64 @@
+// @flow
+import * as React from "react";
+
+import {setupFixtures, fixtures, adapters} from "../index.js";
+
+// Normally would call setup from the storybook.main.js for a project.
+setupFixtures({
+    adapter: adapters.storybook(),
+});
+
+const MyComponent = (props) =>
+    `I am a component. Here are my props: ${JSON.stringify(props, null, 2)}`;
+
+const Wrapper = (props) => (
+    <>
+        Wrapper &gt;&gt;&gt;
+        <MyComponent {...props} />
+        &lt;&lt;&lt; Wrapper
+    </>
+);
+
+const stories: Array<mixed> = Object.values(
+    fixtures(
+        {
+            component: MyComponent,
+            title: "Testing/Fixtures/Basic",
+        },
+        (fixture) => {
+            fixture("This is a fixture with some regular props", {
+                see: "this is a prop",
+                and: "this is another",
+            });
+
+            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 {
+                        this: "prop was made from a function",
+                    };
+                },
+            );
+
+            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 const F3 = stories[3];

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

@@ -0,0 +1,59 @@
+// @flow
+import * as React from "react";
+
+import {setupFixtures, fixtures, adapters} from "../index.js";
+
+// Normally would call setup from the storybook.main.js for a project.
+setupFixtures({
+    adapter: adapters.storybook(),
+});
+
+const MyComponent = (props) => `My props: ${JSON.stringify(props, null, 2)}`;
+
+const Wrapper = (props) => (
+    <>
+        Wrapper &gt;&gt;&gt;
+        <MyComponent {...props} />
+        &lt;&lt;&lt; Wrapper
+    </>
+);
+
+const DefaultWrapper = (props) => (
+    <>
+        DefaultWrapper &gt;&gt;&gt;
+        <MyComponent {...props} />
+        &lt;&lt;&lt; DefaultWrapper
+    </>
+);
+
+const stories: Array<mixed> = Object.values(
+    fixtures(
+        {
+            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,
+            );
+        },
+    ) ?? {},
+);
+
+export default stories[0];
+export const F1 = stories[1];
+export const F2 = stories[2];

package/src/fixtures/fixtures.js

@@ -0,0 +1,77 @@
+// @flow
+import * as React from "react";
+import {getConfiguration} from "./setup.js";
+import {combineOptions} from "./combine-options.js";
+
+import type {FixturesOptions, GetPropsOptions} from "./types.js";
+
+type FixtureProps<TProps: {...}> =
+    | $ReadOnly<TProps>
+    | ((options: $ReadOnly<GetPropsOptions>) => $ReadOnly<TProps>);
+
+/**
+ * Describe a group of fixtures for a given component.
+ *
+ * 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
+ * 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.
+ */
+export const fixtures = <TProps: {...}>(
+    options: $ReadOnly<FixturesOptions<TProps>>,
+    fn: (
+        fixture: (
+            description: string,
+            props: FixtureProps<TProps>,
+            wrapper?: React.ComponentType<TProps>,
+        ) => void,
+    ) => void,
+): ?$ReadOnly<mixed> => {
+    const {adapter, defaultAdapterOptions} = getConfiguration();
+    const {
+        title,
+        component,
+        description: groupDescription,
+        defaultWrapper,
+        additionalAdapterOptions,
+    } = options;
+
+    // 1. Create a new adapter group.
+    const group = adapter.declareGroup<TProps>({
+        title: title || component.displayName || component.name || "Component",
+        description: groupDescription,
+    });
+
+    // 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);
+
+    // 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,
+    );
+
+    // 4. Call close on the group and return the result.
+    return group.closeGroup(combinedAdapterOptions);
+};

package/src/fixtures/setup.js

@@ -0,0 +1,26 @@
+// @flow
+import type {Configuration} from "./types.js";
+
+let _configuration: ?$ReadOnly<Configuration<any, any>> = null;
+
+/**
+ * Setup the fixture framework.
+ */
+export const setup = <TAdapterOptions: {...}, TAdapterExports: {...}>(
+    configuration: $ReadOnly<Configuration<TAdapterOptions, TAdapterExports>>,
+) => {
+    _configuration = configuration;
+};
+
+/**
+ * Get the framework configuration.
+ *
+ * @returns {Configuration} The configuration as provided via setup().
+ * @throws {Error} If the configuration has not been set.
+ */
+export const getConfiguration = (): $ReadOnly<Configuration<any, any>> => {
+    if (_configuration == null) {
+        throw new Error("Not configured");
+    }
+    return _configuration;
+};