Testing web apps in JavaScript using Cypress
This quickstart will show you how to visually test web apps in JavaScript using Cypress. Visual testing can help you catch problems that traditional automation struggles to find. You can also leverage Applitools Ultrafast Grid to run your tests across all the major browsers in a fraction of the time as other cross-browser testing platforms.
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.
The Applitools Eyes SDK for Cypress supports only Applitools Ultrafast Grid. It does not support the Classic runner.
Step 1: Preparing your environment
You'll need a few things to run this quickstart:
An Applitools account, which you can register for free.
Node.js version 16 or higher.
A good JavaScript editor like Visual Studio Code.
Up-to-date versions of at least one of the following browsers:
Step 2: Getting your example project
Downloading the example project
The example project is located at https://github.com/applitools/example-cypress-javascript. Clone this repository to your local machine:
git clone https://github.com/applitools/example-cypress-javascript.git
cd example-cypress-javascript
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. For Cypress, you must install project dependencies and set up Applitools Eyes. Run the following command (which works on any operating system):
npm install
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 Cypress project, run the following commands:
npm install @applitools/eyes-cypress
npx eyes-setup
Walking through the code
The project contains one visual test case,
which is located at cypress/e2e/acme-bank.cy.js
.
acme-bank.cy.js
is a Cypress test module that covers login behavior for the ACME Bank demo web app.
It uses the Applitools Eyes SDK for Cypress
to capture visual checkpoints.
The code is rather concise.
In-line comments explain every section.
Read it top to bottom to understand how it works:
The applitools.config.js
file in the project root directory
provides the configuration to run this visual test across multiple browsers in the Ultrafast Grid.
With the Ultrafast Grid, you can specify different browser types, viewport sizes, and even mobile devices.
Its configuration applies to all test cases in the project:
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 APPLITOOLS_API_KEY
.
You may set it through your IDE (if applicable),
or you may set it from the command line like this:
- macOS and Linux
- Windows
export APPLITOOLS_API_KEY=<your-api-key>
set APPLITOOLS_API_KEY=<your-api-key>
If you have trouble setting the APPLITOOLS_API_KEY
environment variable, you can hard-code your API key like this:
// Override this setting in applitools.config.js:
apiKey: '<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 open the Cypress window for launching tests, run:
npx cypress open
If you want to run tests directly from the command line, run this instead:
npx cypress run
After your tests run, you should see results in the Eyes Test Manager. You can log into the Test Manager at eyes.applitools.com or at the address for your private Applitools Eyes server.
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.
You can also change the web page to inject visual bugs:
// cy.visit('https://demo.applitools.com')
cy.visit('https://demo.applitools.com/index_v2.html')
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