Testing web apps in JavaScript using WebdriverIO | Applitools Documentation
Quickstart for Visual Testing with WebdriverIO
This quickstart will show you how to visually test web apps in JavaScript using WebdriverIO. Visual testing can help you catch problems that traditional automation struggles to find.
After preparing your environment, this three-step quickstart should take about 15 minutes to complete.
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.
- A good JavaScript editor like Visual Studio Code.
- An up-to-date version of Google Chrome.
Step 2: Getting your example project
Downloading the example project
The example project is located at https://github.com/applitools/example-webdriverio-javascript. Clone this repository to your local machine:
git clone https://github.com/applitools/example-webdriverio-javascript.git
cd example-webdriverio-javascript
Don't have Git?
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 WebdriverIO, you must install project dependencies and ChromeDriver. Run the following commands (which work for both example projects on any operating system):
npm install
npm install chromedriver --detect_chromedriver_version
Adding Applitools to Another WebdriverIO Project?
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 WebdriverIO project, run the following command:
npm install --save-dev @applitools/eyes-webdriverio
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
Walking through the code
The project contains one visual test case, which is located at test/acme-bank.test.js.
acme-bank.test.js is a test module that covers login behavior for the ACME Bank demo web app. It uses the Applitools Eyes SDK for WebdriverIO to execute the test. The variables at the top control how tests will run:
- Set
USE_ULTRAFAST_GRIDtotrueto use Ultrafast Grid orfalseto use the Classic runner. - Set
USE_EXECUTION_CLOUDtotrueto use Execution Cloud orfalseto run WebDriver sessions locally.
Setup varies slightly for these different options. In-line comments explain every section. Read it top to bottom to understand how it works:
'use strict';
const { remote } = require('webdriverio');
const { Eyes,
ClassicRunner,
VisualGridRunner,
RunnerOptions,
Target,
RectangleSize,
Configuration,
BatchInfo,
BrowserType,
ScreenOrientation,
DeviceName } = require('@applitools/eyes-webdriverio');
describe('ACME Bank', function () {
const USE_ULTRAFAST_GRID = true;
const USE_EXECUTION_CLOUD = false;
var applitoolsApiKey;
let batch;
let config;
let runner;
let eyes;
before(async () => {
applitoolsApiKey = process.env.APPLITOOLS_API_KEY;
if (USE_ULTRAFAST_GRID) {
runner = new VisualGridRunner(new RunnerOptions().testConcurrency(5));
}
else {
runner = new ClassicRunner();
}
const runnerName = (USE_ULTRAFAST_GRID) ? 'Ultrafast Grid' : 'Classic runner';
batch = new BatchInfo(`Example: WebdriverIO JavaScript with the ${runnerName}`);
config = new Configuration();
config.setApiKey(applitoolsApiKey);
config.setBatch(batch);
if (USE_ULTRAFAST_GRID) {
config.addBrowser(800, 600, BrowserType.CHROME);
config.addBrowser(1600, 1200, BrowserType.FIREFOX);
config.addBrowser(1024, 768, BrowserType.SAFARI);
config.addDeviceEmulation(DeviceName.Pixel_2, ScreenOrientation.PORTRAIT);
config.addDeviceEmulation(DeviceName.Nexus_10, ScreenOrientation.LANDSCAPE);
}
});
beforeEach(async function () {
eyes = new Eyes(runner);
eyes.setConfiguration(config);
if (USE_EXECUTION_CLOUD) {
const executionCloudUrl = new URL(await Eyes.getExecutionCloudUrl());
const protocol_val = executionCloudUrl.protocol.substring(0, executionCloudUrl.protocol.length - 1);
browser = await remote({
logLevel: 'trace',
protocol: protocol_val,
hostname: executionCloudUrl.hostname,
port: Number(executionCloudUrl.port),
capabilities: {
browserName: 'chrome',
}
});
}
browser = await eyes.open(
browser,
'ACME Bank',
this.currentTest.fullTitle(),
new RectangleSize(1200, 600)
);
});
it('should log into a bank account', async () => {
await browser.url('https://sandbox.applitools.com/bank');
await eyes.check(Target.window().fully().withName("Login page"));
await browser.$("#username").setValue("Chris");
await browser.$("#password").setValue("CorrectHorseBatteryStaple");
await browser.$("#log-in").click();
await eyes.check(Target.window().fully().withName("Main page").layout());
});
afterEach(async () => {
await eyes.closeAsync();
await browser.closeWindow();
});
after(async () => {
const allTestResults = await runner.getAllTestResults();
console.log(allTestResults);
});
});
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
export APPLITOOLS_API_KEY=<your-api-key>
- Windows
set APPLITOOLS_API_KEY=<your-api-key>
Launching visual tests
To launch the tests, run:
npm test
By default, the test will run headlessly. After your tests run, you should see results in the Eyes Test Manager.
Injecting visual bugs
You can also change the web page to inject visual bugs:
// await browser.url('https://demo.applitools.com');
await browser.url('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.
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.