Cloudscape Design System
  • Get started
  • Foundation
  • Components
  • Patterns
  • Demos
  • GitHub 
Cloudscape Design System
  • Get started
  • Foundation
  • Components
  • Patterns
  • Demos
  • GitHub 
  • About
  • Guides
    • Introduction
    • Get started for designers
    • Get started for developers
  • Resources
    • Design resources
  • Integration
    • Using Cloudscape components
    • Global styles
  • Development guides
    • Collection hooks package
    • Content security policy (CSP)
    • Responsive development
    • State management
    • Z-index
  • Testing
    • Introduction to testing
    • Testing frameworks integration
    • Testing core classes
  1. Cloudscape Design System
    • Get started
    • Testing: Introduction to testing

    Introduction to testing

    You can test your application by interacting with Cloudscape components.

      On this page

      • Overview
      • Getting started
      • Unit testing
      • Integration testing
      • Additional recommendations

      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.

      • About
      • Connect
      • Privacy 
      • Site terms 
      • © 2023, Amazon Web Services, Inc. or its affiliates. All rights reserved.
      Made with love atAWS