test: Add OptionList unit and integration tests

Author: amanabiy

src/internal/components/listbox/__tests__/plain-list.test.tsx

@@ -0,0 +1,70 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React from 'react';
+import { act, render } from '@testing-library/react';
+
+import PlainList from '../../../../../lib/components/internal/components/listbox/parts/plain-list';
+import { flattenOptions } from '../../../../../lib/components/internal/components/option/utils/flatten-options';
+import { HighlightType } from '../../../../../lib/components/internal/components/options-list/utils/use-highlight-option';
+import type { GetOptionProps, ScrollToIndexRef } from '../interfaces';
+import type { ItemProps } from '../parts/item';
+import type { ListProps } from '../parts/plain-list';
+
+const { flatOptions } = flattenOptions([
+  { value: 'a', label: 'A' },
+  { value: 'b', label: 'B' },
+]);
+
+const getOptionProps: GetOptionProps = (option, index) => ({ option, index, 'data-mouse-target': index }) as ItemProps;
+
+function renderPlainList(scrollStrategy?: ListProps['scrollStrategy']) {
+  const scrollToIndex = React.createRef<ScrollToIndexRef>();
+  const listRef = React.createRef<HTMLDivElement>();
+  render(
+    <PlainList
+      ref={scrollToIndex}
+      listProps={{ ref: listRef, open: true, embedded: true }}
+      getOptionProps={getOptionProps}
+      filteredOptions={flatOptions}
+      filteringValue=""
+      highlightType={new HighlightType('keyboard')}
+      scrollStrategy={scrollStrategy}
+    />
+  );
+  const list = listRef.current!;
+  const item = list.querySelector<HTMLElement>('[data-mouse-target="1"]')!;
+  return { scrollTo: (index: number) => act(() => scrollToIndex.current!(index)), list, item };
+}
+
+describe('PlainList scrollStrategy', () => {
+  const originalScrollIntoView = HTMLElement.prototype.scrollIntoView;
+  let scrollIntoView: jest.Mock;
+
+  beforeEach(() => {
+    scrollIntoView = HTMLElement.prototype.scrollIntoView = jest.fn();
+  });
+  afterEach(() => {
+    HTMLElement.prototype.scrollIntoView = originalScrollIntoView;
+  });
+
+  test('ancestors: scrolls the option into view through all scrollable ancestors', () => {
+    const { scrollTo, list, item } = renderPlainList('ancestors');
+    list.scrollBy = jest.fn();
+    scrollTo(1);
+    expect(scrollIntoView).toHaveBeenCalledTimes(1);
+    expect(scrollIntoView.mock.instances[0]).toBe(item);
+    expect(list.scrollBy).not.toHaveBeenCalled();
+  });
+
+  test('scrolls only the list by default', () => {
+    const { scrollTo, list, item } = renderPlainList();
+    // jsdom has no layout, so give the list a height and place the option below its visible area.
+    Object.defineProperty(list, 'clientHeight', { value: 100 });
+    list.getBoundingClientRect = () => ({ top: 0, bottom: 100, height: 100 }) as DOMRect;
+    item.getBoundingClientRect = () => ({ top: 200, bottom: 250, height: 50 }) as DOMRect;
+    list.scrollBy = jest.fn();
+    scrollTo(1);
+    expect(list.scrollBy).toHaveBeenCalledWith({ top: 150 });
+    expect(scrollIntoView).not.toHaveBeenCalled();
+  });
+});

src/internal/components/listbox/__tests__/scroll-to-index.test.ts

@@ -1,6 +1,6 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
-import scrollToIndex from '../parts/scroll-to-index';
+import scrollToIndex, { scrollOptionIntoView } from '../parts/scroll-to-index';
 
 describe('scroll-to-index', () => {
   function runWith({
@@ -168,3 +168,44 @@ describe('scroll-to-index', () => {
     });
   });
 });
+
+describe('scrollOptionIntoView', () => {
+  const originalScrollIntoView = HTMLElement.prototype.scrollIntoView;
+  let scrollIntoView: jest.Mock;
+
+  beforeEach(() => {
+    scrollIntoView = HTMLElement.prototype.scrollIntoView = jest.fn();
+  });
+  afterEach(() => {
+    HTMLElement.prototype.scrollIntoView = originalScrollIntoView;
+  });
+
+  function createMenu(mouseTargets: number[]) {
+    const menuEl = document.createElement('div');
+    for (const mouseTarget of mouseTargets) {
+      const item = document.createElement('div');
+      item.dataset.mouseTarget = `${mouseTarget}`;
+      menuEl.appendChild(item);
+    }
+    return menuEl;
+  }
+
+  it('scrolls the option at the index into view through its scrollable ancestors', () => {
+    const menuEl = createMenu([0, 1, 2]);
+    scrollOptionIntoView({ index: 2, menuEl });
+    expect(scrollIntoView).toHaveBeenCalledTimes(1);
+    expect(scrollIntoView.mock.instances[0]).toBe(menuEl.children[2]);
+    expect(scrollIntoView).toHaveBeenCalledWith({ block: 'nearest', inline: 'nearest' });
+  });
+
+  it('does not scroll when nothing is highlighted, even if a non-interactive row uses index -1', () => {
+    // Non-interactive rows such as single-selection group headers render with data-mouse-target="-1".
+    scrollOptionIntoView({ index: -1, menuEl: createMenu([-1, 0, 1]) });
+    expect(scrollIntoView).not.toHaveBeenCalled();
+  });
+
+  it('does not scroll when no option has the index', () => {
+    scrollOptionIntoView({ index: 5, menuEl: createMenu([0, 1]) });
+    expect(scrollIntoView).not.toHaveBeenCalled();
+  });
+});

src/internal/components/options-list/__tests__/options-list.test.tsx

@@ -119,3 +119,13 @@ test('onLoadMore is called when dropdown is open and status type changes to "pen
 
   expect(onLoadMore).toHaveBeenCalledTimes(2);
 });
+
+test('onLoadMore does not fire on open when statusType is omitted', () => {
+  const onLoadMore = jest.fn();
+  render(
+    <OptionsList open={true} onLoadMore={onLoadMore}>
+      <div>Option</div>
+    </OptionsList>
+  );
+  expect(onLoadMore).not.toHaveBeenCalled();
+});

src/internal/components/options-list/__tests__/use-keyboard.test.ts

@@ -105,6 +105,16 @@ describe('useMenuKeyboard', () => {
     expect(menuKeys.escape.preventDefault).not.toHaveBeenCalled();
   });
 
+  test('does not stop propagation when onEscape is omitted', () => {
+    const escape = { detail: { keyCode: KeyCode.escape }, preventDefault: jest.fn(), stopPropagation: jest.fn() };
+    const hook = renderHook(useMenuKeyboard, {
+      initialProps: { ...menuInitialProps, onEscape: undefined },
+    });
+    act(() => hook.result.current(escape as any));
+    expect(escape.stopPropagation).not.toHaveBeenCalled();
+    expect(escape.preventDefault).not.toHaveBeenCalled();
+  });
+
   test('should select option when pressing enter', () => {
     const selectOption = jest.fn();
     const hook = renderHook(useMenuKeyboard, {

src/option-list/__integ__/option-list-scroll.test.ts

@@ -0,0 +1,134 @@
+// 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';
+
+const list = createWrapper().findOptionList('[data-testid="option-list"]');
+const listbox = `${list.toSelector()} [role="listbox"]`;
+
+class ScrollPage extends BasePageObject {
+  /** Whether the highlighted option is inside the viewport and inside every scrolling ancestor. */
+  isHighlightVisible() {
+    return this.browser.execute(selector => {
+      const option = document.querySelector(selector);
+      if (!option) {
+        return false;
+      }
+      const rect = option.getBoundingClientRect();
+      const within = (top: number, bottom: number) => rect.top >= top - 1 && rect.bottom <= bottom + 1;
+      for (let parent = option.parentElement; parent; parent = parent.parentElement) {
+        const { overflowY } = getComputedStyle(parent);
+        if ((overflowY === 'auto' || overflowY === 'scroll') && parent.scrollHeight > parent.clientHeight) {
+          const parentRect = parent.getBoundingClientRect();
+          if (!within(parentRect.top + parent.clientTop, parentRect.top + parent.clientTop + parent.clientHeight)) {
+            return false;
+          }
+        }
+      }
+      return within(0, window.innerHeight);
+    }, list.findHighlightedOption().toSelector());
+  }
+
+  getHighlightedText() {
+    return this.getText(list.findHighlightedOption().findLabel().toSelector());
+  }
+
+  /** Scrolls the list's nearest scroll container (or the page) back to the top, away from the highlight. */
+  scrollToTop() {
+    return this.browser.execute(selector => {
+      for (let parent = document.querySelector(selector)!.parentElement; parent; parent = parent.parentElement) {
+        const { overflowY } = getComputedStyle(parent);
+        if ((overflowY === 'auto' || overflowY === 'scroll') && parent.scrollHeight > parent.clientHeight) {
+          parent.scrollTop = 0;
+          return;
+        }
+      }
+      window.scrollTo(0, 0);
+    }, listbox);
+  }
+
+  /** Retries the visibility check for a short time, so it doesn't run before a scroll has settled. */
+  async waitForHighlightVisible() {
+    await this.waitForAssertion(() => expect(this.isHighlightVisible()).resolves.toBe(true));
+  }
+
+  async expectHighlightVisibleAfter(keys: string[], label: string) {
+    await this.keys(keys);
+    await expect(this.getHighlightedText()).resolves.toBe(label);
+    await this.waitForHighlightVisible();
+  }
+
+  async assertKeyboardScrolling() {
+    // Arrow keys call preventDefault, so the browser doesn't scroll on its own: every scroll here comes from the list.
+    await this.expectHighlightVisibleAfter(new Array(30).fill('ArrowDown'), 'Option 31');
+    await this.expectHighlightVisibleAfter(new Array(30).fill('ArrowUp'), 'Option 1');
+
+    // Wrapping around jumps between the two ends of the list.
+    await this.expectHighlightVisibleAfter(['ArrowUp'], 'Option 100');
+    await this.expectHighlightVisibleAfter(['ArrowDown'], 'Option 1');
+    await this.expectHighlightVisibleAfter(['ArrowUp'], 'Option 100');
+
+    // Scroll away from the highlight, so the next move has to scroll back to it.
+    await this.scrollToTop();
+    await this.expectHighlightVisibleAfter(['ArrowUp'], 'Option 99');
+
+    // Home and End don't call preventDefault, so the browser also starts its native scroll. That scroll is animated
+    // and keeps running after the key press, so it would move the page under any later check. Check them last, and
+    // only check where they move the highlight.
+    await this.keys(['End']);
+    await expect(this.getHighlightedText()).resolves.toBe('Option 100');
+    await this.keys(['Home']);
+    await expect(this.getHighlightedText()).resolves.toBe('Option 1');
+  }
+}
+
+const setupTest = (url: string, testFn: (page: ScrollPage) => Promise<void>) =>
+  useBrowser({ width: 1200, height: 800 }, async browser => {
+    await browser.url(url);
+    const page = new ScrollPage(browser);
+    await page.waitForVisible('h1');
+    await testFn(page);
+  });
+
+describe('OptionList keyboard scrolling', () => {
+  describe.each(['wrapper', 'page'])('container=%s', container => {
+    const focusList = async (page: ScrollPage) => {
+      await page.click('#option-list-heading');
+      await page.keys(['Tab']);
+      await expect(page.isFocused(listbox)).resolves.toBe(true);
+    };
+
+    test(
+      'keeps the highlighted option visible',
+      setupTest(`#/light/option-list/scroll?container=${container}`, async page => {
+        await focusList(page);
+        await page.assertKeyboardScrolling();
+      })
+    );
+
+    test(
+      'focus entry highlights the selected option near the end and scrolls it into view',
+      setupTest(`#/light/option-list/scroll?container=${container}&preselected=near-end`, async page => {
+        await focusList(page);
+        await expect(page.getHighlightedText()).resolves.toBe('Option 81');
+        await page.waitForHighlightVisible();
+      })
+    );
+  });
+
+  describe.each([false, true])('in a Dropdown, expandToViewport=%s', expandToViewport => {
+    test(
+      'keeps the highlighted option visible without scrolling the page on open',
+      setupTest(`#/light/option-list/scroll?container=dropdown&expandToViewport=${expandToViewport}`, async page => {
+        const scrollBefore = await page.getWindowScroll();
+        await page.click('#dropdown-trigger');
+        await page.waitForVisible(listbox);
+        await expect(page.isFocused(listbox)).resolves.toBe(true);
+        await expect(page.getWindowScroll()).resolves.toEqual(scrollBefore);
+        await page.assertKeyboardScrolling();
+      })
+    );
+  });
+});

src/option-list/__integ__/option-list.test.ts

@@ -0,0 +1,60 @@
+// 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';
+
+const wrapper = createWrapper();
+const singleList = wrapper.findOptionList('[data-testid="single"]');
+const multiList = wrapper.findOptionList('[data-testid="multi"]');
+const groupsList = wrapper.findOptionList('[data-testid="groups"]');
+const listbox = (list: typeof singleList) => `${list.toSelector()} [role="listbox"]`;
+
+const setupTest = (testFn: (page: BasePageObject) => Promise<void>) =>
+  useBrowser(async browser => {
+    await browser.url('#/light/option-list/simple');
+    const page = new BasePageObject(browser);
+    await page.waitForVisible(singleList.toSelector());
+    await testFn(page);
+  });
+
+describe('OptionList', () => {
+  test(
+    'selects an option with a click anywhere on the row',
+    setupTest(async page => {
+      await page.click(singleList.findOptionByValue('performance').findDescription().toSelector());
+      await expect(page.getText('[data-testid="single-value"]')).resolves.toBe('Selected: performance');
+      await expect(page.getElementsCount(singleList.findSelectedOptions().toSelector())).resolves.toBe(1);
+    })
+  );
+
+  test(
+    'selects with the keyboard: Tab into the list, arrows move, Enter selects',
+    setupTest(async page => {
+      await page.click('#single-heading');
+      await page.keys(['Tab']);
+      await expect(page.isFocused(listbox(singleList))).resolves.toBe(true);
+      await page.keys(['ArrowDown', 'ArrowDown', 'Enter']);
+      await expect(page.getText('[data-testid="single-value"]')).resolves.toBe('Selected: reliability');
+    })
+  );
+
+  test(
+    'Tab leaves the list after one stop',
+    setupTest(async page => {
+      await page.click('#single-heading');
+      await page.keys(['Tab', 'Tab']);
+      await expect(page.isFocused(listbox(singleList))).resolves.toBe(false);
+      await expect(page.isFocused(listbox(multiList))).resolves.toBe(true);
+    })
+  );
+
+  test(
+    'clicking a group header selects its enabled options',
+    setupTest(async page => {
+      await page.click(groupsList.findGroupHeaderByValue('storage').toSelector());
+      await expect(page.getText('[data-testid="groups-value"]')).resolves.toBe('Selected: s3');
+    })
+  );
+});