@khanacademy/wonder-blocks-testing 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @khanacademy/wonder-blocks-testing
+
+## 0.0.2
+### Patch Changes
+
+- d2dba67a: Implemented the fixture framework and added the storybook adapter for it
+- b7a100f2: Add the new wonder-blocks-testing package

package/dist/es/index.js

@@ -0,0 +1,354 @@
+import _extends from '@babel/runtime/helpers/extends';
+import * as React from 'react';
+import { action } from '@storybook/addon-actions';
+import { clone } from '@khanacademy/wonder-stuff-core';
+
+/**
+ * Simple adapter group implementation.
+ */
+class AdapterGroup {
+  /**
+   * 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, _options) {
+    this.closeGroup = (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;
+      }
+    };
+
+    this.declareFixture = 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);
+    };
+
+    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.
+   */
+
+
+}
+
+/**
+ * Class for implementing a custom adapter.
+ */
+class Adapter {
+  /**
+   * @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, closeGroupFn) {
+    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() {
+    return this._name;
+  }
+  /**
+   * Declare a new fixture group.
+   *
+   * @param {AdapterGroupOptions} options The options describing the fixture
+   * group.
+   * @returns {AdapterGroupInterface} The new fixture group.
+   */
+
+
+  declareGroup(options) {
+    return new AdapterGroup(this._closeGroupFn, options);
+  }
+
+}
+
+/**
+ * Get a fixture framework adapter for Storybook support.
+ */
+const getAdapter = (MountingComponent = null) => new Adapter("storybook", ({
+  title,
+  description: groupDescription
+}, adapterOptions, declaredFixtures) => {
+  const templateMap = new WeakMap();
+
+  const log = (message, ...args) => action(message).apply(void 0, 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 => /*#__PURE__*/React.createElement(MountingComponent, {
+        component: Component,
+        props: args,
+        log: log
+      }) : args => /*#__PURE__*/React.createElement(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: _extends({
+      title
+    }, adapterOptions)
+  });
+  return Object.freeze(exports);
+});
+
+var adapters = /*#__PURE__*/Object.freeze({
+    __proto__: null,
+    storybook: getAdapter
+});
+
+let _configuration = null;
+/**
+ * Setup the fixture framework.
+ */
+
+const setup = configuration => {
+  _configuration = configuration;
+};
+/**
+ * Get the framework configuration.
+ *
+ * @returns {Configuration} The configuration as provided via setup().
+ * @throws {Error} If the configuration has not been set.
+ */
+
+const getConfiguration = () => {
+  if (_configuration == null) {
+    throw new Error("Not configured");
+  }
+
+  return _configuration;
+};
+
+/**
+ * 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.
+ */
+
+const combineTopLevel = (val1, val2) => {
+  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([].concat(val1, obj2Clone)));
+    } else if (!val1IsArray && !val2IsArray) {
+      return _extends({}, val1, obj2Clone);
+    }
+  }
+
+  return obj2Clone;
+};
+
+/**
+ * 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.
+ */
+
+const combineOptions = (...toBeCombined) => {
+  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;
+};
+
+/**
+ * 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.
+ */
+const fixtures = (options, fn) => {
+  var _additionalAdapterOpt;
+
+  const {
+    adapter,
+    defaultAdapterOptions
+  } = getConfiguration();
+  const {
+    title,
+    component,
+    description: groupDescription,
+    defaultWrapper,
+    additionalAdapterOptions
+  } = options; // 1. Create a new adapter group.
+
+  const group = adapter.declareGroup({
+    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) => {
+    var _ref;
+
+    group.declareFixture({
+      description,
+      getProps: options => typeof props === "function" ? props(options) : props,
+      component: (_ref = wrapper != null ? wrapper : defaultWrapper) != null ? _ref : component
+    });
+  };
+
+  fn(addFixture); // 3. Combine the adapter options from the fixture group with the
+  //    defaults from our setup.
+
+  const groupAdapterOverrides = (_additionalAdapterOpt = additionalAdapterOptions == null ? void 0 : additionalAdapterOptions[adapter.name]) != null ? _additionalAdapterOpt : {};
+  const combinedAdapterOptions = combineOptions(defaultAdapterOptions, groupAdapterOverrides); // 4. Call close on the group and return the result.
+
+  return group.closeGroup(combinedAdapterOptions);
+};
+
+// Opt this file out of coverage because it's super hard to test.
+
+/* istanbul ignore file */
+
+/**
+ * Isolate imports within a given action using jest.isolateModules.
+ *
+ * This is a helper for the `jest.isolateModules` API, allowing
+ * code to avoid the clunky closure syntax in their tests.
+ *
+ * @param {() => T} action The action that contains the isolated module imports.
+ * We do it this way so that any `require` calls are relative to the calling
+ * code and not this function. Note that we don't support promises here to
+ * discourage dynamic `import` use, which doesn't play well with standard
+ * jest yet.
+ */
+const isolateModules = action => {
+  if (typeof jest === "undefined") {
+    throw new Error(`jest is not available in global scope`);
+  }
+
+  let result = undefined;
+  jest.isolateModules(() => {
+    result = action();
+  }); // We know that we'll have a result of the appropriate type at this point.
+  // We could use a promise to make everything happy, but this doesn't need
+  // to be async, so why bother.
+  // $FlowIgnore[incompatible-return]
+
+  return result;
+};
+
+export { adapters, fixtures, isolateModules, setup as setupFixtures };