feat: AppLayout error boundaries v2

src/__a11y__/a11y-app-layout-toolbar.test.ts

@@ -10,6 +10,7 @@ const EXCLUDED_PAGES = [
   // Test page for an app layout nested inside another through an iframe.
   // Not a use case that's encouraged.
   'app-layout/multi-layout-global-drawer-child-layout',
+  'app-layout/with-error-boundaries',
 ];
 
 describe('A11y checks for app layout toolbar', () => {

src/__a11y__/run-a11y-tests.ts

@@ -32,6 +32,7 @@ export default function runA11yTests(theme: Theme, mode: Mode, skip: string[] =
         'theming/tokens',
         // this page intentionally has issues to test the helper
         'undefined-texts',
+        'app-layout/with-error-boundaries',
       ];
       const testFunction =
         skipPages.includes(inputUrl) ||

src/app-layout/__integ__/app-layout-error-boundaries.test.ts

@@ -0,0 +1,89 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { BasePageObject } from '@cloudscape-design/browser-test-tools/page-objects';
+import useBrowser from '@cloudscape-design/browser-test-tools/use-browser';
+
+import createWrapper from '../../../lib/components/test-utils/selectors';
+import { getUrlParams } from './utils';
+
+const wrapper = createWrapper().findAppLayout();
+
+const ERROR_BOUNDARY_TEST_SELECTORS = {
+  'left drawer trigger': '[data-testid="break-left-drawer-trigger"]',
+  breadcrumbs: '[data-testid="break-breadcrumbs"]',
+  'local drawer trigger': '[data-testid="break-local-drawer-trigger"]',
+  'global drawer trigger': '[data-testid="break-global-drawer-trigger"]',
+  'left drawer content': '[data-testid="break-left-drawer-content"]',
+  'left drawer header': '[data-testid="break-left-drawer-header"]',
+  'navigation panel': '[data-testid="break-nav-panel"]',
+  'local drawer content': '[data-testid="break-local-drawer-content"]',
+  'global drawer content': '[data-testid="break-global-drawer-content"]',
+  'bottom drawer content': '[data-testid="break-bottom-drawer-content"]',
+} as const;
+
+describe('Visual refresh toolbar only', () => {
+  class PageObject extends BasePageObject {
+    async getConsoleErrorLogs() {
+      const total = (await this.browser.getLogs('browser')) as Array<{
+        level: string;
+        message: string;
+        source: string;
+      }>;
+
+      return total.filter(entry => entry.level === 'SEVERE' && entry.source !== 'network').map(entry => entry.message);
+    }
+
+    async expectConsoleErrors() {
+      const consoleErrors = await this.getConsoleErrorLogs();
+      const errorPattern = /The above error occurred in the .+ component:/;
+      const matchingErrors = consoleErrors.filter(error => errorPattern.test(error));
+      expect(matchingErrors.length).toBeGreaterThan(0);
+    }
+
+    async expectContentAreaStaysFunctional() {
+      await expect(this.getText(wrapper.findContentRegion().toSelector())).resolves.toContain(
+        'Error boundaries in app layout slots'
+      );
+    }
+  }
+  function setupTest({ hasParentErrorBoundary = 'true' }, testFn: (page: PageObject) => Promise<void>) {
+    return useBrowser(async browser => {
+      const page = new PageObject(browser);
+
+      await browser.url(
+        `#/light/app-layout/with-error-boundaries?${getUrlParams('refresh-toolbar', {
+          appLayoutToolbar: 'true',
+          hasParentErrorBoundary,
+        })}`
+      );
+      await page.waitForVisible(wrapper.findContentRegion().toSelector(), true);
+      await testFn(page);
+    });
+  }
+
+  describe('with parent error boundary', () => {
+    Object.entries(ERROR_BOUNDARY_TEST_SELECTORS).forEach(([areaName, selector]) => {
+      test(
+        `should handle error boundary in ${areaName}`,
+        setupTest({ hasParentErrorBoundary: 'true' }, async page => {
+          await page.click(selector);
+          await page.expectConsoleErrors();
+          await page.expectContentAreaStaysFunctional();
+        })
+      );
+    });
+  });
+
+  describe('without parent error boundary', () => {
+    Object.entries(ERROR_BOUNDARY_TEST_SELECTORS).forEach(([areaName, selector]) => {
+      test(
+        `should handle error boundary in ${areaName}`,
+        setupTest({ hasParentErrorBoundary: 'false' }, async page => {
+          await page.click(selector);
+          await page.expectConsoleErrors();
+          await page.expectContentAreaStaysFunctional();
+        })
+      );
+    });
+  });
+});

src/app-layout/__tests__/widget-areas-error-boundaries.test.tsx

@@ -0,0 +1,284 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React from 'react';
+import { render } from '@testing-library/react';
+
+import AppLayout from '../../../lib/components/app-layout';
+import ErrorBoundary from '../../../lib/components/error-boundary';
+import awsuiPlugins from '../../../lib/components/internal/plugins';
+import { DrawerConfig } from '../../../lib/components/internal/plugins/controllers/drawers';
+import * as awsuiWidgetPlugins from '../../../lib/components/internal/plugins/widget';
+import createWrapper, { ErrorBoundaryWrapper } from '../../../lib/components/test-utils/dom';
+import { describeEachAppLayout, getGlobalDrawersTestUtils } from './utils';
+
+const drawerDefaults: DrawerConfig = {
+  id: 'test',
+  ariaLabels: {},
+  trigger: { iconSvg: 'icon placeholder' },
+  mountContent: container => (container.textContent = 'runtime drawer content'),
+  unmountContent: () => {},
+};
+
+function renderComponent(jsx: React.ReactElement) {
+  const { container, rerender, getByTestId, ...rest } = render(jsx);
+  const wrapper = createWrapper(container).findAppLayout()!;
+  const errorBoundaryWrapper = createWrapper(container).findErrorBoundary()!;
+  const globalDrawersWrapper = getGlobalDrawersTestUtils(wrapper);
+  return {
+    wrapper,
+    errorBoundaryWrapper,
+    globalDrawersWrapper,
+    rerender,
+    getByTestId,
+    container,
+    ...rest,
+  };
+}
+
+beforeEach(() => {
+  jest.resetAllMocks();
+});
+
+describe('AppLayout error boundaries: errors in different areas does not crash the entire app layout', () => {
+  const ThrowError = ({ message = 'Test error' }: { message?: string }) => {
+    throw new Error(message);
+  };
+
+  const expectInvisibleErrorBoundary = (errorBoundaryWrapper: ErrorBoundaryWrapper) => {
+    expect(errorBoundaryWrapper.getElement()).toBeInTheDocument();
+    expect(errorBoundaryWrapper.findHeader()).toBeFalsy();
+    expect(errorBoundaryWrapper.findDescription()).toBeFalsy();
+    expect(errorBoundaryWrapper.findAction()).toBeFalsy();
+  };
+
+  describeEachAppLayout({ themes: ['refresh-toolbar'] }, () => {
+    describe.each([true, false])(
+      'entire AppLayout wrapped with error boundary component : %p',
+      (wrappedWithErrorBoundary: boolean) => {
+        const onError = jest.fn();
+        const consoleSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+        const AppLayoutWrapper = wrappedWithErrorBoundary ? ErrorBoundary : 'div';
+        const appLayoutWrapperProps = wrappedWithErrorBoundary ? { onError } : {};
+        const content = <div>content</div>;
+
+        const expectErrorCallbacksToBeCalled = () => {
+          if (wrappedWithErrorBoundary) {
+            expect(onError).toHaveBeenCalled();
+          }
+          expect(consoleSpy).toHaveBeenCalled();
+        };
+
+        test('left drawer content', () => {
+          awsuiWidgetPlugins.registerLeftDrawer({
+            defaultActive: true,
+            ...drawerDefaults,
+            id: '1',
+            trigger: undefined,
+            mountContent: () => {
+              throw new Error('Mount error in drawer content');
+            },
+          });
+          const { errorBoundaryWrapper, wrapper } = renderComponent(
+            <AppLayoutWrapper {...(appLayoutWrapperProps as any)}>
+              <AppLayout content={content} />
+            </AppLayoutWrapper>
+          );
+
+          expect(wrapper.findContentRegion().getElement()).toHaveTextContent('content');
+          expectInvisibleErrorBoundary(errorBoundaryWrapper);
+          expectErrorCallbacksToBeCalled();
+        });
+
+        test('left drawer header', () => {
+          awsuiWidgetPlugins.registerLeftDrawer({
+            ...drawerDefaults,
+            id: '2',
+            defaultActive: true,
+            trigger: undefined,
+            mountHeader: () => {
+              throw new Error('Mount error in drawer content');
+            },
+          });
+          const { errorBoundaryWrapper, wrapper } = renderComponent(
+            <AppLayoutWrapper {...(appLayoutWrapperProps as any)}>
+              <AppLayout content={content} />
+            </AppLayoutWrapper>
+          );
+
+          expect(wrapper.findContentRegion().getElement()).toHaveTextContent('content');
+          expectInvisibleErrorBoundary(errorBoundaryWrapper);
+          expectErrorCallbacksToBeCalled();
+        });
+
+        test('left drawer trigger', () => {
+          awsuiWidgetPlugins.registerLeftDrawer({
+            ...drawerDefaults,
+            id: '3',
+            trigger: {
+              iconSvg: Symbol() as any,
+            },
+          });
+          const { errorBoundaryWrapper, wrapper } = renderComponent(
+            <AppLayoutWrapper {...(appLayoutWrapperProps as any)}>
+              <AppLayout content={content} />
+            </AppLayoutWrapper>
+          );
+
+          expect(wrapper.findContentRegion().getElement()).toHaveTextContent('content');
+          expectInvisibleErrorBoundary(errorBoundaryWrapper);
+          expectErrorCallbacksToBeCalled();
+        });
+
+        test('breadcrumbs', () => {
+          const { errorBoundaryWrapper, wrapper } = renderComponent(
+            <AppLayoutWrapper {...(appLayoutWrapperProps as any)}>
+              <AppLayout content={content} breadcrumbs={<ThrowError message="Breadcrumbs error" />} />
+            </AppLayoutWrapper>
+          );
+
+          expect(wrapper.findContentRegion().getElement()).toHaveTextContent('content');
+          expectInvisibleErrorBoundary(errorBoundaryWrapper);
+          expectErrorCallbacksToBeCalled();
+        });
+
+        test('local drawer trigger', () => {
+          awsuiPlugins.appLayout.registerDrawer({
+            ...drawerDefaults,
+            type: 'local',
+            trigger: {
+              iconSvg: Symbol() as any,
+            },
+          });
+
+          const { errorBoundaryWrapper, wrapper } = renderComponent(
+            <AppLayoutWrapper {...(appLayoutWrapperProps as any)}>
+              <AppLayout content={content} />
+            </AppLayoutWrapper>
+          );
+
+          expect(wrapper.findContentRegion().getElement()).toHaveTextContent('content');
+          expectInvisibleErrorBoundary(errorBoundaryWrapper);
+          expectErrorCallbacksToBeCalled();
+        });
+
+        test('global drawer trigger', () => {
+          awsuiPlugins.appLayout.registerDrawer({
+            ...drawerDefaults,
+            type: 'global',
+            trigger: {
+              iconSvg: Symbol() as any,
+            },
+          });
+
+          const { errorBoundaryWrapper, wrapper } = renderComponent(
+            <AppLayoutWrapper {...(appLayoutWrapperProps as any)}>
+              <AppLayout content={content} />
+            </AppLayoutWrapper>
+          );
+
+          expect(wrapper.findContentRegion().getElement()).toHaveTextContent('content');
+          expectInvisibleErrorBoundary(errorBoundaryWrapper);
+          expectErrorCallbacksToBeCalled();
+        });
+
+        test('nav panel', () => {
+          const { errorBoundaryWrapper, wrapper } = renderComponent(
+            <AppLayoutWrapper {...(appLayoutWrapperProps as any)}>
+              <AppLayout
+                content={content}
+                navigation={<ThrowError message="Breadcrumbs error" />}
+                navigationOpen={true}
+              />
+            </AppLayoutWrapper>
+          );
+
+          expect(wrapper.findContentRegion().getElement()).toHaveTextContent('content');
+          expectInvisibleErrorBoundary(errorBoundaryWrapper);
+          expectErrorCallbacksToBeCalled();
+        });
+
+        test('local drawer content', () => {
+          awsuiPlugins.appLayout.registerDrawer({
+            ...drawerDefaults,
+            type: 'local',
+            mountContent: () => {
+              throw new Error('Mount error in drawer content');
+            },
+          });
+
+          const { errorBoundaryWrapper, wrapper } = renderComponent(
+            <AppLayoutWrapper {...(appLayoutWrapperProps as any)}>
+              <AppLayout content={content} />
+            </AppLayoutWrapper>
+          );
+
+          expect(wrapper.findContentRegion().getElement()).toHaveTextContent('content');
+          expectInvisibleErrorBoundary(errorBoundaryWrapper);
+          expectErrorCallbacksToBeCalled();
+        });
+
+        test('global drawer content', () => {
+          awsuiPlugins.appLayout.registerDrawer({
+            ...drawerDefaults,
+            type: 'global',
+            mountContent: () => {
+              throw new Error('Mount error in drawer content');
+            },
+          });
+
+          const { errorBoundaryWrapper, wrapper } = renderComponent(
+            <AppLayoutWrapper {...(appLayoutWrapperProps as any)}>
+              <AppLayout content={content} />
+            </AppLayoutWrapper>
+          );
+
+          expect(wrapper.findContentRegion().getElement()).toHaveTextContent('content');
+          expectInvisibleErrorBoundary(errorBoundaryWrapper);
+          expectErrorCallbacksToBeCalled();
+        });
+
+        test('bottom drawer content', () => {
+          awsuiWidgetPlugins.registerBottomDrawer({
+            defaultActive: true,
+            ...drawerDefaults,
+            id: '4',
+            mountContent: () => {
+              throw new Error('Mount error in drawer content');
+            },
+          });
+
+          const { errorBoundaryWrapper, wrapper } = renderComponent(
+            <AppLayoutWrapper {...(appLayoutWrapperProps as any)}>
+              <AppLayout content={content} />
+            </AppLayoutWrapper>
+          );
+
+          expect(wrapper.findContentRegion().getElement()).toHaveTextContent('content');
+          expectInvisibleErrorBoundary(errorBoundaryWrapper);
+          expectErrorCallbacksToBeCalled();
+        });
+
+        test('content area error are not caught by app layout error boundaries', () => {
+          if (wrappedWithErrorBoundary) {
+            const { errorBoundaryWrapper } = renderComponent(
+              <AppLayoutWrapper {...(appLayoutWrapperProps as any)}>
+                <AppLayout content={<ThrowError />} />
+              </AppLayoutWrapper>
+            );
+
+            expectInvisibleErrorBoundary(errorBoundaryWrapper);
+            expectErrorCallbacksToBeCalled();
+          } else {
+            expect(() =>
+              render(
+                <AppLayoutWrapper {...(appLayoutWrapperProps as any)}>
+                  <AppLayout content={<ThrowError />} />
+                </AppLayoutWrapper>
+              )
+            ).toThrow('Test error');
+          }
+        });
+      }
+    );
+  });
+});