Introduction to testing

When creating automated tests for your application you interact with Cloudscape components. For example, you might choose a Cloudscape button and assert that the application updates to reflect the action that you associated to that button.

The inner HTML structure of Cloudscape components, including CSS class names, can change at any time. This is why we created test utilities for each component. Test utilities expose stable APIs so that you can access relevant parts of those components without worrying about the right selector to use.

Cloudscape test utilities are framework-agnostic and can be used with any test stack (from Jest  and jsdom  to WebdriverIO ), as well as the following:

• Unit tests, where you typically have direct access to the Document Object Model (DOM).

• Integration tests, where it is typical to rely on string selectors.

You can find documentation for component-specific test utilities on the Testing tab of each component page (for example: Input test utilities), in addition to documentation on testing core classes that are component-independent.

Test utilities are part of the main components package. If you don’t have components installed, see our installation guide.

To get started:

• Learn more about Cloudscape integration with popular testing frameworks.

• Consult examples on this page for unit and integrations tests.

• Familiarize yourself with our testing core classes.

• Browse component-specific test utilities in each component page (for example: Input test utilities).

• Read our recommendations later on this page.

This section contains example of usage of test utilities for unit tests, where you typically have direct access to the Document Object Model (DOM).

For such tests, use the default wrapper exposed by the '@cloudscape-design/components/test-utils/dom' package.

// import test utils from the package
import createWrapper from '@cloudscape-design/components/test-utils/dom';

// get the DOM element of your application 
const element = document.getElementById('app');

// find a select trigger in your application using test utils
const trigger = createWrapper(element).findSelect().findTrigger();

// open the select by clicking on the trigger
trigger.click();

The createWrapper method returns an instance of ElementWrapper . Use this object to find Cloudscape components on the page and interact with them.

Examples

Finding a component

createWrapper(element).findFlashbar(); // should not be null if the component is on the page

Finding a component inside another component

createWrapper(element).findFormField().findControl().findInput(); // find an input inside a form field

Choosing an element

createWrapper(element).findButton().click(); // choosing a button element

Note: Events only work when an element is mounted within a document ancestor node.

Changing an input value

createWrapper(element).findInput().setInputValue('New value for test'); // editing an input

This section contains usage examples of test utilities for integration tests that don't have direct access to the DOM and typically rather rely on string selectors.

For these tests, use the default wrapper exposed by the '@cloudscape-design/components/test-utils/selectors' package.

// import test utils from the package
import createWrapper from '@cloudscape-design/components/test-utils/selectors';

// use the browser object from your favorite integration testing framework
const browser = getBrowserSomehow();

// generate a CSS-selector to select trigger element
const triggerSelector = createWrapper('#app').findSelect().findTrigger().toSelector();

// use your test framework to make a click on the specified selector
browser.click(triggerSelector)

The wrapper method returns an instance of ElementWrapper. Use this object to find Cloudscape components on the page and interact with them.

Examples

Generate selector for a component

createWrapper('#app').findFlashbar().toSelector(); // selector for the Flashbar component

Generate selector for a specific component among multiple ones

createWrapper('#app').findButton('[data-testid="my-button"]').toSelector(); // selector for Button component that has a specific test id

Generate selector for a nested component

createWrapper('#app').findFormField().findControl().findInput().toSelector(); // selector for Input component inside a Form field component

• Use data-testid attribute to uniquely identify a specific component. Do not rely on CSS class names.

• If you can't use Cloudscape test utilities, consider querying elements using visible text and aria-labels, for example through testing-library   and its ByText   and ByLabelText   methods.