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();
}

Notes

  1. Everything between eyes.open and eyes.close is called a Test.
  2. The eyes.checkWindow is the code that takes the picture and uploads the image to our AI eyes server.
  3. You can have multiple checkWindow if you are navigating multiple pages in a single test.

Also note that because this example has only one test, the code you include to add Applitools may look like a lot. But once you set things up, the only extra code you will add will be "eyes.checkWindow()", "eyes.checkRegion()" etc even if there are hundreds of tests.

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 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:

login page

App 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. API-key

  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: Chromedriver

Step 1.2 Download the demo project

  1. Clone the repo:

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

TIP

Optionally, download the Zip file and extract it from the git repo.

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

  2. 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.

Potential problems and their solutions

  1. You may see an error that says Chrome driver is not found. This means that either the Chrome driver is not downloaded or it is in your PATH. If you simply type chromedriver and if you see unknown command then chromedriver is not in your PATH.
  2. You may see an error that says "Could not set Viewport". This means that your computer monitor's viewport size is smaller than what the test app is using. If so, open the testSelector.js and reduce viewPortWidth and viewPortHeight. Keep reducing until it's smaller than your monitor's size.








ย 
ย 



//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.

Baseline 1

TIP

The initial run is automatically accepted as a baseline.

  1. If you don't see anything, click on the "Refresh" button

  2. The "Thumbs up" button is used to accept the image as a baseline

  3. The "Save" button is used to save a new baseline image

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.

TIP

Remember to click on the "Refresh" button in the left panel to see the new test result

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.3

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

Step 2.4

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.5

Step 2.6 Zoom in and see each difference closely

Step 2.6

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.

Part 3

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.

TIP

This is the default mode. You can set whichever mode you want in code.

Step 3.1

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.2

WARNING

Do not use this mode unless really necessary as it does pixel-by-pixel comparison and may lead to false positives.

Most other Visual testing tools/methods become useless because they use a simple pixel-by-pixel comparison.

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.

TIP

The content level can be useful if your website includes different colors which are not relevant for your tests

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!

Step 3.4

TIP

For most scenarios, we recommend using either the "Strict" mode or the "Layout" mode. Use "Content" and "Exact" modes for special cases.

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 ๐Ÿ˜Š!

Note

We'll go over the few lines of code you will add to import Applitools and generate images but that's about all the code you'll write. And once you wrote it, it won't change!

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.2

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". Step 4.4

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. Part 5

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

A note about taking a full page screenshot

Note that the main app is pretty long and goes below the fold (or, below the current viewport). So Applitools scrolls down the page twice. First to load everything below the scroller. Then it goes back up to the top of the page and scrolls down the second time to take the screenshot.

This is because we have eyes.setForceFullPageScreenshot(true); //force scrolling

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.3

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.2

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

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ยฉ 2018 Applitools. All rights reserved.

Last Updated: 10/16/2018, 1:53:23 PM