Merge pull request #811 from bcgsc/feat/DEVSU-2982-404-render-test

[DEVSU-2982] 404 render test addon

Author: kttkjl

.eslintrc.js

@@ -38,8 +38,22 @@ module.exports = {
   },
   overrides: [
     {
+      // Build/test tooling that tsconfig.json deliberately does not include.
+      // Type-aware linting needs the file to be in the project, so these are
+      // linted with the type-checked rules (and parserOptions.project) off.
       extends: ['plugin:@typescript-eslint/disable-type-checked'],
-      files: ['./*.js'],
+      files: ['./*.js', './config/jest/**/*.js'],
+      env: {
+        jest: true,
+        node: true,
+      },
+      rules: {
+        // These files are CommonJS by necessity: webpack and jest load them outside the app's module pipeline
+        '@typescript-eslint/no-var-requires': 'off',
+        'import/no-extraneous-dependencies': 'off',
+        // Setup files legitimately declare several small mock classes
+        'max-classes-per-file': 'off',
+      },
     },
   ],
 };

app/hooks/__tests__/useApiError.test.ts

@@ -0,0 +1,97 @@
+import { renderHook } from '@testing-library/react';
+
+import snackbar from '@/services/SnackbarUtils';
+import { makeApiError } from '@/test/apiErrorHelpers';
+import useApiError, { getStatus } from '../useApiError';
+
+jest.mock('@/services/SnackbarUtils');
+
+describe('useApiError', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    (console.error as jest.Mock).mockRestore();
+  });
+
+  describe('getStatus', () => {
+    test('reads the status attached by errorHandler', () => {
+      expect(getStatus(makeApiError(404))).toBe(404);
+      expect(getStatus(makeApiError(500, 'Server Error'))).toBe(500);
+    });
+
+    test('is undefined for errors without a response', () => {
+      expect(getStatus(new Error('network down'))).toBeUndefined();
+      expect(getStatus(undefined)).toBeUndefined();
+    });
+  });
+
+  describe('in the browser view', () => {
+    test('reportError shows a labelled snackbar', () => {
+      const { result } = renderHook(() => useApiError(false));
+
+      result.current.reportError('Failed to load comparators', makeApiError(404));
+
+      expect(snackbar.error).toHaveBeenCalledTimes(1);
+      expect(snackbar.error).toHaveBeenCalledWith('Failed to load comparators: Not Found');
+    });
+
+    test('reportErrorSkip404 logs but shows no snackbar on 404', () => {
+      const { result } = renderHook(() => useApiError(false));
+
+      result.current.reportErrorSkip404('Failed to load TMB', makeApiError(404));
+
+      expect(snackbar.error).not.toHaveBeenCalled();
+      expect(console.error).toHaveBeenCalled();
+    });
+
+    test('reportErrorSkip404 still reports other statuses', () => {
+      const { result } = renderHook(() => useApiError(false));
+
+      result.current.reportErrorSkip404('Failed to load TMB', makeApiError(500, 'Server Error'));
+
+      expect(snackbar.error).toHaveBeenCalledWith('Failed to load TMB: Server Error');
+    });
+
+    test('queryOnError returns a handler usable as a react-query onError', () => {
+      const { result } = renderHook(() => useApiError(false));
+
+      result.current.queryOnError('Failed to load MSI')(makeApiError(404));
+
+      expect(snackbar.error).toHaveBeenCalledWith('Failed to load MSI: Not Found');
+    });
+  });
+
+  describe('in the print view', () => {
+    test('reportError logs but shows no snackbar', () => {
+      const { result } = renderHook(() => useApiError(true));
+
+      result.current.reportError('Failed to load comparators', makeApiError(404));
+
+      expect(snackbar.error).not.toHaveBeenCalled();
+      expect(console.error).toHaveBeenCalled();
+    });
+
+    test('queryOnError shows no snackbar', () => {
+      const { result } = renderHook(() => useApiError(true));
+
+      result.current.queryOnError('Failed to load MSI')(makeApiError(500, 'Server Error'));
+
+      expect(snackbar.error).not.toHaveBeenCalled();
+    });
+  });
+
+  test('handlers are stable across re-renders with the same isPrint', () => {
+    const { result, rerender } = renderHook(({ isPrint }) => useApiError(isPrint), {
+      initialProps: { isPrint: false },
+    });
+    const first = result.current;
+
+    rerender({ isPrint: false });
+
+    expect(result.current.reportError).toBe(first.reportError);
+    expect(result.current.queryOnError).toBe(first.queryOnError);
+  });
+});

app/hooks/useApiError.ts

@@ -0,0 +1,90 @@
+import { useCallback, useMemo } from 'react';
+
+import snackbar from '@/services/SnackbarUtils';
+import { ErrorMixin } from '@/services/errors/errors';
+
+type ApiError = Error | ErrorMixin;
+
+/**
+ * Status code attached by `errorHandler` when the server responded with a
+ * non-2xx code. Absent for network/parse failures.
+ */
+const getStatus = (err: unknown): number | undefined => (
+  (err as ErrorMixin)?.content?.status as number | undefined
+);
+
+const getMessage = (err: unknown): string => {
+  if (err instanceof Error) {
+    return err.message;
+  }
+  return String(err);
+};
+
+type UseApiErrorReturnType = {
+  /**
+   * For imperative `try`/`catch` blocks. Logs always; shows a snackbar only
+   * outside of print.
+   */
+  reportError: (label: string, err: unknown) => void;
+  /** As `reportError`, but stays silent for 404s. */
+  reportErrorSkip404: (label: string, err: unknown) => void;
+  /** `onError` handler for react-query options. */
+  queryOnError: (label: string) => (err: ApiError) => void;
+  /** As `queryOnError`, but stays silent for 404s. */
+  queryOnErrorSkip404: (label: string) => (err: ApiError) => void;
+};
+
+/**
+ * Consistent API failure reporting for report sections.
+ *
+ * A section must keep rendering when one of its requests fails, so every
+ * consumer of this hook is expected to tolerate missing data rather than bail
+ * out. The hook only decides how the failure is surfaced:
+ *
+ * - the browser view gets a labelled error snackbar so the user knows which
+ *   part of the page is incomplete
+ * - the print view gets a console error only, since a snackbar would be
+ *   captured in the printed output and there is nobody to dismiss it
+ *
+ * 404 is treated as "this resource does not exist for this report", which is a
+ * normal state for many optional sections, hence the `Skip404` variants.
+ *
+ * @param isPrint true when rendering inside PrintView
+ */
+const useApiError = (isPrint = false): UseApiErrorReturnType => {
+  const reportError = useCallback((label: string, err: unknown) => {
+    console.error(label, err);
+    if (!isPrint) {
+      snackbar.error(`${label}: ${getMessage(err)}`);
+    }
+  }, [isPrint]);
+
+  const reportErrorSkip404 = useCallback((label: string, err: unknown) => {
+    if (getStatus(err) === 404) {
+      // Still logged so the absence is traceable, but not worth interrupting
+      // the user over: the resource simply does not exist for this report
+      console.error(label, err);
+      return;
+    }
+    reportError(label, err);
+  }, [reportError]);
+
+  const queryOnError = useCallback((label: string) => (
+    (err: ApiError) => reportError(label, err)
+  ), [reportError]);
+
+  const queryOnErrorSkip404 = useCallback((label: string) => (
+    (err: ApiError) => reportErrorSkip404(label, err)
+  ), [reportErrorSkip404]);
+
+  return useMemo(() => ({
+    reportError,
+    reportErrorSkip404,
+    queryOnError,
+    queryOnErrorSkip404,
+  }), [reportError, reportErrorSkip404, queryOnError, queryOnErrorSkip404]);
+};
+
+export type { UseApiErrorReturnType };
+export { getStatus };
+export default useApiError;

app/test/apiErrorHelpers.ts

@@ -0,0 +1,57 @@
+import { APIConnectionFailureError } from '@/services/errors/errors';
+
+/**
+ * Builds the error a component actually receives from `api.get(...).request()`
+ * when the server responds with a non-2xx code.
+ *
+ * `errorHandler` maps 404 onto `APIConnectionFailureError` and attaches the
+ * status under `content.status`, which is what `useApiError`'s Skip404
+ * variants and the react-query `retry` predicate both key off. Constructing a
+ * plain `Error` in a test would therefore exercise a different code path.
+ *
+ * @param status HTTP status code, defaults to 404
+ * @param message server supplied message
+ */
+const makeApiError = (status = 404, message = 'Not Found'): Error => {
+  const err = new APIConnectionFailureError({ message, status });
+  return err as unknown as Error;
+};
+
+/**
+ * `ApiCallSet` mock factory. `request(settled)` mirrors the real class:
+ * `Promise.all` semantics when called without arguments, `Promise.allSettled`
+ * results when called with `true`.
+ *
+ * @param outcomes one entry per call in the set, in order. An `Error` value
+ * marks that call as rejected, anything else as resolved with that value.
+ */
+const mockApiCallSet = (outcomes: unknown[]) => () => ({
+  request: jest.fn(async (settled = false) => {
+    if (settled) {
+      return outcomes.map((outcome) => (
+        outcome instanceof Error
+          ? { status: 'rejected' as const, reason: outcome }
+          : { status: 'fulfilled' as const, value: outcome }
+      ));
+    }
+    const rejected = outcomes.find((outcome) => outcome instanceof Error);
+    if (rejected) {
+      throw rejected;
+    }
+    return outcomes;
+  }),
+  abort: jest.fn(),
+});
+
+/**
+ * Marks the call at `index` as a 404 and resolves every other call in the set
+ * with the matching entry of `resolved`.
+ *
+ * @param resolved the happy path values for the whole set
+ * @param index which call should 404
+ */
+const mockApiCallSetWith404At = (resolved: unknown[], index: number) => mockApiCallSet(
+  resolved.map((value, i) => (i === index ? makeApiError() : value)),
+);
+
+export { makeApiError, mockApiCallSet, mockApiCallSetWith404At };

app/utils/__tests__/settleApiCalls.test.ts

@@ -0,0 +1,55 @@
+import { makeApiError } from '@/test/apiErrorHelpers';
+import { unwrapSettled } from '../settleApiCalls';
+
+describe('unwrapSettled', () => {
+  const settle = (outcomes: unknown[]): PromiseSettledResult<unknown>[] => outcomes.map(
+    (outcome) => (outcome instanceof Error
+      ? { status: 'rejected' as const, reason: outcome }
+      : { status: 'fulfilled' as const, value: outcome }),
+  );
+
+  test('returns every value positionally when all calls resolve', () => {
+    const onError = jest.fn();
+
+    const result = unwrapSettled(settle([['a'], ['b'], ['c']]), ['a', 'b', 'c'], onError);
+
+    expect(result).toEqual([['a'], ['b'], ['c']]);
+    expect(onError).not.toHaveBeenCalled();
+  });
+
+  test('keeps the resolved values when one call 404s', () => {
+    const onError = jest.fn();
+    const err = makeApiError(404);
+
+    const result = unwrapSettled(
+      settle([['variants'], err, ['images']]),
+      ['load variants', 'load circos', 'load images'],
+      onError,
+    );
+
+    expect(result).toEqual([['variants'], undefined, ['images']]);
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(onError).toHaveBeenCalledWith('load circos', err);
+  });
+
+  test('reports each failure separately', () => {
+    const onError = jest.fn();
+
+    unwrapSettled(
+      settle([makeApiError(404), ['ok'], makeApiError(500, 'Server Error')]),
+      ['first', 'second', 'third'],
+      onError,
+    );
+
+    expect(onError).toHaveBeenCalledTimes(2);
+    expect(onError.mock.calls.map(([label]) => label)).toEqual(['first', 'third']);
+  });
+
+  test('falls back to a positional label when labels are missing', () => {
+    const onError = jest.fn();
+
+    unwrapSettled(settle([makeApiError(404)]), [], onError);
+
+    expect(onError).toHaveBeenCalledWith('request 1', expect.any(Error));
+  });
+});

app/utils/settleApiCalls.ts

@@ -0,0 +1,32 @@
+/**
+ * Helpers for working with `ApiCallSet.request(true)`, which resolves to
+ * `Promise.allSettled` results so that one failing call (e.g. a 404 for a
+ * resource that simply does not exist on this report) does not discard the
+ * responses of every other call in the set.
+ */
+
+type SettleErrorHandler = (label: string, err: unknown) => void;
+
+/**
+ * Maps settled results back onto a positional tuple, substituting `undefined`
+ * for any call that rejected and reporting it through `onError`.
+ *
+ * @param results settled results, in the same order the calls were pushed
+ * @param labels human readable name per call, used in the error message
+ * @param onError invoked once per rejected call
+ */
+const unwrapSettled = <T extends unknown[]>(
+  results: PromiseSettledResult<unknown>[],
+  labels: string[],
+  onError: SettleErrorHandler,
+): Partial<T> => results.map((result, index) => {
+    if (result.status === 'fulfilled') {
+      return result.value;
+    }
+    onError(labels[index] ?? `request ${index + 1}`, result.reason);
+    return undefined;
+  }) as Partial<T>;
+
+export type { SettleErrorHandler };
+export { unwrapSettled };
+export default unwrapSettled;