@khanacademy/wonder-blocks-testing 7.0.3 → 7.1.0

package/src/__docs__/exports.respond-with.stories.mdx

@@ -16,19 +16,23 @@ interface RespondWith {
     /**
      * Rejects with an AbortError to simulate an aborted request.
      */
-    abortedRequest: () => MockResponse<any>;
+    abortedRequest: (signal: ?SettleSignal = null) => MockResponse<any>;
 
     /**
      * A non-200 status code with empty text body.
      * Equivalent to calling `ResponseWith.text("", statusCode)`.
      */
-    errorStatusCode: (statusCode: number) => MockResponse<any>;
+    errorStatusCode: (
+        statusCode: number,
+        signal: ?SettleSignal = null,
+    ) => MockResponse<any>;
 
     /**
      * Response with GraphQL data JSON body and status code 200.
      */
     graphQLData: <TData: {...}>(
         data: TData,
+        signal: ?SettleSignal = null,
     ) => MockResponse<GraphQLJson<TData>>;
 
     /**
@@ -36,22 +40,26 @@ interface RespondWith {
      */
     graphQLErrors: (
         errorMessages: $ReadOnlyArray<string>,
+        signal: ?SettleSignal = null,
     ) => MockResponse<any>;
 
     /**
      * Response with JSON body and status code 200.
      */
-    json: <TJson: {...}>(json: TJson): MockResponse<TJson>;
+    json: <TJson: {...}>(
+        json: TJson,
+        signal: ?SettleSignal = null,
+    ): MockResponse<TJson>;
 
     /**
      * Response body that is valid JSON but not a valid GraphQL response.
      */
-    nonGraphQLBody: () => MockResponse<any>;
+    nonGraphQLBody: (signal: ?SettleSignal = null) => MockResponse<any>;
 
     /**
      * Rejects with the given error.
      */
-    reject: (error: Error) => MockResponse<any>;
+    reject: (error: Error, signal: ?SettleSignal = null) => MockResponse<any>;
 
     /**
      * Response with text body and status code.
@@ -60,14 +68,17 @@ interface RespondWith {
     text: <TData = string>(
         text: string,
         statusCode: number = 200,
+        signal: ?SettleSignal = null,
     ) => MockResponse<TData>;
 
     /**
      * Response with body that will not parse as JSON and status code 200.
      */
-    unparseableBody: () => MockResponse<any>;
+    unparseableBody: (signal: ?SettleSignal = null) => MockResponse<any>;
 });
 ```
 
 The `RespondWith` object is a helper for defining mock responses to use with
 mock request methods such as [`mockGqlFetch`](/docs/testing-mocking-exports-mockgqlfetch--page).
+
+Each call takes an optional `signal` that can be used to control when the promise generated from the call resolves. See [`SettleController`](/docs/testing-mocking-exports-settlecontroller--page) for related information.

package/src/__docs__/exports.settle-controller.stories.mdx

@@ -0,0 +1,32 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Testing / Mocking / Exports / SettleController"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# SettleController
+
+```ts
+class SettleController {
+    /**
+     * The signal to pass to the `RespondWith` API.
+     */
+    get signal(): SettleSignal;
+
+    /**
+     * Settle the signal and therefore any associated responses.
+     *
+     * @throws {Error} if the signal has already been settled.
+     */
+    settle(): void;
+}
+```
+
+The `SettleController` is used to control the settling of a signal. This is specifically created to work with the [`RespondWith`](/docs/testing-mocking-exports-respondwith--page) API. The `signal` property it exposes can be passed to `RespondWith` methods and then the `settle` method can be invoked to settle the signal, causing the related responses to either reject or resolve as appropriate.
+
+This can be useful for tests where the order of operations needs to be controlled in order to verify the expected behaviour of the system under test.

package/src/__docs__/types.mock-response.stories.mdx

@@ -12,7 +12,11 @@ import {Meta} from "@storybook/addon-docs";
 # MockResponse<>
 
 ```ts
-opaque type MockResponse<TJson>;
+type MockResponse<TJson> = {|
+    toPromise: () => Promise<Response>,
+|};
 ```
 
-This opaque type specifies a mock response. Values of this type are generated by the [`RespondWith`](/docs/testing-mocking-exports-respondwith--page) API.
+This type specifies a mock response. Values of this type are generated by the [`RespondWith`](/docs/testing-mocking-exports-respondwith--page) API. The type parameter is included to allow uses to enforce if they only support `MockResponses` that resolve to a specific JSON pattern.
+
+The `toPromise` method can be used to generate a new promise from the mocked response definition. Note that `toPromise` will always generate a new promise and any promise created will settle according to any signal passed to the corresponding `RespondWith` API call.

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

@@ -1,5 +1,5 @@
 // @flow
-import {RespondWith} from "../make-mock-response.js";
+import {RespondWith} from "../respond-with.js";
 import {mockRequester} from "../mock-requester.js";
 
 describe("#mockRequester", () => {

package/src/__tests__/respond-with.test.js

@@ -0,0 +1,525 @@
+// @flow
+import {SettleController} from "../settle-controller.js";
+import {RespondWith} from "../respond-with.js";
+
+describe("RespondWith", () => {
+    describe("#text.toPromise", () => {
+        it("should respond with the given text", async () => {
+            // Arrange
+
+            // Act
+            const response = await RespondWith.text("SOME TEXT").toPromise();
+            const result = await response.text();
+
+            // Assert
+            expect(result).toBe("SOME TEXT");
+        });
+
+        it("should respond with the given status code", async () => {
+            // Arrange
+
+            // Act
+            const result = await RespondWith.text("SOME TEXT", 204).toPromise();
+
+            // Assert
+            expect(result).toHaveProperty("status", 204);
+        });
+
+        it("should not settle if the signal is not raised", async () => {
+            // Arrange
+            const settleController = new SettleController();
+            const settleableResponse = RespondWith.text(
+                "SIGNALLED",
+                200,
+                settleController.signal,
+            ).toPromise();
+            const otherResponse = RespondWith.text("NO SIGNAL").toPromise();
+
+            // Act
+            const firstResponse = await Promise.race([
+                settleableResponse,
+                otherResponse,
+            ]);
+            const result = await firstResponse.text();
+
+            // Assert
+            expect(result).toBe("NO SIGNAL");
+        });
+
+        it("should settle if the signal is raised", async () => {
+            // Arrange
+            const settleController = new SettleController();
+            const settleableResponse = RespondWith.text(
+                "SIGNALLED",
+                200,
+                settleController.signal,
+            ).toPromise();
+            const otherResponse = RespondWith.text("NO SIGNAL").toPromise();
+
+            // Act
+            settleController.settle();
+            const firstResponse = await Promise.race([
+                settleableResponse,
+                otherResponse,
+            ]);
+            const result = await firstResponse.text();
+
+            // Assert
+            expect(result).toBe("SIGNALLED");
+        });
+    });
+
+    describe("#json.toPromise", () => {
+        it("should respond with the given json", async () => {
+            // Arrange
+
+            // Act
+            const response = await RespondWith.json({
+                some: "json",
+            }).toPromise();
+            const result = await response.json();
+
+            // Assert
+            expect(result).toStrictEqual({some: "json"});
+        });
+
+        it("should not settle if the signal is not raised", async () => {
+            // Arrange
+            const settleController = new SettleController();
+            const settleableResponse = RespondWith.json(
+                {result: "SIGNALLED"},
+                settleController.signal,
+            ).toPromise();
+            const otherResponse = RespondWith.text("NO SIGNAL").toPromise();
+
+            // Act
+            const firstResponse = await Promise.race([
+                settleableResponse,
+                otherResponse,
+            ]);
+            const result = await firstResponse.text();
+
+            // Assert
+            expect(result).toBe("NO SIGNAL");
+        });
+
+        it("should settle if the signal is raised", async () => {
+            // Arrange
+            const settleController = new SettleController();
+            const settleableResponse = RespondWith.json(
+                {result: "SIGNALLED"},
+                settleController.signal,
+            ).toPromise();
+            const otherResponse = RespondWith.text("NO SIGNAL").toPromise();
+
+            // Act
+            settleController.settle();
+            const firstResponse = await Promise.race([
+                settleableResponse,
+                otherResponse,
+            ]);
+            const result = await firstResponse.json();
+
+            // Assert
+            expect(result).toStrictEqual({result: "SIGNALLED"});
+        });
+    });
+
+    describe("#graphQLData", () => {
+        it("should respond with the given GraphQL data", async () => {
+            // Arrange
+
+            // Act
+            const response = await RespondWith.graphQLData({
+                some: "json",
+            }).toPromise();
+            const result = await response.json();
+
+            // Assert
+            expect(result).toStrictEqual({data: {some: "json"}});
+        });
+
+        it("should not settle if the signal is not raised", async () => {
+            // Arrange
+            const settleController = new SettleController();
+            const settleableResponse = RespondWith.graphQLData(
+                {result: "SIGNALLED"},
+                settleController.signal,
+            ).toPromise();
+            const otherResponse = RespondWith.text("NO SIGNAL").toPromise();
+
+            // Act
+            const firstResponse = await Promise.race([
+                settleableResponse,
+                otherResponse,
+            ]);
+            const result = await firstResponse.text();
+
+            // Assert
+            expect(result).toBe("NO SIGNAL");
+        });
+
+        it("should settle if the signal is raised", async () => {
+            // Arrange
+            const settleController = new SettleController();
+            const settleableResponse = RespondWith.graphQLData(
+                {result: "SIGNALLED"},
+                settleController.signal,
+            ).toPromise();
+            const otherResponse = RespondWith.text("NO SIGNAL").toPromise();
+
+            // Act
+            settleController.settle();
+            const firstResponse = await Promise.race([
+                settleableResponse,
+                otherResponse,
+            ]);
+            const result = await firstResponse.json();
+
+            // Assert
+            expect(result).toStrictEqual({data: {result: "SIGNALLED"}});
+        });
+    });
+
+    describe("#unparseableBody", () => {
+        it("should reject JSON as unparseable", async () => {
+            // Arrange
+
+            // Act
+            const response = await RespondWith.unparseableBody().toPromise();
+            const act = response.json();
+
+            // Assert
+            await expect(act).rejects.toThrowErrorMatchingInlineSnapshot(
+                `"invalid json response body at  reason: Unexpected token I in JSON at position 0"`,
+            );
+        });
+
+        it("should not settle if the signal is not raised", async () => {
+            // Arrange
+            const settleController = new SettleController();
+            const settleableResponse = RespondWith.unparseableBody(
+                settleController.signal,
+            ).toPromise();
+            const otherResponse = RespondWith.text("NO SIGNAL").toPromise();
+
+            // Act
+            const firstResponse = await Promise.race([
+                settleableResponse,
+                otherResponse,
+            ]);
+            const result = await firstResponse.text();
+
+            // Assert
+            expect(result).toBe("NO SIGNAL");
+        });
+
+        it("should settle if the signal is raised", async () => {
+            // Arrange
+            const settleController = new SettleController();
+            const settleableResponse = RespondWith.unparseableBody(
+                settleController.signal,
+            ).toPromise();
+            const otherResponse = RespondWith.text("NO SIGNAL").toPromise();
+
+            // Act
+            settleController.settle();
+            const firstResponse = await Promise.race([
+                settleableResponse,
+                otherResponse,
+            ]);
+            const act = firstResponse.json();
+
+            // Assert
+            await expect(act).rejects.toThrowError();
+        });
+    });
+
+    describe("#abortedRequest", () => {
+        it("should reject with AbortError", async () => {
+            // Arrange
+
+            // Act
+            const act = RespondWith.abortedRequest().toPromise();
+
+            // Assert
+            await expect(act).rejects.toThrowErrorMatchingInlineSnapshot(
+                `"Mock request aborted"`,
+            );
+        });
+
+        it("should not settle if the signal is not raised", async () => {
+            // Arrange
+            const settleController = new SettleController();
+            const settleableResponse = RespondWith.abortedRequest(
+                settleController.signal,
+            ).toPromise();
+            const otherResponse = RespondWith.text("NO SIGNAL").toPromise();
+
+            // Act
+            const act = Promise.race([settleableResponse, otherResponse]);
+
+            // Assert
+            await expect(act).resolves;
+        });
+
+        it("should settle if the signal is raised", async () => {
+            // Arrange
+            const settleController = new SettleController();
+            const settleableResponse = RespondWith.abortedRequest(
+                settleController.signal,
+            ).toPromise();
+            const otherResponse = RespondWith.text("NO SIGNAL").toPromise();
+
+            // Act
+            settleController.settle();
+            const act = Promise.race([settleableResponse, otherResponse]);
+
+            // Assert
+            await expect(act).rejects.toThrowError();
+        });
+    });
+
+    describe("#reject", () => {
+        it("should reject with AbortError", async () => {
+            // Arrange
+
+            // Act
+            const act = RespondWith.reject(new Error("BOOM!")).toPromise();
+
+            // Assert
+            await expect(act).rejects.toThrowErrorMatchingInlineSnapshot(
+                `"BOOM!"`,
+            );
+        });
+
+        it("should not settle if the signal is not raised", async () => {
+            // Arrange
+            const settleController = new SettleController();
+            const settleableResponse = RespondWith.reject(
+                new Error("BOOM!"),
+                settleController.signal,
+            ).toPromise();
+            const otherResponse = RespondWith.text("NO SIGNAL").toPromise();
+
+            // Act
+            const act = Promise.race([settleableResponse, otherResponse]);
+
+            // Assert
+            await expect(act).resolves;
+        });
+
+        it("should settle if the signal is raised", async () => {
+            // Arrange
+            const settleController = new SettleController();
+            const settleableResponse = RespondWith.reject(
+                new Error("BOOM!"),
+                settleController.signal,
+            ).toPromise();
+            const otherResponse = RespondWith.text("NO SIGNAL").toPromise();
+
+            // Act
+            settleController.settle();
+            const act = Promise.race([settleableResponse, otherResponse]);
+
+            // Assert
+            await expect(act).rejects.toThrowError();
+        });
+    });
+
+    describe("#errorStatusCode", () => {
+        it("should throw if the status code represents success", () => {
+            // Arrange
+
+            // Act
+            const result = () => RespondWith.errorStatusCode(200);
+
+            // Assert
+            expect(result).toThrowErrorMatchingInlineSnapshot(
+                `"200 is not a valid error status code"`,
+            );
+        });
+
+        it("should respond with the given status code", async () => {
+            // Arrange
+
+            // Act
+            const result = await RespondWith.errorStatusCode(400).toPromise();
+
+            // Assert
+            expect(result).toHaveProperty("status", 400);
+        });
+
+        it("should not settle if the signal is not raised", async () => {
+            // Arrange
+            const settleController = new SettleController();
+            const settleableResponse = RespondWith.errorStatusCode(
+                500,
+                settleController.signal,
+            ).toPromise();
+            const otherResponse = RespondWith.text("NO SIGNAL").toPromise();
+
+            // Act
+            const firstResponse = await Promise.race([
+                settleableResponse,
+                otherResponse,
+            ]);
+            const result = await firstResponse.text();
+
+            // Assert
+            expect(result).toBe("NO SIGNAL");
+        });
+
+        it("should settle if the signal is raised", async () => {
+            // Arrange
+            const settleController = new SettleController();
+            const settleableResponse = RespondWith.errorStatusCode(
+                500,
+                settleController.signal,
+            ).toPromise();
+            const otherResponse = RespondWith.text("NO SIGNAL").toPromise();
+
+            // Act
+            settleController.settle();
+            const result = await Promise.race([
+                settleableResponse,
+                otherResponse,
+            ]);
+
+            // Assert
+            expect(result).toHaveProperty("status", 500);
+        });
+    });
+
+    describe("#nonGraphQLBody", () => {
+        it("should respond with valid json", async () => {
+            // Arrange
+
+            // Act
+            const response = await RespondWith.nonGraphQLBody().toPromise();
+            const act = response.json();
+
+            // Assert
+            await expect(act).resolves.not.toThrow();
+        });
+
+        it("should respond with JSON that is not a valid GraphQL response", async () => {
+            // Arrange
+
+            // Act
+            const response = await RespondWith.nonGraphQLBody().toPromise();
+            const result = await response.json();
+
+            // Assert
+            expect(result).toMatchInlineSnapshot(`
+                Object {
+                  "that": "is not a valid graphql response",
+                  "valid": "json",
+                }
+            `);
+        });
+
+        it("should not settle if the signal is not raised", async () => {
+            // Arrange
+            const settleController = new SettleController();
+            const settleableResponse = RespondWith.nonGraphQLBody(
+                settleController.signal,
+            ).toPromise();
+            const otherResponse = RespondWith.text("NO SIGNAL").toPromise();
+
+            // Act
+            const firstResponse = await Promise.race([
+                settleableResponse,
+                otherResponse,
+            ]);
+            const result = await firstResponse.text();
+
+            // Assert
+            expect(result).toBe("NO SIGNAL");
+        });
+
+        it("should settle if the signal is raised", async () => {
+            // Arrange
+            const settleController = new SettleController();
+            const settleableResponse = RespondWith.nonGraphQLBody(
+                settleController.signal,
+            ).toPromise();
+            const otherResponse = RespondWith.text("NO SIGNAL").toPromise();
+
+            // Act
+            settleController.settle();
+            const firstResponse = await Promise.race([
+                settleableResponse,
+                otherResponse,
+            ]);
+            const result = await firstResponse.json();
+
+            // Assert
+            expect(result).toStrictEqual({
+                valid: "json",
+                that: "is not a valid graphql response",
+            });
+        });
+    });
+
+    describe("#graphQLErrors", () => {
+        it("should respond with the given GraphQL errors", async () => {
+            // Arrange
+
+            // Act
+            const response = await RespondWith.graphQLErrors([
+                "BOOM!",
+                "BANG!",
+            ]).toPromise();
+            const result = await response.json();
+
+            // Assert
+            expect(result).toStrictEqual({
+                errors: [{message: "BOOM!"}, {message: "BANG!"}],
+            });
+        });
+
+        it("should not settle if the signal is not raised", async () => {
+            // Arrange
+            const settleController = new SettleController();
+            const settleableResponse = RespondWith.graphQLErrors(
+                ["BOOM!", "BANG!"],
+                settleController.signal,
+            ).toPromise();
+            const otherResponse = RespondWith.text("NO SIGNAL").toPromise();
+
+            // Act
+            const firstResponse = await Promise.race([
+                settleableResponse,
+                otherResponse,
+            ]);
+            const result = await firstResponse.text();
+
+            // Assert
+            expect(result).toBe("NO SIGNAL");
+        });
+
+        it("should settle if the signal is raised", async () => {
+            // Arrange
+            const settleController = new SettleController();
+            const settleableResponse = RespondWith.graphQLErrors(
+                ["SIGNALLED"],
+                settleController.signal,
+            ).toPromise();
+            const otherResponse = RespondWith.text("NO SIGNAL").toPromise();
+
+            // Act
+            settleController.settle();
+            const firstResponse = await Promise.race([
+                settleableResponse,
+                otherResponse,
+            ]);
+            const result = await firstResponse.json();
+
+            // Assert
+            expect(result).toStrictEqual({
+                errors: [{message: "SIGNALLED"}],
+            });
+        });
+    });
+});

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

@@ -0,0 +1,29 @@
+// @flow
+import {SettleController} from "../settle-controller.js";
+import {SettleSignal} from "../settle-signal.js";
+
+describe("SettleController", () => {
+    it("should have a signal", () => {
+        // Arrange
+
+        // Act
+        const result = new SettleController();
+
+        // Assert
+        expect(result).toHaveProperty("signal", expect.any(SettleSignal));
+    });
+
+    describe("#settle", () => {
+        it("should settle the signal", () => {
+            // Arrange
+            const controller = new SettleController();
+            const signal = controller.signal;
+
+            // Act
+            controller.settle();
+
+            // Assert
+            expect(signal.settled).toBe(true);
+        });
+    });
+});