@khanacademy/wonder-blocks-testing-core 1.0.2 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @khanacademy/wonder-blocks-testing-core
 
+## 1.1.0
+
+### Minor Changes
+
+-   16565a85: Add support for hard fails to the request mocking features
+
 ## 1.0.2
 
 ### Patch Changes

package/dist/es/index.js

@@ -52,19 +52,33 @@ const fetchRequestMatchesMock = (mock, input, init) => {
 
 const mockRequester = (operationMatcher, operationToString) => {
   const mocks = [];
-  const mockFn = (...args) => {
+  const configuration = {
+    hardFailOnUnmockedRequests: false
+  };
+  const getMatchingMock = (...args) => {
     for (const mock of mocks) {
       if (mock.onceOnly && mock.used) {
         continue;
       }
       if (operationMatcher(mock.operation, ...args)) {
         mock.used = true;
-        return mock.response();
+        return mock;
       }
     }
+    return null;
+  };
+  const mockFn = (...args) => {
+    const matchingMock = getMatchingMock(...args);
+    if (matchingMock) {
+      return matchingMock.response();
+    }
     const operation = operationToString(...args);
-    return Promise.reject(new Error(`No matching mock response found for request:
-    ${operation}`));
+    const noMatchError = new Error(`No matching mock response found for request:
+    ${operation}`);
+    if (configuration.hardFailOnUnmockedRequests) {
+      throw noMatchError;
+    }
+    return Promise.reject(noMatchError);
   };
   const addMockedOperation = (operation, response, onceOnly) => {
     const mockResponse = () => response.toPromise();
@@ -78,6 +92,10 @@ const mockRequester = (operationMatcher, operationToString) => {
   };
   mockFn.mockOperation = (operation, response) => addMockedOperation(operation, response, false);
   mockFn.mockOperationOnce = (operation, response) => addMockedOperation(operation, response, true);
+  mockFn.configure = config => {
+    Object.assign(configuration, config);
+    return mockFn;
+  };
   return mockFn;
 };
 

package/dist/fetch/types.d.ts

@@ -1,9 +1,58 @@
 import type { MockResponse } from "../respond-with";
+import { ConfigureFn } from "../types";
 export type FetchMockOperation = RegExp | string;
-type FetchMockOperationFn = (operation: FetchMockOperation, response: MockResponse<any>) => FetchMockFn;
+interface FetchMockOperationFn {
+    (
+    /**
+     * The operation to match.
+     *
+     * This is a string for an exact match, or a regex. This is compared to
+     * to the URL of the fetch request to determine if it is a matching
+     * request.
+     */
+    operation: FetchMockOperation, 
+    /**
+     * The response to return when the operation is matched.
+     */
+    response: MockResponse<any>): FetchMockFn;
+}
 export type FetchMockFn = {
+    /**
+     * The mock fetch function.
+     *
+     * This function is a drop-in replacement for the fetch function. You should
+     * not need to call this function directly. Just replace the normal fetch
+     * function implementation with this.
+     */
     (input: RequestInfo, init?: RequestInit): Promise<Response>;
+    /**
+     * Mock a fetch operation.
+     *
+     * This adds a response for a given mocked operation. Regardless of how
+     * many times this mock is matched, it will be used.
+     *
+     * @returns The mock fetch function for chaining.
+     */
     mockOperation: FetchMockOperationFn;
+    /**
+     * Mock a fetch operation once.
+     *
+     * This adds a response for a given mocked operation that will only be used
+     * once and discarded.
+     *
+     * @returns The mock fetch function for chaining.
+     */
     mockOperationOnce: FetchMockOperationFn;
+    /**
+     * Configure the mock fetch function with the given configuration.
+     *
+     * This function is provided as a convenience to allow for configuring the
+     * mock fetch function in a fluent manner. The configuration is applied
+     * to all mocks for a given fetch function; the last configuration applied
+     * will be the one that is used for all mocked operations.
+     *
+     * @returns The mock fetch function for chaining.
+     */
+    configure: ConfigureFn<FetchMockOperation, any>;
 };
 export {};

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export { RespondWith } from "./respond-with";
 export { SettleController } from "./settle-controller";
 export type { MockResponse } from "./respond-with";
 export type { FetchMockFn, FetchMockOperation } from "./fetch/types";
-export type { GraphQLJson, MockFn, OperationMock, OperationMatcher, MockOperationFn, } from "./types";
+export type { GraphQLJson, MockFn, OperationMock, OperationMatcher, MockOperationFn, MockConfiguration, ConfigureFn, } from "./types";
 export * from "./harness/types";
 export * as harnessAdapters from "./harness/adapters/adapters";
 export { makeHookHarness } from "./harness/make-hook-harness";

package/dist/index.js

@@ -80,19 +80,33 @@ const fetchRequestMatchesMock = (mock, input, init) => {
 
 const mockRequester = (operationMatcher, operationToString) => {
   const mocks = [];
-  const mockFn = (...args) => {
+  const configuration = {
+    hardFailOnUnmockedRequests: false
+  };
+  const getMatchingMock = (...args) => {
     for (const mock of mocks) {
       if (mock.onceOnly && mock.used) {
         continue;
       }
       if (operationMatcher(mock.operation, ...args)) {
         mock.used = true;
-        return mock.response();
+        return mock;
       }
     }
+    return null;
+  };
+  const mockFn = (...args) => {
+    const matchingMock = getMatchingMock(...args);
+    if (matchingMock) {
+      return matchingMock.response();
+    }
     const operation = operationToString(...args);
-    return Promise.reject(new Error(`No matching mock response found for request:
-    ${operation}`));
+    const noMatchError = new Error(`No matching mock response found for request:
+    ${operation}`);
+    if (configuration.hardFailOnUnmockedRequests) {
+      throw noMatchError;
+    }
+    return Promise.reject(noMatchError);
   };
   const addMockedOperation = (operation, response, onceOnly) => {
     const mockResponse = () => response.toPromise();
@@ -106,6 +120,10 @@ const mockRequester = (operationMatcher, operationToString) => {
   };
   mockFn.mockOperation = (operation, response) => addMockedOperation(operation, response, false);
   mockFn.mockOperationOnce = (operation, response) => addMockedOperation(operation, response, true);
+  mockFn.configure = config => {
+    Object.assign(configuration, config);
+    return mockFn;
+  };
   return mockFn;
 };
 

package/dist/mock-requester.d.ts

@@ -2,4 +2,4 @@ import type { OperationMatcher, MockFn } from "./types";
 /**
  * A generic mock request function for using when mocking fetch or gqlFetch.
  */
-export declare const mockRequester: <TOperationType>(operationMatcher: OperationMatcher<any>, operationToString: (...args: Array<any>) => string) => MockFn<TOperationType>;
+export declare const mockRequester: <TOperationType, TResponseData>(operationMatcher: OperationMatcher<any>, operationToString: (...args: Array<any>) => string) => MockFn<TOperationType, TResponseData>;

package/dist/types.d.ts

@@ -10,11 +10,43 @@ export type GraphQLJson<TData extends Record<any, any>> = {
         message: string;
     }>;
 };
-export type MockFn<TOperationType> = {
+export interface MockFn<TOperationType, TResponseData> {
+    /**
+     * The mock fetch function.
+     *
+     * This function is a drop-in replacement for the fetch function being
+     * mocked. It is recommended that a more strongly-typed definition is
+     * provided in the consuming codebase, as this definition is intentionally
+     * loose to allow for mocking any fetch operation.
+     */
     (...args: Array<any>): Promise<Response>;
-    mockOperation: MockOperationFn<TOperationType>;
-    mockOperationOnce: MockOperationFn<TOperationType>;
-};
+    /**
+     * Mock a fetch operation.
+     *
+     * This adds a response for a given mocked operation of the given type.
+     * Matches are determined by the operation matcher provided to the
+     * mockRequester function that creates the mock fetch function.
+     */
+    mockOperation: MockOperationFn<TOperationType, TResponseData>;
+    /**
+     * Mock a fetch operation once.
+     *
+     * This adds a response for a given mocked operation of the given type that
+     * will only be used once and discarded. Matches are determined by the
+     * operation matcher provided to the mockRequester function that creates the
+     * mock fetch function.
+     */
+    mockOperationOnce: MockOperationFn<TOperationType, TResponseData>;
+    /**
+     * Configure the mock fetch function with the given configuration.
+     *
+     * This function is provided as a convenience to allow for configuring the
+     * mock fetch function in a fluent manner. The configuration is applied
+     * to all mocks for a given fetch function; the last configuration applied
+     * will be the one that is used for all mocked operations.
+     */
+    configure: ConfigureFn<TOperationType, TResponseData>;
+}
 export type OperationMock<TOperation> = {
     operation: TOperation;
     onceOnly: boolean;
@@ -22,4 +54,34 @@ export type OperationMock<TOperation> = {
     response: () => Promise<Response>;
 };
 export type OperationMatcher<TOperation> = (operation: TOperation, ...args: Array<any>) => boolean;
-export type MockOperationFn<TOperationType> = <TOperation extends TOperationType>(operation: TOperation, response: MockResponse<any>) => MockFn<TOperationType>;
+export type MockOperationFn<TOperationType, TResponseData> = <TOperation extends TOperationType>(operation: TOperation, response: MockResponse<TResponseData>) => MockFn<TOperationType, TResponseData>;
+/**
+ * Configuration options for mocked fetches.
+ */
+export type MockConfiguration = {
+    /**
+     * If true, any requests that don't match a mock will throw an error
+     * immediately on the request being made; otherwise, if false, unmatched
+     * requests will return a rejected promise.
+     *
+     * Defaults to false. When true, this is akin to the Apollo MockLink
+     * behavior that throws upon the request being. This is useful as it will
+     * clearly fail a test early, indicating that a request was not mocked.
+     * However, that mode requires all requests to be mocked, which can be
+     * cumbersome and unncessary. Having unmocked requests return a rejected
+     * promise is more flexible and allows for more granular control over
+     * mocking, allowing developers to mock only the requests they care about
+     * and let the error handling of their code deal with the rejected promises.
+     */
+    hardFailOnUnmockedRequests: boolean;
+};
+export interface ConfigureFn<TOperationType, TResponseData> {
+    /**
+     * Configure the mock fetch function with the given configuration.
+     *
+     * @param config The configuration changes to apply to the mock fetch
+     * function.
+     * @returns The mock fetch function .
+     */
+    (config: Partial<MockConfiguration>): MockFn<TOperationType, TResponseData>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanacademy/wonder-blocks-testing-core",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "design": "v1",
   "publishConfig": {
     "access": "public"