Skip to main content

Migrating from Testing Library

Migration principles​

This guide describes migration to copilotbrowser's Experimental Component Testing from DOM Testing Library, React Testing Library, Vue Testing Library and Svelte Testing Library.

note

If you use DOM Testing Library in the browser (for example, you bundle end-to-end tests with webpack), you can switch directly to copilotbrowser Test. Examples below are focused on component tests, but for end-to-end test you just need to replace await mount with await page.goto('http://localhost:3000/') to open the page under test.

Cheat Sheet​

Testing Librarycopilotbrowser
screenpage and component
querieslocators
async helpersassertions
user eventsactions
await user.click(screen.getByText('Click me'))await component.getByText('Click me').click()
await user.click(await screen.findByText('Click me'))await component.getByText('Click me').click()
await user.type(screen.getByLabelText('Password'), 'secret')await component.getByLabel('Password').fill('secret')
expect(screen.getByLabelText('Password')).toHaveValue('secret')await expect(component.getByLabel('Password')).toHaveValue('secret')
screen.getByRole('button', { pressed: true })component.getByRole('button', { pressed: true })
screen.getByLabelText('...')component.getByLabel('...')
screen.queryByPlaceholderText('...')component.getByPlaceholder('...')
screen.findByText('...')component.getByText('...')
screen.getByTestId('...')component.getByTestId('...')
render(<Component />);mount(<Component />);
const { unmount } = render(<Component />);const { unmount } = await mount(<Component />);
const { rerender } = render(<Component />);const { update } = await mount(<Component />);

Example​

Testing Library:

import React from 'react';
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';

test('sign in', async () => {
  // Setup the page.
  const user = userEvent.setup();
  render(<SignInPage />);

  // Perform actions.
  await user.type(screen.getByLabelText('Username'), 'John');
  await user.type(screen.getByLabelText('Password'), 'secret');
  await user.click(screen.getByRole('button', { name: 'Sign in' }));

  // Verify signed in state by waiting until "Welcome" message appears.
  expect(await screen.findByText('Welcome, John')).toBeInTheDocument();
});

Line-by-line migration to copilotbrowser Test:

const { test, expect } = require('@copilotbrowser/experimental-ct-react'); // 1

test('sign in', async ({ mount }) => { // 2
  // Setup the page.
  const component = await mount(<SignInPage />); // 3

  // Perform actions.
  await component.getByLabel('Username').fill('John'); // 4
  await component.getByLabel('Password').fill('secret');
  await component.getByRole('button', { name: 'Sign in' }).click();

  // Verify signed in state by waiting until "Welcome" message appears.
  await expect(component.getByText('Welcome, John')).toBeVisible(); // 5
});

Migration highlights (see inline comments in the copilotbrowser Test code snippet):

  1. Import everything from @copilotbrowser/experimental-ct-react (or -vue, -svelte) for component tests, or from @copilotbrowser/copilotbrowser/test for end-to-end tests.
  2. Test function is given a page that is isolated from other tests, and mount that renders a component in this page. These are two of the useful fixtures in copilotbrowser Test.
  3. Replace render with mount that returns a component locator.
  4. Use locators created with Locator.locator() or Page.locator() to perform most of the actions.
  5. Use assertions to verify the state.

Migrating queries​

All queries like getBy..., findBy..., queryBy... and their multi-element counterparts are replaced with component.getBy... locators. Locators always auto-wait and retry when needed, so you don't have to worry about choosing the right method. When you want to do a list operation, e.g. assert a list of texts, copilotbrowser automatically performs multi-element operations.

Replacing waitFor​

copilotbrowser includes assertions that automatically wait for the condition, so you don't usually need an explicit waitFor/waitForElementToBeRemoved call.

// Testing Library
await waitFor(() => {
  expect(getByText('the lion king')).toBeInTheDocument();
});
await waitForElementToBeRemoved(() => queryByText('the mummy'));

// copilotbrowser
await expect(page.getByText('the lion king')).toBeVisible();
await expect(page.getByText('the mummy')).toBeHidden();

When you cannot find a suitable assertion, use expect.poll instead.

await expect.poll(async () => {
  const response = await page.request.get('https://api.example.com');
  return response.status();
}).toBe(200);

Replacing within​

You can create a locator inside another locator with Locator.locator() method.

// Testing Library
const messages = screen.getByTestId('messages');
const helloMessage = within(messages).getByText('hello');

// copilotbrowser
const messages = component.getByTestId('messages');
const helloMessage = messages.getByText('hello');

copilotbrowser Test Super Powers​

Once you're on copilotbrowser Test, you get a lot!

  • Full zero-configuration TypeScript support
  • Run tests across all web engines (Chrome, Firefox, Safari) on any popular operating system (Windows, macOS, Ubuntu)
  • Full support for multiple origins, (i)frames, tabs and contexts
  • Run tests in isolation in parallel across multiple browsers
  • Built-in test artifact collection

You also get all these ✨ awesome tools ✨ that come bundled with copilotbrowser Test:

Further Reading​

Learn more about copilotbrowser Test runner: