Overview

Pleasantest

Frustration-free automated UI testing in a real browser, with a familiar and intuitive syntax

Get Started GitHub
Pleasantest test code, showing code to launch a browser, find and click a button, and check that a heading becomes visible.
ts
test(
  'Toggle Hikes List',
  withBrowser(async ({ screen, user }) => {
    // Find the hikes button
    const hikesButton = await screen.getByRole(
      'button',
      { name: 'View Hikes' }
    );
    // Click it
    await user.click(hikesButton);
    // Confirm the hikes heading is visible
    await expect(
      await screen.getByRole('heading', {
        name: 'Hikes Near You',
      })
    ).toBeVisible();
  })
);
Highlights

Test Real Use Cases in Real Browsers

Increase confidence in your code by writing tests that mimic real user behavior and running them in a real browser. When things go wrong, debug your tests using browser developer tools.

Graphic showing a failing test pointing to a missing element in the browser

Build Inclusive UIs with Accessibility Testing Features

One-of-a-kind tools like Accessibility Tree Snapshots as well as features built into Jest and Testing Library make it easier to understand, improve, and maintain the accessibility of your interfaces.

Graphic showing an accessibility tree in code next to a browser, with lines between browser elements and their corresponding accessibility tree nodes

Get Up to Speed Quickly With Familiar Tools

Pleasantest super-charges tools like Jest and Testing Library that you may already be familiar with, while avoiding the drawbacks of simulated browsers.

Graphic showing a code snippet, pointing out which lines of code come from Jest, Puppeteer, Jest-dom, and Testing Library

Getting Started

Follow these six quick steps to get up and running with Pleasantest. For more information, check out the documentation on GitHub.

  1. Install Jest and Pleasantest

    Pleasantest integrates with Jest tests. If you haven't set up Jest yet, here is Jest's getting started guide.

    You’ll need to install Jest and Pleasantest:

    npm i -D jest pleasantest

  2. Write Your First Test

    Now you’re ready to write your first test! Wrapping your test callback with withBrowser allows you to hook into a real browser with Pleasantest:

    ts
    // If you want to use module imports you’ll need to configure
    // Jest and Babel to use ESM
    // See https://jestjs.io/docs/getting-started#using-babel
    const { withBrowser } = require('pleasantest');
    test(
      'test name',
      withBrowser(async ({ utils, screen, user }) => {
        // Your test code here
      }),
    );

  3. Add UI Markup to Your Test

    Once you’ve created a test there are three ways to insert markup:

    ts
    // For JS frameworks you can run arbitrary JavaScript
    // (./app could be a .js, .jsx .ts, or .tsx file)
    await utils.runJS(`
      import { App } from './app'
      import { render } from 'react-dom'
      render(<App/>, document.body)
    `);
    // You can also insert HTML
    // (This works well with templating languages)
    await utils.injectHTML('<h1>Find Hikes</h1>');
    // Tests can also be run by navigating to URLs within your app:
    await page.goto('http://localhost:3000/hikes');

  4. Interact With Your App In a Real Browser

    Pleasantest comes prepackaged with helpful utilities to find and interact with elements like a real user:

    ts
    const locationInput = await screen.getByRole('textbox', {
      name: 'Pick a Location'
    });
    const submitButton = await screen.getByRole('button', {
      name: 'Find Hikes'
    });
    await user.type(locationInput, 'Portland, Oregon');
    await user.click(submitButton);

  5. Make Assertions Against the DOM

    Use jest-dom’s intuitive syntax to confirm your interface responds correctly to user actions:

    ts
    await expect(submitButton).toHaveFocus();
    await expect(hikeResults).toBeVisible();

  6. Run Your Tests

    Now you can use the Jest CLI commands to run your tests. The testTimeout flag tells Jest to allow the test to run for up to 10 seconds, which is necessary for the first time Pleasantest starts the browser.

    npx jest --testTimeout=10000