Testing frameworks integration

Our packages do not require any special configuration in this framework.

For the best testing experience, we recommend combining vitest with the react testing library . After installing respective dependencies, create a testing setup file, tests/setup.js, for example:

import { expect, afterEach } from 'vitest';
import { cleanup } from '@testing-library/react';

afterEach(() => {
  cleanup();
});

Update vite.config.js:

export default defineConfig({
  // ... your other configuration ...
  test: {
    environment: "jsdom",
    setupFiles: ["./test/setup.js"],
  },
});

Common errors

If you receive "SyntaxError: Cannot use import statement outside a module" error coming from our packages, it is likely there is a configuration error in an intermediate dependency. Check this vitest issue , and other similar issues , for more guidance.

Preset configuration

We recommend using our configuration preset  for tests involving our components. For example, this preset fixes SyntaxError: Unexpected token 'export', which may occur in your tests.

For integration instructions, see the package readme .

Snapshot testing

By design, our components are not meant to produce stable snapshots. This is because we constantly add new features and improvements. To protect your snapshots from unexpected changes, isolate your tests by mocking the components module.

If you use main import path

// in a file with snapshot tests
jest.mock('@cloudscape-design/components', () => {
  const Components = jest.genMockFromModule('@cloudscape-design/components');
  for (const componentName of Object.keys(Components)) {
    Components[componentName] = componentName;
  }
  return Components;
})

If you use individual component imports

Create a file component-mocks.js:

// This has to be a separate file because Jest does not support for-loops in the mocks:
// https://github.com/facebook/jest/issues/11063
import kebabCase from 'lodash/kebabCase';
const Components = jest.requireActual('@cloudscape-design/components');
for (const mockComponentName of Object.keys(Components)) {
  jest.mock(`@cloudscape-design/components/${kebabCase(mockComponentName).replace('s-3', 's3')}`, () => mockComponentName);
}

Import it in the test file:

// this line must be above the source code import
import './component-mocks';
import YourComponent from './your-code';

Using Enzyme

Enzyme's mount method doesn't attach the content to the document. Due to the way the React event system works , you must attach the content to the document.
If you want to to initiate test events (for example, clicks or input changes), attach elements to the document manually:

import { mount } from 'enzyme';
import createWrapper from '@cloudscape-design/components/test-utils/dom';

let rendered = [];
function mountToDocument(node) {
  const container = document.createElement('div');
  document.body.appendChild(container);
  const enzymeWrapper = mount(node, { attachTo: container });
  rendered.push(enzymeWrapper);
  return container;
}

// clean up the DOM after each test
afterEach(() => {
  for (const enzymeWrapper of rendered) {
    enzymeWrapper.detach();
  }
  rendered = [];
});

test('usage example', () => {
  const container = mountToDocument(<YourComponent />);
  const wrapper = createWrapper(container);
  wrapper.findButton().click(); // this works
})

As an alternative, you may consider using react-testing-library , which does not require such additional setup.

Configure require hooks

Our components are only provided in ES-module format, which requires some preliminary setup. Create a setup.js file and load it to Mocha using the --require option :

require('ignore-styles');
require('@babel/register')({
  only: [/node_modules\/@cloudscape-design\//],
  ignore: [/test-utils/],
  plugins: [require.resolve('@babel/plugin-transform-modules-commonjs')],
  sourceMap: 'inline',
});

The modules used in this file may not be installed in your project. Install them if needed.

Configure JSDOM

Mocha does not provide a simulated DOM environment. However, you can get it using global-jsdom  module. Add this line to your setup file:

require('global-jsdom')(undefined, { pretendToBeVisual: true });

pretendToBeVisual flag is needed to enable a shim for requestAnimationFrame, which is a requirement for React .

Mocha doesn’t provide you a simulated DOM environment. However, you can get it by using the global-jsdom module. Add this line to your setup file:

require('global-jsdom')(undefined, { pretendToBeVisual: true });

The pretendToBeVisual flag is needed to enable a shim for requestAnimationFrame, which is a requirement for React.