- Testing: Introduction to testing
Introduction to testing
You can test your application by interacting with Cloudscape components.
Overview
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.
Getting started
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.
Unit testing
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
Integration testing
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
Additional recommendations
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.