@khanacademy/wonder-blocks-testing 2.0.8 → 4.0.0

package/src/fetch/__tests__/fetch-request-matches-mock.test.js

@@ -0,0 +1,99 @@
+// @flow
+import {Request} from "node-fetch";
+import {fetchRequestMatchesMock} from "../fetch-request-matches-mock.js";
+
+const TEST_URL = "http://example.com/foo?querya=1&queryb=elephants#fragment";
+
+describe("#fetchRequestMatchesMock", () => {
+    it("should throw if mock is not valid", () => {
+        // Arrange
+        const mock = {
+            operation: {
+                id: "foo",
+                type: "query",
+            },
+        };
+
+        // Act
+        const underTest = () =>
+            fetchRequestMatchesMock((mock: any), TEST_URL, null);
+
+        // Assert
+        expect(underTest).toThrowErrorMatchingInlineSnapshot(
+            `"Unsupported mock operation: {\\"operation\\":{\\"id\\":\\"foo\\",\\"type\\":\\"query\\"}}"`,
+        );
+    });
+
+    it("should throw if input is not valid", () => {
+        // Arrange
+        const mock = "http://example.com/foo";
+
+        // Act
+        const underTest = () =>
+            fetchRequestMatchesMock(
+                mock,
+                ({not: "a valid request"}: any),
+                null,
+            );
+
+        // Assert
+        expect(underTest).toThrowErrorMatchingInlineSnapshot(
+            `"Unsupported input type"`,
+        );
+    });
+
+    describe.each([TEST_URL, new URL(TEST_URL), new Request(TEST_URL)])(
+        "for valid inputs",
+        (input) => {
+            it("should return false if mock is a string and it does not match the fetched URL", () => {
+                // Arrange
+                const mock = "http://example.com/bar";
+
+                // Act
+                const result = fetchRequestMatchesMock(mock, input, null);
+
+                // Assert
+                expect(result).toBe(false);
+            });
+
+            it("should return false if the mock is a regular expression and it doesn't match the fetched URL", () => {
+                // Arrange
+                const mock = /\/bar/;
+
+                // Act
+                const result = fetchRequestMatchesMock(mock, input, null);
+
+                // Assert
+                expect(result).toBe(false);
+            });
+
+            it("should return true if the mock is a string and matches the fetched URL", () => {
+                // Arrange
+                const mock = TEST_URL;
+
+                // Act
+                const result = fetchRequestMatchesMock(mock, input, null);
+
+                // Assert
+                expect(result).toBe(true);
+            });
+
+            it.each([
+                /http:\/\/example.com\/foo/,
+                /queryb=elephants/,
+                /^.*#fragment$/,
+            ])(
+                "should return true if the mock is a %s and matches the fetched URL",
+                (regex) => {
+                    // Arrange
+
+                    // Act
+                    const result = fetchRequestMatchesMock(regex, input, null);
+
+                    // Assert
+                    expect(result).toBe(true);
+                },
+            );
+        },
+    );
+});

package/src/fetch/__tests__/mock-fetch.test.js

@@ -0,0 +1,84 @@
+// @flow
+import {Request} from "node-fetch";
+import {RespondWith} from "../../make-mock-response.js";
+import {mockFetch} from "../mock-fetch.js";
+
+describe("#mockFetch", () => {
+    it.each`
+        input                                    | init
+        ${"http://example.com/foo"}              | ${undefined}
+        ${new URL("http://example.com/foo")}     | ${{method: "GET"}}
+        ${new Request("http://example.com/foo")} | ${{method: "POST"}}
+    `(
+        "should reject with a useful error when there are no matching mocks for %s",
+        async ({input, init}) => {
+            // Arrange
+            const mockFn = mockFetch();
+
+            // Act
+            const result = mockFn(input, init);
+
+            // Assert
+            await expect(result).rejects.toThrowErrorMatchingSnapshot();
+        },
+    );
+
+    describe("mockOperation", () => {
+        it("should match a similar operation", async () => {
+            // Arrange
+            const mockFn = mockFetch();
+            const operation = "http://example.com/foo";
+
+            // Act
+            mockFn.mockOperation(operation, RespondWith.text("TADA!"));
+            const result = mockFn(operation, {method: "GET"});
+
+            // Assert
+            await expect(result).resolves.toBeDefined();
+        });
+
+        it("should not match a different operation", async () => {
+            // Arrange
+            const mockFn = mockFetch();
+            const operation = "http://example.com/foo";
+
+            // Act
+            mockFn.mockOperation(operation, RespondWith.text("TADA!"));
+            const result = mockFn("http://example.com/bar", {method: "GET"});
+
+            // Assert
+            await expect(result).rejects.toThrowError();
+        });
+    });
+
+    describe("mockOperationOnce", () => {
+        it("should match once", async () => {
+            // Arrange
+            const mockFn = mockFetch();
+            const operation = "http://example.com/foo";
+
+            // Act
+            mockFn.mockOperationOnce(operation, RespondWith.text("TADA!"));
+            const result = mockFn(operation, {method: "GET"});
+
+            // Assert
+            await expect(result).resolves.toBeDefined();
+        });
+
+        it("should only match once", async () => {
+            // Arrange
+            const mockFn = mockFetch();
+            const operation = "http://example.com/foo";
+
+            // Act
+            mockFn.mockOperationOnce(operation, RespondWith.text("TADA!"));
+            const result = Promise.all([
+                mockFn(operation, {method: "GET"}),
+                mockFn(operation, {method: "POST"}),
+            ]);
+
+            // Assert
+            await expect(result).rejects.toThrowError();
+        });
+    });
+});

package/src/fetch/fetch-request-matches-mock.js

@@ -0,0 +1,43 @@
+// @flow
+import type {FetchMockOperation} from "./types.js";
+
+/**
+ * Get the URL from the given RequestInfo.
+ *
+ * Since we could be running in Node or in JSDOM, we don't check instance
+ * types, but just use a heuristic so that this works without knowing what
+ * was polyfilling things.
+ */
+const getHref = (input: RequestInfo): string => {
+    if (typeof input === "string") {
+        return input;
+    } else if (typeof input.url === "string") {
+        return input.url;
+    } else if (typeof input.href === "string") {
+        return input.href;
+    } else {
+        throw new Error(`Unsupported input type`);
+    }
+};
+
+/**
+ * Determines if a given fetch invocation matches the given mock.
+ */
+export const fetchRequestMatchesMock = (
+    mock: FetchMockOperation,
+    input: RequestInfo,
+    init: ?RequestOptions,
+): boolean => {
+    // Currently, we only match on the input portion.
+    // This can be a Request, a URL, or a string.
+    const href = getHref(input);
+
+    // Our mock operation is either a string for an exact match, or a regex.
+    if (typeof mock === "string") {
+        return href === mock;
+    } else if (mock instanceof RegExp) {
+        return mock.test(href);
+    } else {
+        throw new Error(`Unsupported mock operation: ${JSON.stringify(mock)}`);
+    }
+};

package/src/fetch/mock-fetch.js

@@ -0,0 +1,19 @@
+// @flow
+import {fetchRequestMatchesMock} from "./fetch-request-matches-mock.js";
+import {mockRequester} from "../mock-requester.js";
+import type {FetchMockFn, FetchMockOperation} from "./types.js";
+
+/**
+ * A mock for the fetch function passed to GqlRouter.
+ */
+export const mockFetch = (): FetchMockFn =>
+    mockRequester<FetchMockOperation, _>(
+        fetchRequestMatchesMock,
+        (input, init) =>
+            `Input: ${
+                typeof input === "string"
+                    ? input
+                    : JSON.stringify(input, null, 2)
+            }
+    Options: ${init == null ? "None" : JSON.stringify(init, null, 2)}`,
+    );

package/src/fetch/types.js

@@ -0,0 +1,18 @@
+//@flow
+import type {OperationMock} from "../types.js";
+import type {MockResponse} from "../make-mock-response.js";
+
+export type FetchMockOperation = RegExp | string;
+
+type FetchMockOperationFn = (
+    operation: FetchMockOperation,
+    response: MockResponse<any>,
+) => FetchMockFn;
+
+export type FetchMockFn = {|
+    (input: RequestInfo, init?: RequestOptions): Promise<Response>,
+    mockOperation: FetchMockOperationFn,
+    mockOperationOnce: FetchMockOperationFn,
+|};
+
+export type FetchMock = OperationMock<FetchMockOperation>;

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,
 |};
 
 /**