@khanacademy/wonder-blocks-testing 7.0.3 → 7.1.0

package/src/__tests__/settle-signal.test.js

@@ -0,0 +1,105 @@
+// @flow
+import {SettleSignal} from "../settle-signal.js";
+
+describe("SettleSignal", () => {
+    it("should extend EventTarget", () => {
+        // Arrange
+
+        // Act
+        const result = new SettleSignal();
+
+        // Assert
+        expect(result).toBeInstanceOf(EventTarget);
+    });
+
+    it("should start with settled = false", () => {
+        // Arrange
+
+        // Act
+        const result = new SettleSignal();
+
+        // Assert
+        expect(result).toHaveProperty("settled", false);
+    });
+
+    it("should invoke the passed function with a function", () => {
+        // Arrange
+        const setSettleFn = jest.fn();
+
+        // Act
+        // eslint-disable-next-line no-new
+        new SettleSignal(setSettleFn);
+
+        // Assert
+        expect(setSettleFn).toHaveBeenCalledWith(expect.any(Function));
+    });
+
+    describe("setSettleFn argument", () => {
+        it("should set settled to true", () => {
+            // Arrange
+            const setSettleFn = jest.fn();
+            const signal = new SettleSignal(setSettleFn);
+            const settle = setSettleFn.mock.calls[0][0];
+
+            // Act
+            settle();
+
+            // Assert
+            expect(signal.settled).toBe(true);
+        });
+
+        it("should raise the settled event", () => {
+            // Arrange
+            const setSettleFn = jest.fn();
+            const signal = new SettleSignal(setSettleFn);
+            const settle = setSettleFn.mock.calls[0][0];
+            const handler = jest.fn();
+            signal.addEventListener("settled", handler);
+
+            // Act
+            settle();
+
+            // Assert
+            expect(handler).toHaveBeenCalled();
+        });
+
+        it("should throw if the signal has already been settled", () => {
+            // Arrange
+            const setSettleFn = jest.fn();
+            // eslint-disable-next-line no-new
+            new SettleSignal(setSettleFn);
+            const settle = setSettleFn.mock.calls[0][0];
+            settle();
+
+            // Act
+            const result = () => settle();
+
+            // Assert
+            expect(result).toThrowErrorMatchingInlineSnapshot(
+                `"SettleSignal already settled"`,
+            );
+        });
+    });
+
+    describe("#SettleSignal.settle", () => {
+        it("should return a SettleSignal", () => {
+            // Arrange
+
+            // Act
+            const result = SettleSignal.settle();
+
+            // Assert
+            expect(result).toBeInstanceOf(SettleSignal);
+        });
+
+        it("should return a SettleSignal that is already settled", () => {
+            // Arrange
+
+            // Act
+            const result = SettleSignal.settle();
+
+            // Assert
+            expect(result).toHaveProperty("settled", true);
+        });
+    });
+});

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

@@ -1,6 +1,6 @@
 // @flow
 import {Request} from "node-fetch";
-import {RespondWith} from "../../make-mock-response.js";
+import {RespondWith} from "../../respond-with.js";
 import {mockFetch} from "../mock-fetch.js";
 
 describe("#mockFetch", () => {

package/src/fetch/types.js

@@ -1,5 +1,5 @@
 //@flow
-import type {MockResponse} from "../make-mock-response.js";
+import type {MockResponse} from "../respond-with.js";
 
 export type FetchMockOperation = RegExp | string;
 

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

@@ -3,7 +3,7 @@ import * as React from "react";
 import {render, screen, waitFor} from "@testing-library/react";
 
 import {GqlRouter, useGql} from "@khanacademy/wonder-blocks-data";
-import {RespondWith} from "../../make-mock-response.js";
+import {RespondWith} from "../../respond-with.js";
 import {mockGqlFetch} from "../mock-gql-fetch.js";
 
 describe("#mockGqlFetch", () => {

package/src/gql/__tests__/wb-data-integration.test.js

@@ -3,7 +3,7 @@ import * as React from "react";
 import {render, screen, waitFor} from "@testing-library/react";
 
 import {GqlRouter, useGql} from "@khanacademy/wonder-blocks-data";
-import {RespondWith} from "../../make-mock-response.js";
+import {RespondWith} from "../../respond-with.js";
 import {mockGqlFetch} from "../mock-gql-fetch.js";
 
 describe("integrating mockGqlFetch, RespondWith, GqlRouter and useGql", () => {

package/src/gql/types.js

@@ -1,7 +1,7 @@
 //@flow
 import type {GqlOperation, GqlContext} from "@khanacademy/wonder-blocks-data";
 import type {GraphQLJson} from "../types.js";
-import type {MockResponse} from "../make-mock-response.js";
+import type {MockResponse} from "../respond-with.js";
 
 export type GqlMockOperation<
     TData: {...},

package/src/index.js

@@ -11,8 +11,9 @@ export type {
 // Fetch mocking framework
 export {mockFetch} from "./fetch/mock-fetch.js";
 export {mockGqlFetch} from "./gql/mock-gql-fetch.js";
-export {RespondWith} from "./make-mock-response.js";
-export type {MockResponse} from "./make-mock-response.js";
+export {RespondWith} from "./respond-with.js";
+export {SettleController} from "./settle-controller.js";
+export type {MockResponse} from "./respond-with.js";
 export type {FetchMockFn, FetchMockOperation} from "./fetch/types.js";
 export type {GqlFetchMockFn, GqlMockOperation} from "./gql/types.js";
 

package/src/mock-requester.js

@@ -1,6 +1,5 @@
 // @flow
-import {makeMockResponse} from "./make-mock-response.js";
-import type {MockResponse} from "./make-mock-response.js";
+import type {MockResponse} from "./respond-with.js";
 import type {OperationMock, OperationMatcher, MockFn} from "./types.js";
 
 /**
@@ -51,7 +50,7 @@ export const mockRequester = <
         response: MockResponse<any>,
         onceOnly: boolean,
     ): MockFn<TOperationType> => {
-        const mockResponse = () => makeMockResponse(response);
+        const mockResponse = () => response.toPromise();
         mocks.push({
             operation,
             response: mockResponse,

package/src/respond-with.js

@@ -0,0 +1,236 @@
+// @flow
+import {SettleSignal} from "./settle-signal.js";
+import {ResponseImpl} from "./response-impl.js";
+import type {GraphQLJson} from "./types.js";
+
+// We want the parameterization here so that folks can assert a response is
+// of a specific type if passing between various functions. For example,
+// the graphql mocking framework might want to assert a response is returning
+// the expected data structure. We could use `opaque` but that would then
+// hide the `toPromise` call we want to provide.
+/* eslint-disable no-unused-vars */
+/**
+ * Describes a mock response to a fetch request.
+ */
+export type MockResponse<TData> = {|
+    /**
+     * Create a promise from the mocked response.
+     *
+     * If a signal was provided when the mock response was created, the promise
+     * will only settle to resolution or rejection if the signal is raised.
+     */
+    +toPromise: () => Promise<Response>,
+|};
+/* eslint-enable no-unused-vars */
+
+type InternalMockResponse =
+    | {|
+          +type: "text",
+          +text: string | (() => string),
+          +statusCode: number,
+          +signal: ?SettleSignal,
+      |}
+    | {|
+          +type: "reject",
+          +error: Error | (() => Error),
+          +signal: ?SettleSignal,
+      |};
+
+/**
+ * Helper for creating a text-based mock response.
+ */
+const textResponse = <TData>(
+    text: string | (() => string),
+    statusCode: number,
+    signal: ?SettleSignal,
+): MockResponse<TData> => ({
+    toPromise: () =>
+        makeMockResponse({
+            type: "text",
+            text,
+            statusCode,
+            signal,
+        }),
+});
+
+/**
+ * Helper for creating a rejected mock response.
+ */
+const rejectResponse = (
+    error: Error | (() => Error),
+    signal: ?SettleSignal,
+): MockResponse<empty> => ({
+    toPromise: () =>
+        makeMockResponse({
+            type: "reject",
+            error,
+            signal,
+        }),
+});
+
+/**
+ * Helpers to define mock responses for mocked requests.
+ */
+export const RespondWith = Object.freeze({
+    /**
+     * Response with text body and status code.
+     * Status code defaults to 200.
+     */
+    text: <TData = string>(
+        text: string,
+        statusCode: number = 200,
+        signal: ?SettleSignal = null,
+    ): MockResponse<TData> => textResponse<TData>(text, statusCode, signal),
+
+    /**
+     * Response with JSON body and status code 200.
+     */
+    json: <TJson: {...}>(
+        json: TJson,
+        signal: ?SettleSignal = null,
+    ): MockResponse<TJson> =>
+        textResponse<TJson>(() => JSON.stringify(json), 200, signal),
+
+    /**
+     * Response with GraphQL data JSON body and status code 200.
+     */
+    graphQLData: <TData: {...}>(
+        data: TData,
+        signal: ?SettleSignal = null,
+    ): MockResponse<GraphQLJson<TData>> =>
+        textResponse<GraphQLJson<TData>>(
+            () => JSON.stringify({data}),
+            200,
+            signal,
+        ),
+
+    /**
+     * Response with body that will not parse as JSON and status code 200.
+     */
+    unparseableBody: (signal: ?SettleSignal = null): MockResponse<any> =>
+        textResponse("INVALID JSON", 200, signal),
+
+    /**
+     * Rejects with an AbortError to simulate an aborted request.
+     */
+    abortedRequest: (signal: ?SettleSignal = null): MockResponse<any> =>
+        rejectResponse(() => {
+            const abortError = new Error("Mock request aborted");
+            abortError.name = "AbortError";
+            return abortError;
+        }, signal),
+
+    /**
+     * Rejects with the given error.
+     */
+    reject: (error: Error, signal: ?SettleSignal = null): MockResponse<any> =>
+        rejectResponse(error, signal),
+
+    /**
+     * A non-200 status code with empty text body.
+     * Equivalent to calling `ResponseWith.text("", statusCode)`.
+     */
+    errorStatusCode: (
+        statusCode: number,
+        signal: ?SettleSignal = null,
+    ): MockResponse<any> => {
+        if (statusCode < 300) {
+            throw new Error(`${statusCode} is not a valid error status code`);
+        }
+        return textResponse("{}", statusCode, signal);
+    },
+
+    /**
+     * Response body that is valid JSON but not a valid GraphQL response.
+     */
+    nonGraphQLBody: (signal: ?SettleSignal = null): MockResponse<any> =>
+        textResponse(
+            () =>
+                JSON.stringify({
+                    valid: "json",
+                    that: "is not a valid graphql response",
+                }),
+            200,
+            signal,
+        ),
+
+    /**
+     * Response that is a GraphQL errors response with status code 200.
+     */
+    graphQLErrors: (
+        errorMessages: $ReadOnlyArray<string>,
+        signal: ?SettleSignal = null,
+    ): MockResponse<GraphQLJson<any>> =>
+        textResponse<GraphQLJson<any>>(
+            () =>
+                JSON.stringify({
+                    errors: errorMessages.map((e) => ({
+                        message: e,
+                    })),
+                }),
+            200,
+            signal,
+        ),
+});
+
+const callOnSettled = (signal: ?SettleSignal, fn: () => void): void => {
+    if (signal == null || signal.settled) {
+        fn();
+        return;
+    }
+
+    const onSettled = () => {
+        signal.removeEventListener("settled", onSettled);
+        fn();
+    };
+    signal.addEventListener("settled", onSettled);
+};
+
+/**
+ * Turns a MockResponse value to an actual Response that represents the mock.
+ */
+const makeMockResponse = (
+    response: InternalMockResponse,
+): Promise<Response> => {
+    const {signal} = response;
+
+    switch (response.type) {
+        case "text":
+            return new Promise((resolve, reject) => {
+                callOnSettled(signal, () => {
+                    const text =
+                        typeof response.text === "function"
+                            ? response.text()
+                            : response.text;
+                    resolve(
+                        new ResponseImpl(text, {status: response.statusCode}),
+                    );
+                });
+            });
+
+        case "reject":
+            return new Promise((resolve, reject) => {
+                callOnSettled(signal, () =>
+                    reject(
+                        response.error instanceof Error
+                            ? response.error
+                            : response.error(),
+                    ),
+                );
+            });
+
+        /* istanbul ignore next */
+        default:
+            if (process.env.NODE_ENV !== "production") {
+                // If we're not in production, give an immediate signal that the
+                // dev forgot to support this new type.
+                throw new Error(`Unknown response type: ${response.type}`);
+            }
+            // Production; assume a rejection.
+            return makeMockResponse({
+                type: "reject",
+                error: new Error("Unknown response type"),
+                signal,
+            });
+    }
+};

package/src/settle-controller.js

@@ -0,0 +1,35 @@
+// @flow
+import {SettleSignal} from "./settle-signal.js";
+
+/**
+ * A controller for the `RespondWith` API to control response settlement.
+ */
+export class SettleController {
+    #settleFn: () => void;
+    #signal: SettleSignal;
+
+    constructor() {
+        // Create our signal.
+        // We pass in a method to capture it's settle function so that
+        // only we can call it.
+        this.#signal = new SettleSignal(
+            (settleFn) => (this.#settleFn = settleFn),
+        );
+    }
+
+    /**
+     * The signal to pass to the `RespondWith` API.
+     */
+    get signal(): SettleSignal {
+        return this.#signal;
+    }
+
+    /**
+     * Settle the signal and therefore any associated responses.
+     *
+     * @throws {Error} if the signal has already been settled.
+     */
+    settle(): void {
+        this.#settleFn();
+    }
+}

package/src/settle-signal.js

@@ -0,0 +1,41 @@
+// @flow
+/**
+ * A signal for controlling the `RespondWith` API responses.
+ *
+ * This provide finely-grained control over the promise lifecycle to support
+ * complex test scenarios.
+ */
+export class SettleSignal extends EventTarget {
+    #settled: boolean = false;
+
+    constructor(setSettleFn: ?(settleFn: () => void) => mixed = null) {
+        super();
+
+        // If we were given a function, we call it with a method that will
+        // settle ourselves. This allows the appropriate SettleController
+        // to be in charge of settling this instance.
+        setSettleFn?.(() => {
+            if (this.#settled) {
+                throw new Error("SettleSignal already settled");
+            }
+            this.#settled = true;
+            this.dispatchEvent(new Event("settled"));
+        });
+    }
+
+    /**
+     * An already settled signal.
+     */
+    static settle(): SettleSignal {
+        const signal = new SettleSignal();
+        signal.#settled = true;
+        return signal;
+    }
+
+    /**
+     * Has this signal been settled yet?
+     */
+    get settled(): boolean {
+        return this.#settled;
+    }
+}

package/src/types.js

@@ -1,5 +1,5 @@
 // @flow
-import type {MockResponse} from "./make-mock-response.js";
+import type {MockResponse} from "./respond-with.js";
 
 /**
  * A valid GraphQL response as supported by our mocking framework.