Setup @elastic/eui-test-helpers

packages/test-helpers/.gitignore

@@ -0,0 +1,37 @@
+# node_modules directory at any level deep
+node_modules
+
+# Global log files
+npm-debug.log
+
+# IDE-specific files
+.idea
+.vscode
+
+# OS-specific files
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+*.stackdump
+[Dd]esktop.ini
+.DS_Store
+
+# Logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# Yarn
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+yarn-error.log
+
+es/
+lib/

packages/test-helpers/LICENSE.txt

@@ -0,0 +1,6 @@
+Source code in this repository is covered by (i) a dual license under the Server
+Side Public License, v 1 and the Elastic License 2.0 or (ii) an Apache License
+2.0 compatible license or (iii) solely under the Elastic License 2.0, in each
+case, as noted in the applicable header. The default throughout the repository
+is a dual license under the Server Side Public License, v 1 and the Elastic
+License 2.0, unless the header specifies another license.

packages/test-helpers/README.md

@@ -0,0 +1,28 @@
+# EUI Test Helpers
+
+`@elastic/eui-test-helpers` is a library of EUI components test helpers for [Cypress](https://github.com/cypress-io/cypress) 
+and [React Testing Library](https://github.com/testing-library/react-testing-library).
+It provides assertion, find, and query functions to make testing EUI components easier and more reliable by exposing
+a stable API eliminating guesswork. Say goodbye to finding CSS selectors that _seem_ right.
+
+> [!NOTE]
+> This library is in early stages of development and is missing many useful utilities. Please contribute or 
+> [open a feature request](https://github.com/elastic/eui/issues/new?template=feature_request.md) if you notice 
+> anything missing!
+
+This library provides utilities to EUI components that are non-trivial to write tests for, usually because of going
+beyond what the native experience looks like, making it more complicated for test frameworks
+to have built-in utilities for. A good example is `EuiComboBox` which resembles the native `<select>` but ships with
+additional features like search, multi-option selection, and a custom UI.
+
+You should keep using the ways of testing UI recommended by your testing framework whenever possible, and reach out for
+`@elastic/eui-test-helpers` only when testing selected EUI components this library was made to help with.
+This approach ensures you go the most maintenance-free path possible.
+
+## Installation
+
+This library's versioning is following `@elastic/eui` and must be kept in sync to ensure correct functionality.
+
+```shell
+yarn add --dev @elastic/eui-test-helpers
+```

packages/test-helpers/babel.config.js

@@ -0,0 +1,7 @@
+module.exports = {
+  presets: [
+    ['@babel/preset-env', { targets: { node: 'current' }}],
+    '@babel/preset-typescript',
+    ['@babel/preset-react', { runtime: 'automatic' }],
+  ],
+};

packages/test-helpers/jest.config.ts

@@ -0,0 +1,24 @@
+/**
+ * For a detailed explanation regarding each configuration property, visit:
+ * https://jestjs.io/docs/configuration
+ */
+
+import type {Config} from 'jest';
+
+const config: Config = {
+  coverageProvider: "v8",
+  testEnvironment: "jsdom",
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'json'],
+  testMatch: ['**/*.test.js', '**/*.test.ts', '**/*.test.tsx'],
+  transform: {
+    '^.+\\.(js|tsx?)$': 'babel-jest',
+  },
+  moduleNameMapper: {
+    'uuid': require.resolve('uuid'),
+  },
+  setupFilesAfterEnv: [
+    '<rootDir>/test/setup.ts',
+  ],
+};
+
+export default config;

packages/test-helpers/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@elastic/eui-test-helpers",
+  "version": "99.1.0",
+  "description": "A library of EUI components test helpers for Cypress and react-testing-library",
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "main": "lib/index.js",
+  "module": "es/index.js",
+  "scripts": {
+    "test": "jest src",
+    "build:esm": "tsc --project tsconfig.esm.json",
+    "build:cjs": "tsc --project tsconfig.cjs.json",
+    "build": "concurrently \"yarn run build:esm\" \"yarn run build:cjs\"",
+    "clean": "rimraf es lib"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/elastic/eui.git",
+    "directory": "packages/test-helpers"
+  },
+  "files": [
+    "lib",
+    "es",
+    "licenses"
+  ],
+  "dependencies": {
+    "typescript": "^5.7.3"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.26.7",
+    "@babel/preset-env": "^7.26.7",
+    "@babel/preset-react": "^7.26.3",
+    "@babel/preset-typescript": "^7.26.0",
+    "@elastic/eui": "99.0.0",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.2.0",
+    "@types/babel__core": "^7",
+    "@types/babel__preset-env": "^7",
+    "@types/jest": "^29.5.14",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "babel-jest": "^29.7.0",
+    "canvas": "^3.1.0",
+    "concurrently": "^9.1.2",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "rimraf": "^6.0.1"
+  },
+  "peerDependencies": {
+    "@elastic/eui": "workspace:^",
+    "@testing-library/dom": "*",
+    "@testing-library/react": "*"
+  }
+}

packages/test-helpers/src/components/combo_box/rtl.test.tsx

@@ -0,0 +1,63 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import React from 'react';
+import { fireEvent, render as rtlRender } from '@testing-library/react';
+import { EuiComboBox } from '@elastic/eui';
+import { testHelpersScreen } from '../../utils/rtl/internal';
+import { withEuiProvider } from '../../utils/rtl';
+import { EuiComboBoxTestHelpers } from './rtl';
+import { EuiComboBoxSelectors } from './selectors';
+
+const render = withEuiProvider(rtlRender);
+
+describe('EuiComboBoxTestHelpers', () => {
+  const options = [
+    { label: 'Lorem' },
+    { label: 'ipsum' },
+    { label: 'dolor' },
+    { label: 'sit' },
+    { label: 'amet' },
+  ];
+
+  beforeEach(() => {
+    render(<EuiComboBox options={options} />);
+  });
+
+  it('is sane', () => {
+    expect(testHelpersScreen.getByTestSubject(EuiComboBoxSelectors.TEST_SUBJ)).toBeInTheDocument();
+  });
+
+  it('isOptionsListOpen()', async () => {
+    await expect(EuiComboBoxTestHelpers.isOptionsListOpen()).resolves.toBe(false);
+
+    fireEvent.click(testHelpersScreen.getByTestSubject(EuiComboBoxSelectors.OPTIONS_LIST_TOGGLE_BUTTON_TEST_SUBJ));
+    await expect(EuiComboBoxTestHelpers.isOptionsListOpen()).resolves.toBe(true);
+
+    fireEvent.click(testHelpersScreen.getByTestSubject(EuiComboBoxSelectors.OPTIONS_LIST_TOGGLE_BUTTON_TEST_SUBJ));
+    await expect(EuiComboBoxTestHelpers.isOptionsListOpen()).resolves.toBe(false);
+  });
+
+  it('openOptionsList()', async () => {
+    await expect(EuiComboBoxTestHelpers.isOptionsListOpen()).resolves.toBe(false);
+
+    await EuiComboBoxTestHelpers.openOptionsList();
+    await expect(EuiComboBoxTestHelpers.isOptionsListOpen()).resolves.toBe(true);
+
+    await EuiComboBoxTestHelpers.openOptionsList();
+    await expect(EuiComboBoxTestHelpers.isOptionsListOpen()).resolves.toBe(true);
+  });
+
+  it('closeOptionsList()', async () => {
+    await EuiComboBoxTestHelpers.openOptionsList();
+    await expect(EuiComboBoxTestHelpers.isOptionsListOpen()).resolves.toBe(true);
+
+    await EuiComboBoxTestHelpers.closeOptionsList();
+    await expect(EuiComboBoxTestHelpers.isOptionsListOpen()).resolves.toBe(false);
+  });
+});

packages/test-helpers/src/components/combo_box/rtl.ts

@@ -0,0 +1,110 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { fireEvent, waitFor } from '@testing-library/react';
+import { getAriaControlsElement, getTargetContainer, WaitForOptions } from '../../utils/rtl/internal';
+import { EuiPopoverTestHelpers } from '../popover/rtl';
+import { EuiComboBoxSelectors } from './selectors';
+
+/**
+ * Find outer <EuiComboBox> element or throw when it doesn't exist
+ */
+const findElement = async (
+  container?: HTMLElement,
+  options?: WaitForOptions,
+) => {
+  const target = getTargetContainer(container);
+
+  try {
+    return await target.findByTestSubject(
+      EuiComboBoxSelectors.TEST_SUBJ,
+      undefined,
+      options,
+    );
+  } catch (err) {
+    throw new Error(
+      `Unable to find <EuiComboBox> within given container. Make sure ` +
+      `it's rendered on the screen when calling this function ` +
+      `or increase the timeout if you're waiting for an asynchronous action`
+    );
+  }
+};
+
+const getInput = async (container?: HTMLElement) => {
+  const target = getTargetContainer(container);
+
+  return target.getByTestSubject(EuiComboBoxSelectors.SEARCH_INPUT_TEST_SUBJ);
+};
+
+/**
+ * Whether the options list is currently open (visible)
+ */
+const isOptionsListOpen = async (container?: HTMLElement) => {
+  // Find the outer element
+  const wrappingElement = await findElement(container);
+  // Get EuiComboBox <input> element and read its aria-controls to find the exact listbox element
+  const inputElement = await getInput(wrappingElement);
+
+  return !!getAriaControlsElement(inputElement);
+};
+
+/**
+ * Opens EuiComboBox options list
+ */
+const openOptionsList = async (container?: HTMLElement) => {
+  // Ignore if options list is already open
+  if (await isOptionsListOpen(container)) {
+    return;
+  }
+
+  const target = getTargetContainer(container);
+
+  fireEvent.click(
+    target.getByTestSubject(
+      EuiComboBoxSelectors.OPTIONS_LIST_TOGGLE_BUTTON_TEST_SUBJ
+    )
+  );
+
+  await EuiPopoverTestHelpers.waitForOpen();
+
+  await waitFor(() => {
+    expect(
+      target.queryByTestSubject(EuiComboBoxSelectors.OPTIONS_LIST_TEST_SUBJ)
+    ).toBeInTheDocument();
+  });
+};
+
+/**
+ * Closes EuiComboBox options list
+ */
+const closeOptionsList = async (container?: HTMLElement) => {
+  // Ignore if options list is already closed
+  if (!(await isOptionsListOpen(container))) {
+    return;
+  }
+
+  const target = getTargetContainer(container);
+
+  fireEvent.click(
+    target.getByTestSubject(
+      EuiComboBoxSelectors.OPTIONS_LIST_TOGGLE_BUTTON_TEST_SUBJ
+    )
+  );
+
+  await waitFor(() => {
+    expect(
+      target.queryByTestSubject(EuiComboBoxSelectors.OPTIONS_LIST_TEST_SUBJ)
+    ).not.toBeInTheDocument();
+  });
+};
+
+export const EuiComboBoxTestHelpers = {
+  isOptionsListOpen,
+  openOptionsList,
+  closeOptionsList,
+};

packages/test-helpers/src/components/combo_box/selectors.ts

@@ -0,0 +1,53 @@
+/**
+ * List of available stable selectors for
+ * {@link https://eui.elastic.co/#/forms/combo-box|EuiComboBox}
+ */
+export const EuiComboBoxSelectors = {
+  /**
+   * `data-test-subj` identifier of the outer (main) element
+   */
+  TEST_SUBJ: 'comboBoxInput',
+
+  /**
+   * `data-test-subj` identifier of the search input field
+   */
+  SEARCH_INPUT_TEST_SUBJ: 'comboBoxSearchInput',
+
+  /**
+   * `data-test-subj` identifier of the options list
+   */
+  OPTIONS_LIST_TEST_SUBJ: 'comboBoxOptionsList',
+
+  /**
+   * `data-test-subj` identifier of the options list toggle button
+   */
+  OPTIONS_LIST_TOGGLE_BUTTON_TEST_SUBJ: 'comboBoxToggleListButton',
+
+  /**
+   * `data-test-subj` identifier of the clear button
+   */
+  CLEAR_BUTTON_TEST_SUBJ: 'comboBoxClearButton',
+
+  /**
+   * `data-test-subj` identifier of all selected options (pills)
+   */
+  SELECTED_OPTIONS_TEST_SUBJ: 'euiComboBoxPill',
+
+  /**
+   * CSS selector to find all options (currently rendered on the screen).
+   *
+   * Note: Because the list of options might be virtualized, when searching
+   * for a specific option, type in the searched string into the search input
+   * before running any assertions to ensure the option is in DOM.
+   */
+  OPTION: '[data-test-subj="comboBoxOptionsList"] button[role="option"]',
+
+  /**
+   * CSS selector to find all selected options (currently rendered on the screen)
+   *
+   * Note: Because the list of options might be virtualized, when searching
+   * for a specific option, type in the searched string into the search input
+   * before running any assertions to ensure the option is in DOM.
+   */
+  SELECTED_OPTION: '[data-test-subj="comboBoxOptionsList"] button[role="option"][aria-selected="true"]',
+};