After preparing your environment, this three-step quickstart should take about 15 minutes to complete.
If you get stuck on this example, don't suffer in silence! Please reach out to us to get things working. We can also help you get Applitools running in your own project.
Step 1: Preparing your environment
You'll need a few things to run this quickstart:
An Applitools account, which you can register for free.
A recent version of Node.js.
An up-to-date version of Google Chrome.
A corresponding version of ChromeDriver.Installing ChromeDriver
The major version numbers of Chrome and ChromeDriver must be the same. Otherwise, Selenium WebDriver may raise an exception when it is initialized. For example, Chrome v101 requires ChromeDriver v101.
ChromeDriver must be installed into a directory covered by the system
PATHvariable. Follow the instructions on Selenium's Install browser drivers page. On macOS and Linux, the recommended location for the
chromedriverexecutable is the
You can test that ChromeDriver is working by running the
chromedriver -vcommand to print its version.
Step 2: Getting your example project
Downloading the example project
Instead of running
git clone, you can download the project as a ZIP file and extract it.
Installing the dependencies
The example project uses npm for package management. Run the following commands to install the dependencies, which work for both example projects on any operating system:
This example project already has the Applitools Eyes SDK as a dependency. If you want to add the Applitools Eyes SDK as a new dependency to another project, run the following command:
npm install --save-dev @applitools/eyes-selenium
Deciding how to run tests
The test uses Selenium WebDriver to automate the browser. There are two places to run your Selenium WebDriver session:
- On your local machine (which is the default option)
- On Applitools Execution Cloud
If you run WebDriver locally, then you need to set it up and manage it yourself. If you use Execution Cloud, then Applitools will manage WebDriver for you. It will also automatically heal broken locators and wait for elements to be ready. If you would like to try Execution Cloud, please request access. The docs for Execution Cloud provide more information.
There are two ways to test the visual snapshots captured by the test:
- Using Applitools Ultrafast Grid for cross-browser testing in the cloud
- Using Applitools Classic runner on your local machine
If you are not sure which one to pick, read Leveraging the Applitools platform. For most cases, we recommend Applitools Ultrafast Grid. The docs for Ultrafast Grid and Classic runner provide more information.
Walking through the code
The project contains one visual test case,
which is located at
acme-bank.test.js is a Mocha test file that covers login behavior for the ACME Bank demo web app.
It uses the Applitools Eyes SDK to execute the test.
The variables at the top control how tests will run:
trueto use Ultrafast Grid or
falseto use the Classic runner.
trueto use Execution Cloud or
falseto run WebDriver sessions locally.
Setup varies slightly for these different options. In-line comments explain every section of its code. Read it top to bottom to understand how it works:
Step 3: Running your tests
Setting Applitools variables
Before running the visual test,
you must find your Applitools API key
and set it as an environment variable named
You may set it through your IDE (if applicable),
or you may set it from the command line like this:
- macOS and Linux
If you have trouble setting the
APPLITOOLS_API_KEY environment variable, you can hard-code your API key like this:
// Change the following line:
// applitoolsApiKey = process.env.APPLITOOLS_API_KEY;
applitoolsApiKey = "<your-api-key>";
However, be warned: hard-coding secrets is poor practice. Do this only temporarily for debugging, and never commit hard-coded secrets to version control.
You may also need to set your Applitools Eyes server.
By default, tests will use the public Applitools Eyes server at eyes.applitools.com.
However, if your team is using a private Applitools Eyes server,
you can target it by setting the
APPLITOOLS_SERVER_URL environment variable.
(If you are using a free Applitools account, then use the public server.)
Launching visual tests
To launch the tests, run:
To run tests using headless Chrome, set the
HEADLESS environment variable to
When you run tests with the Applitools Ultrafast Grid, the tests will run one time on the local machine, and then they will upload snapshots to render on each target configuration in the cloud. The Test Manager will show a separate result for each rendering. When you run tests with the Applitools Classic runner, the Test Manager will show the one snapshot from your local machine.
You can also change the web page to inject visual bugs:
// await driver.get("https://demo.applitools.com");
If you rerun the tests, then they should yield "unresolved" results for you to review. Visual differences will be highlighted in magenta. It's up to you to accept (👍) or reject (👎) the changes. Applitools will remember your decisions for future analysis.
Again, it's okay. If you get stuck on this example, don't suffer in silence! Please reach out to us to get things working. We can also help you get Applitools running in your own project.
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:
- 🤖 Learning how visual testing works
- ↔️ Setting match levels for visual checkpoints
- 💥 Troubleshooting common issues
- 🐞 Reporting bugs
- 🗺 Detailed overview of visual testing with Applitools