Skip to main content

Testing web apps using Puppeteer

Getting Started with Applitools Eyes & Puppeteer

Adding Applitools Eyes to a Puppeteer test

  1. Install Applitools Eyes for Puppeteer

In order to use Applitools Eyes, we need to first install the Eyes SDK for Puppeteer as an npm package.

npm i -D @applitools/eyes-puppeteer
  1. Add a new visual test with Applitools Eyes

To run a new check with Applitools Eyes, you can add the following to a test.

First import the Eyes SDK dependencies:

const { Eyes, ClassicRunner, Target } = require('@applitools/eyes-puppeteer')

Next create a new runner and Eyes instance to set up the test:

const runner = new ClassicRunner();
const eyes = new Eyes();

Then add a new check with Eyes:

await, 'Hello World!', 'My first JavaScript test!', { width: 800, height: 600 });
await eyes.check(Target.window().fully());
await eyes.close();

At it's simplest, this will tell Eyes that you want to start a test, capture the active window, and finally close the test.

You can also create multiple checks that make sense in a typical user flow. If you have a login page where you want to be sure your authentication is working exactly as expected, you may write a test like:

await, 'Hello World!', 'My first JavaScript test!', { width: 800, height: 600 });
await eyes.check('Login Page', Target.window().fully());
await eyes.check('Dashboard', Target.window().fully());
await eyes.close();
  1. Set your Applitools API key

Before running your test, you need to make your API key available to the environment. You can do this by either prepending your test command or exporting it in your terminal session.

To prepend, run a command like npm test as:

APPLITOOLS_API_KEY="[Your Key]" npm test

To export your API key on a Mac, run:

export APPLITOOLS_API_KEY="[Your Key]"

To export your API key on Windows, run:

Unsure how to find your API key?

Read Retrieving your API key to find your API key.

  1. Run your Puppeteer tests!

Now you're ready to run your tests!

You can use your existing test command to run your Puppeteer tests.

And that's it! Your tests should now be available to review in the Applitools dashboard.

Running tests with the Applitools Ultrafast Grid

The Ultrafast Grid gives you the power to run tests on a variety of browsers all from a single test!

To do this, the core difference will start from the runner that we use to configure our Eyes instance.

  1. Update the imported dependencies

First we need to update our dependencies to import the VisualGridRunner along with other modules that will be used to configure out browsers.

const { Eyes, VisualGridRunner, Target, BrowserType, DeviceName } = require('@applitools/eyes-puppeteer');
  1. Replace the runner with the VisualGridRunner

In the previous steps, we used the ClassicRunner to run our tests. For the Ultrafast Grid, we need to use the VisualGridRunner.

Replace the runner with the following:

const runner = new VisualGridRunner({ testConcurrency: 5 });
  1. Add browser configurations

The last step needed is to add any browser configurations to ensure we're running our tests on multiple devices.

Add the following before running

const configuration = eyes.getConfiguration();

configuration.addBrowser({ width: 1200, height: 800, name: BrowserType.CHROME });
configuration.addBrowser({ width: 1200, height: 800, name: BrowserType.FIREFOX });
configuration.addBrowser({ width: 1200, height: 800, name: BrowserType.SAFARI });
configuration.addBrowser({ width: 1200, height: 800, name: BrowserType.EDGE_CHROMIUM });
configuration.addBrowser({ width: 1200, height: 800, name: BrowserType.IE_11 });
configuration.addBrowser({ deviceName: DeviceName.Pixel_2 });
configuration.addBrowser({ deviceName: DeviceName.iPhone_X });

  1. Run your Puppeteer tests!

You can use the same command to run your tests as you did before, just remember to set your API key.

Puppeteer Applitools Eyes SDK

Check out a working demo

See it in action with our example over on GitHub!

More information

The @applitools/eyes-puppeteer npm package page contain more information about advanced configuration, best practices and troubleshooting. Visit eyes-puppeteer SDK repo to find out more about what's possible with Applitools' Puppeteer SDK.

Having Trouble?

Don't suffer in silence! Let us help you. Please reach out to us to get your project working.

Taking the next steps with Applitools

Congratulations on completing this quickstart! There's still so much to learn about visual testing with Applitools, but you're off to a great start.

Resources for next steps:

  1. 🤖 Learning how visual testing works
  2. ↔️ Setting match levels for visual checkpoints
  3. 💥 Troubleshooting common issues
  4. 🐞 Reporting bugs
  5. 🗺 Detailed overview of visual testing with Applitools

You can also: