@khanacademy/wonder-blocks-testing 2.0.4 → 2.0.7

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @khanacademy/wonder-blocks-testing
 
+## 2.0.7
+
+### Patch Changes
+
+-   Updated dependencies [5ad01891]
+    -   @khanacademy/wonder-blocks-data@6.0.1
+
+## 2.0.6
+
+### Patch Changes
+
+-   Updated dependencies [1f34c4e8]
+-   Updated dependencies [885fe62b]
+-   Updated dependencies [5c852025]
+-   Updated dependencies [c91f3959]
+-   Updated dependencies [5d614ed4]
+-   Updated dependencies [753220a4]
+    -   @khanacademy/wonder-blocks-data@6.0.0
+
+## 2.0.5
+
+### Patch Changes
+
+-   Updated dependencies [c9922b34]
+    -   @khanacademy/wonder-blocks-data@5.0.1
+
 ## 2.0.4
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@khanacademy/wonder-blocks-testing",
-    "version": "2.0.4",
+    "version": "2.0.7",
     "design": "v1",
     "publishConfig": {
         "access": "public"
@@ -14,7 +14,7 @@
     },
     "dependencies": {
         "@babel/runtime": "^7.16.3",
-        "@khanacademy/wonder-blocks-data": "^5.0.0"
+        "@khanacademy/wonder-blocks-data": "^6.0.1"
     },
     "peerDependencies": {
         "@khanacademy/wonder-stuff-core": "^0.1.2",

package/src/__docs__/_overview_.stories.mdx

@@ -0,0 +1,19 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Testing / Overview"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# Wonder Blocks Testing
+
+Wonder Blocks Testing provides various utilities to support testing of React components and Wonder Blocks features.
+
+ * [Fixtures Framework](/docs/testing-fixtures-basic--f-1)
+ * Testing Wonder Blocks Data GraphQL
+   * [`mockGqlFetch`](/docs/testing-exports-mockgqlfetch--page)
+   * [`RespondWith`](/docs/testing-exports-respondwith--page)

package/src/__docs__/exports.mock-gql-fetch.stories.mdx

@@ -0,0 +1,59 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Testing / Exports / mockGqlFetch()"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# mockGqlFetch()
+
+```ts
+mockGqlFetch(): GqlFetchMockFn;
+```
+
+The `mockGqlFetch` function provides an API to easily mock GraphQL responses for use with the [Wonder Blocks Data GraphQL API](/docs/data-graphql--page). It follows the similar patterns of `jest.fn()` and jest mocks whereby the returned value is both a proxy for the fetch function that is used by [`GqlRouter`](/docs/data-exports-gqlrouter--page) as well as an API for modifying the behavior of that function.
+
+# API
+
+Besides being a function that fits the [`GqlFetchFn`](/docs/data-types-gqlfetchfn--page) signature, the return value of `mockGqlFetch()` has an API to customize the behavior of that function. Used in conjunction with the [`RespondWith`](/docs/testing-exports-respondwith--page) API, this can create a variety of GraphQL responses for testing and stories.
+
+| Function | Purpose |
+| -------- | ------- |
+| `mockOperation` | When called, any GraphQL operation that matches the defined mock operation will respond with the given response. |
+| `mockOperationOnce` | When called, the first GraphQL operation that matches the defined mock operation will respond with the given response. The mock is only used by once. |
+
+Both of these functions have the same signature:
+
+```ts
+type GqlMockOperationFn = <TData, TVariables: {...}, TContext: GqlContext>(
+    matchOperation: GqlMockOperation<TData, TVariables, TContext>,
+    response: GqlMockResponse<TData>,
+) => GqlFetchMockFn;
+```
+
+# Operation Matching
+
+The `matchOperation` parameter given to a `mockOperation` or `mockOperationOnce` function is a `GqlMockOperation` defining the actual GraphQL operation to be matched by the mock. The variables and context of the mocked operation change how the mock is matched against requests.
+
+```ts
+ type GqlMockOperation<
+    TData,
+    TVariables: {...},
+    TContext: GqlContext,
+> = {|
+    operation: GqlOperation<TData, TVariables>,
+    variables?: TVariables,
+    context?: TContext,
+|};
+```
+
+1. When `matchOperation.operation` is present but `matchOperation.variables` and `matchOperation.context` are not, the mock will match any request for the
+same operation, regardless of variables or context on the request.
+2. When `matchOperation.variables` is present but `matchOperation.context` is not, the mock will match any request for the same operation with matching variables, regardless of context on the request.
+3. When `matchOperation.context` is present but `matchOperation.variables` is not, the mock will match any request for the same operation with matching context, regardless of variables on the request.
+4. When `matchOperation.variables` and `matchOperation.context` are present, the mock will match any request for the same operation with matching variables and context.
+

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

@@ -0,0 +1,27 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Testing / Exports / RespondWith"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# RespondWith
+
+```ts
+interface RespondWith {
+    data: <TData>(data: TData) => GqlMockResponse<TData>;
+    unparseableBody: () => GqlMockResponse<any>;
+    abortedRequest: () => GqlMockResponse<any>;
+    errorStatusCode: (statusCode: number) => GqlMockResponse<any>,
+    nonGraphQLBody: () => GqlMockResponse<any>,
+    graphQLErrors: (
+        errorMessages: $ReadOnlyArray<string>,
+    ) => GqlMockResponse<any>,
+});
+```
+
+The `RespondWith` object is a helper for defining mock responses to use with the [`mockGqlFetch`](/docs/testing-exports-mockgqlfetch--page) API.

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

@@ -50,7 +50,7 @@ describe("#mockGqlFetch", () => {
                 id: "getMyStuff",
             };
             const data = {myStuff: "stuff"};
-            const RenderError = () => {
+            const RenderData = () => {
                 const [result, setResult] = React.useState(null);
                 const gqlFetch = useGql();
                 React.useEffect(() => {
@@ -68,7 +68,7 @@ describe("#mockGqlFetch", () => {
             mockFetch.mockOperation({operation: query}, RespondWith.data(data));
             render(
                 <GqlRouter defaultContext={{}} fetch={mockFetch}>
-                    <RenderError />
+                    <RenderData />
                 </GqlRouter>,
             );
             const result = screen.getByTestId("result");
@@ -79,7 +79,7 @@ describe("#mockGqlFetch", () => {
             );
         });
 
-        it("should provide null data if aborted response", async () => {
+        it("should reject when request aborted", async () => {
             // Arrange
             const mockFetch = mockGqlFetch();
             const query = {
@@ -91,8 +91,8 @@ describe("#mockGqlFetch", () => {
                 const gqlFetch = useGql();
                 React.useEffect(() => {
                     // eslint-disable-next-line promise/catch-or-return
-                    gqlFetch(query).then((r) => {
-                        setResult(JSON.stringify(r ?? "(null)"));
+                    gqlFetch(query).catch((e) => {
+                        setResult(e.message);
                         return;
                     });
                 }, [gqlFetch]);
@@ -113,7 +113,7 @@ describe("#mockGqlFetch", () => {
             const result = screen.getByTestId("result");
 
             // Assert
-            await waitFor(() => expect(result).toHaveTextContent('"(null)"'));
+            await waitFor(() => expect(result).toHaveTextContent("aborted"));
         });
 
         it("should reject when request gives failed error code", async () => {

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

@@ -49,7 +49,7 @@ describe("integrating mockGqlFetch, RespondWith, GqlRouter and useGql", () => {
             id: "getMyStuff",
         };
         const data = {myStuff: "stuff"};
-        const RenderError = () => {
+        const RenderData = () => {
             const [result, setResult] = React.useState(null);
             const gqlFetch = useGql();
             React.useEffect(() => {
@@ -67,7 +67,7 @@ describe("integrating mockGqlFetch, RespondWith, GqlRouter and useGql", () => {
         mockFetch.mockOperation({operation: query}, RespondWith.data(data));
         render(
             <GqlRouter defaultContext={{}} fetch={mockFetch}>
-                <RenderError />
+                <RenderData />
             </GqlRouter>,
         );
         const result = screen.getByTestId("result");
@@ -78,7 +78,7 @@ describe("integrating mockGqlFetch, RespondWith, GqlRouter and useGql", () => {
         );
     });
 
-    it("should respond with null data for RespondWith.abortedRequest", async () => {
+    it("should reject with AbortError for RespondWith.abortedRequest", async () => {
         // Arrange
         const mockFetch = mockGqlFetch();
         const query = {
@@ -90,8 +90,8 @@ describe("integrating mockGqlFetch, RespondWith, GqlRouter and useGql", () => {
             const gqlFetch = useGql();
             React.useEffect(() => {
                 // eslint-disable-next-line promise/catch-or-return
-                gqlFetch(query).then((r) => {
-                    setResult(JSON.stringify(r ?? "(null)"));
+                gqlFetch(query).catch((e) => {
+                    setResult(e.message);
                     return;
                 });
             }, [gqlFetch]);
@@ -112,7 +112,7 @@ describe("integrating mockGqlFetch, RespondWith, GqlRouter and useGql", () => {
         const result = screen.getByTestId("result");
 
         // Assert
-        await waitFor(() => expect(result).toHaveTextContent('"(null)"'));
+        await waitFor(() => expect(result).toHaveTextContent("aborted"));
     });
 
     it("should reject with unsuccessful response error for RespondWith.errorStatusCode", async () => {