# Selenium JavaScript Tutorial

Welcome! Applitools is a thin layer on top of Selenium that provides advanced A.I. capabilities to simplify your tests. This tutorial has a "Quick start" and a detailed "Step-by-Step guide" to help you get started with Applitools.

# Quick start 🚀

The following 5 minutes video shows how to quickly get started with Applitools and also some of the features of Applitools that help you significantly impact your automation efforts.

# 1. Install the eyes.selenium SDK

npm install eyes.selenium --save-dev

# 2. Import the SDK

//import the "eyes" SDK
var SeleniumSDK = require("eyes.selenium");
var Eyes = SeleniumSDK.Eyes;

# 3. Initialize the SDK and set API key

// Initialize the eyes SDK and set your private API key.
var eyes = new Eyes();
​
//⚠️️️Set the APPLITOOLS_API_KEY environment variable
eyes.setApiKey("APPLITOOLS_API_KEY");
​
//scroll the entire page (optional)
eyes.setForceFullPageScreenshot(true);

# 4. Set the application (AUT) name, the test name and set browser's viewport size

  eyes.open(driver, "Test app", "First test", { width: 600, height: 800});

# 5. Generate screenshot.

This line uploads the image data to Applitools for the AI to compare differences, generate baseline and so on.

// Visual checkpoint #1.
eyes.checkWindow("Login Window test");

# 6. End the test, Close the browser and abort if necessary

// End the test
  eyes.close();

  // Close the browser.
  driver.quit();

  // If the test was aborted before eyes.close was called ends the test as aborted.
  eyes.abortIfNotClosed();

# Putting it all together (simplified code)

var webdriver = require("selenium-webdriver");
var Capabilities = webdriver.Capabilities;
var Builder = webdriver.Builder;
var By = webdriver.By;

var SeleniumSDK = require("eyes.selenium"); //Import Applitools SDK
var Eyes = SeleniumSDK.Eyes;

// Open a Chrome browser.
var driver = new Builder().withCapabilities(Capabilities.chrome()).build();

// Initialize the eyes SDK and set your private API key.
var eyes = new Eyes();
eyes.setApiKey("APPLITOOLS_API_KEY");

//scroll the entire page
eyes.setForceFullPageScreenshot(true);

try {
  // Start the test and set the browser's viewport size to 600 x 800
  eyes.open(driver, "Test app", "First test", { width: 600, height: 800});

  // Navigate the browser to the demo app
  driver.get("https://demo.applitools.com");

  // Visual checkpoint #1.
  eyes.checkWindow("Login Window test");
  //🌟 Note: You can have multiple "checkWindow" to create multiple test steps within a test.🌟  
  //For example, you may want to test errors in the login window after clicking a login button,
  //In that case, you may add the following before you call eyes.close(). 
  //This will create a test with two test steps.
  //driver.click("login");
  //eyes.checkWindow("Login Window Error");
  // End the test.
  eyes.close(false);
} finally {
  // Close the browser.
  driver.quit();

  // If the test was aborted before eyes.close was called ends the test as aborted.
  eyes.abortIfNotClosed();
}

# Step-by-Step guide

The tutorial provides a detailed step-by-step guide to help you get started. This has lots of gifs and pictures to help you glide through it. Our objective is to quickly show you how powerful and useful AI can be in automation testing.

Note: You can download the code from this Github repo.

• Part 1 - 🚀 Setup Applitools and create a baseline

• Part 2 - 🐞 Find UI bugs and analyze differences using AI

• Part 3 - 🤖 Understand why Applitools AI is superior to pixel-by-pixel comparison

• Part 4 - ✅ Accepting hundreds of changes by clicking a button instead of updating numerous tests

• Part 5 - 👁 Use our advanced AI tools to work with real-world scenarios

• Part 6 - 🎉 Congratulations!!

# Part 1 - Setup environment and create a baseline

Test Overview:

In this part, you will set up the environment to run the test locally and then store a baseline image of just the login page. We will use the app page later on.

Login page:

App page:

# Step 1.1: Install Prerequisites

1. Create an Applitools account and obtain your API key from the Person Icon > "My API key" menu.

2. Please set the APPLITOOLS_API_KEY environment variable

   • Mac: export APPLITOOLS_API_KEY='YOUR_API_KEY'

   • Windows: set APPLITOOLS_API_KEY='YOUR_API_KEY'

   TIP

   1. You may skip this step if you want to hard code the API KEY inside the tutorial project's code.
   2. It's better to store APPLITOOLS_API_KEY in the system variables (in Windows) or in the ~/.bash_profile (in Mac) so that it is accessible from all Terminal shells

3. Install node.js from https://nodejs.org​

4. Install git from https://git-scm.com​

   TIP

   Installing git is optional. You need this mainly to clone the demo project from the Github repository. Instead of installing git, you can simply download the Zip file from the repo. Further, If you are Mac, you already have git.

5. Install Google Chrome browser from https://www.google.com/chrome/

6. Install a Chromedriver that's appropriate for your operating system and your Chrome browser's version from http://chromedriver.chromium.org/downloads. For example, if your Chrome browser is v67-v69, download ChromeDriver 2.41.

   • Unzip ChromeDriver to any folder of your choice.

   • Add ChromeDriver's path to your system's PATH so Selenium can find it.

   • Mac:

     • Open ~/.bash_profile file (Create one if it's missing).
     • Add export PATH="<PATH_TO_YOUR_CHROME_DRIVER>:$PATH"
     • Run source ~/.bash_profile.
     • For example, if the chromedriver is in /Users/apps/chromedriver, then it would be export PATH="/Users/apps/:$PATH

   • Windows:

     • Navigate to Computer (Right click) | Properties | Advanced System Settings | Advanced (Tab) | Environment variables | System Variables.
     • Select the line with Path key.
     • Click on Edit.
     • Add a semicolon ; to the end of the values and add the path where you have unzipped ChromeDriver.
     • For example, if the ChromeDriver is in c:\selenium\chromedriver, then append ;c:\selenium to the end of the Path. Finally, save it.
     • If everything went fine, and if you typed chromedriver in the command prompt, you should see something like below:

# Step 1.2 Download the demo project

1. Clone the repo:

git clone https://github.com/applitools/tutorial-selenium-javascript.git

2. Go to the tutorial-selenium-javascript folder.

3. Run npm install

# Step 1.3 Run your first test

1. Run $ npm test part1

You should see the test run in a Chrome browser window.

//testSelector.js
let testsToRun = {
  url: baseUrl,
  appName: "Demo app",
  windowName: "Login Page",
  testName: "Login Page",
  goto2ndPage: false,
  viewportWidth: 800, //<-- Reduce this to 600
  viewportHeight: 750 //<-- Reduce this to 600
};

# Step 1.3: Check the baseline

Login to applitools.com and see the results. Applitools app should show the results like below.

# Part 2 - Find UI bugs and analyze differences using AI

In this part, you'll run the tests again but the test will use a different URL to simulate a broken UI.

# Step 2.1: Run the test again

Go to your command line and type the following command. It will test the login page (version 2) again and store the result in Applitools.

$ npm test part2

​

# Step 2.2 Analyze the result

Please switch to Applitools dashboard in your browser.

You will see a new test run with an "unresolved" status. This means Applitools is asking you to check if the differences are valid. If so, accept it and this result will become a new baseline. If not, reject it and your result will be marked as "Failed" and your previous baseline remains as is.

# Step 2.3: Click on the resulting image

# Step 2.4 Click on the "Toggle" button to see differences between the baseline and current checkpoint

# Step 2.5 Click on the Radar button to highlight differences at once

This is very handy when your app is complex and has lot of data.

# Step 2.6 Zoom in and see each difference closely

# Part 3 - Understand why Applitools AI is superior to pixel-by-pixel comparison

At Applitools we have trained our AI with millions of images to look for differences in various ways. AI is also trained to ignore certain types of differences that human eyes usually ignore. We provide four different "modes" to compare differences. In this part, you will see how differences between 4 "modes" of comparisons.

# Step 3.1 Check out the "Strict" mode by selecting the option in the menu

This mode uses AI to simulate the differences that are commonly found by the human eye. It ignores some of the minor differences like "off-by-a-pixel" type errors. This eliminates most common false-positives of pixel-by-pixel comparison tools.

# Step 3.2 Check out the "Exact" mode by selecting the option in the left-menu

This mode does a pixel-by-pixel comparison. This will cause a lot of false positives! This is one of the big reasons why we use AI

Notice that a lot of things in the background image is also considered as real bugs! ⚠️

# Step 3.3 Check out "Content" mode by selecting the option in the menu

The Content mode works in a similar way to Strict except for the fact that it ignores colors.

# Step 3.4 Check out the "Layout" mode by selecting the option in the left-menu

This mode shows any major differences in the layouts like a major section is removed.

In our example there are no major layout changes so if you were simply testing if the structure of the app looks good, and are using the layout mode in your code, it would succeed!

# Part 4 - Accepting 100s of changes by clicking a button instead of updating numerous tests

Now let's imagine that you did your analysis and it turns out all those differences are because of just a new version of the app. Typically this means you'd need to throw out or rewrite 100s of tests! In "Visual testing" you don't have because you didn't really write any tests 😊!

To accept 100s of changes, simply click on one of the three "Thumbs up" buttons.

There are three options:

1. Accept the differences and the checkpoint image of this test step: This option allows us to accept all the changes for this specific step and not other steps in the same test (if there are multiple steps).

2. Accept the differences and checkpoint images of all test steps with similar differences: This option allows us to accept similar differences in all the steps.

3. Accept the differences and checkpoint images of all test steps: This accepts all test steps irrespective of similar differences or not. Essentially, you get a new baseline for all test steps.

# Step 4.1 : Select "Accept the differences and the checkpoint image of this test step" option

# Step 4.2: Press Save

# Step 4.3: Re-run the test

Switch to the command prompt and run:

$ npm test part2

# Step 4.4: Check the result in the Dashboard

Switch to Applitools dashboard in the browser. Press the "Refresh" button and then you should see the result marked as "Passed".

# Part 5 - Use advanced AI tools to work with real-world scenarios

In this part, you will run tests on the main app page and learn about how to deal with dynamic contents and floating contents.

# Step 5.1 Run the test on the main app

The following command opens the main app and generates a screenshot and closes it.

$ npm test part3

# Step 5.2 Run the test on the main app (version 2)

Now run the following command to open up the second version of the app so we can see differences.

$ npm test part4

​

# Step 5.3 See the differences

# Step 5.4 Dealing with Dynamic contents

Dynamic contents are contents that constantly change, for example, a clock. If you use the pixel-by-pixel comparison, your test will fail every time. Thankfully, Applitools provide a simple way to ignore a region so you can continue to visual test the rest of the page.

# Step 5.4.1 Click on the "Ignore region" option

# Step 5.4.2 Select the region around the time

# Step 5.4 Dealing with floating contents

Sometimes the data remains the same but they move or float around a bit. For example, if you center-align some data then if the data changes, the browser will move it a bit to keep it center. But this causes problems for the visual test. Again, you can use Applitools' "Floating region" option to manually add some wiggle room.

In our app, the Your nearest branch closes in: text moves sideways because it is center aligned. Let's add some wiggle room.

# Step 5.4.1 Select "Floating region" option from the menu

# Step 5.4.2 Select the area around the "Your closest branch closes in:" to add

# Step 5.4.3

Press "Thumbs up" button accept the changes.

# Step 5.4.4

Press "Save" to save it as a new baseline.

# Part 6 - Congratulations and next steps!

Applitools Eyes is a powerful platform for automated visual UI testing that supports full page screenshots, page layout matching, cross-device and browser testing, test batching, baseline branching and merging, automated baseline maintenance, collaboration features, and much more. Applitools has over 40 SDKs supporting a broad range of testing environments.

# Reference documentation

To learn more, check out the Applitools Eyes documentation and tutorials for other testing environments.

# Request a demo

If you want to see a demo of all our other features, you do request a demo

# Knowledge base and Support

You can search our Knowldege base for more information. You can also file a contact our support team and file a Ticket.


Terms & Conditions Privacy Policy GDPR© 2019 Applitools. All rights reserved.