Testing frameworks integration
How to integrate different testing frameworks with Cloudscape components.
On this page
Did this page help you?
Tell us more - optional
Using Vitest
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.
Using Jest
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
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.
Using Mocha
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 .
Configure JSDOM
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.