Skip to main content

Advanced Configuration

General Configuration​

Configuring the Server URL​

By default, the SDK communicates with the Applitools public Eyes cloud server, located at https://eyesapi.applitools.com.

If you have a dedicated cloud or an on-premise server, you can configure a different Eyes server URL using the following code:

eyes.setServerUrl('https://mycompanyeyesapi.applitools.com');

Configuring a Proxy​

If your company's network requires requests to go through a corporate proxy, you can configure it using the following code:

eyes.setProxy('http://yourproxy.com');

// Provide username and password:
eyes.setProxy('http://user:pass@yourproxy.com');
// OR
eyes.setProxy({
  url: 'https://yourproxy.com',
  username: 'user',
  password: 'pass'
});

// Use tunneling in case of an HTTP over HTTPS proxy:
eyes.setProxy({
  url: 'http://yourproxy.com',
  isHttpOnly: true
});

Integrating with Functional Tests​

You can integrate an Eyes test with a functional test that you have created in a different system.

Every call to eyes.open and eyes.closeAsync defines a test in Applitools Eyes, and all the calls to eyes.check between them are called "steps." To align the test structure in Applitools with your functional test, you should open and close tests in every test call.

For example, when running with Mocha as a test runner:

describe('My first visual test', function() {
  beforeEach(async () => {
    await eyes.open(browser, "webdriver.io website", "My first webdriver.io test!");
  });

  afterEach(async () => {
    await eyes.close();
  });

  it('...', async function() {
    // ...
  });
});

In the above code, the describe block represents the test suite, and the beforeEach and afterEach hooks are used to open and close the Eyes test respectively. The it block represents an individual test case where you can write your functional test code.

Organizing Tests in Batches​

To manage how visual tests are grouped into batches, you can use the following methods:

Method 1: Environment Variable​

Run all the processes that execute WebdriverIO with the same value for APPLITOOLS_BATCH_ID. For example, execute all WebdriverIO files specified in the configuration file wdio.conf.js with the same randomly generated UUID:

You can use an environment variable to ensure that all processes executing WebdriverIO have the same value for APPLITOOLS_BATCH_ID.

The following example runs WebdriverIO files specified in the wdio.conf.js configuration file with the same randomly generated UUID:

# Unix based machines:
APPLITOOLS_BATCH_ID=`uuidgen` npx wdio wdio.conf.js

You can control the batch name displayed in the Test Manager, for example:

export APPLITOOLS_BATCH_ID=`uuidgen`
export APPLITOOLS_BATCH_NAME="Login tests"
npm test

Method 2: Set Batch​

You can use the eyes.setBatch method to assign the same value for the batch ID across all Eyes instances. For example:

eyes.setBatch({
  id: SOME_SHARED_VALUE_THAT_WILL_BE_THE_SAME_FOR_ALL_TEST_FILES,
  name: 'My batch'
});

By setting the batch ID using these methods, you can effectively organize and group your visual tests into logical batches.

Test Configuration​

Test Properties​

When working with test batches in Applitools Eyes, you can specify test properties per batch by using the setProperties method on the BatchInfo object. This method allows you to provide an array of properties, each with a {name, value} structure.

Following is an example of how you can set test properties per batch:

const { Eyes, BatchInfo } = require('@applitools/eyes-webdriverio');

const eyes = new Eyes();

const batch = new BatchInfo();
batch.setProperties([{ name: 'my custom batch property', value: 'some value' }]);

const configuration = eyes.getConfiguration();
configuration.setBatch(batch);
eyes.setConfiguration(configuration);

Test Results​

To create a formatted output string from the TestResults object in Applitools Eyes, you can use the following example code:

function formatTestResults(testResults) {
  return `
Test name                 : ${testResults.getName()}
Test status               : ${testResults.getStatus()}
URL to results            : ${testResults.getUrl()}
Total number of steps     : ${testResults.getSteps()}
Number of matching steps  : ${testResults.getMatches()}
Number of visual diffs    : ${testResults.getMismatches()}
Number of missing steps   : ${testResults.getMissing()}
Display size              : ${testResults.getHostDisplaySize().toString()}
Steps                     :
${testResults
  .getStepsInfo()
  .map(step => `  ${step.getName()} - ${getStepStatus(step)}`)
  .join('\n')}`;
}

function getStepStatus(step) {
  if (step.getIsDifferent()) {
    return 'Diff';
  } else if (!step.getHasBaselineImage()) {
    return 'New';
  } else if (!step.getHasCurrentImage()) {
    return 'Missing';
  } else {
    return 'Passed';
  }
}

In the provided code, the formatTestResults function takes a TestResults object as input and returns a formatted string containing various information about the test results. The string includes details such as the test name, test status, URL to the results, total number of steps, number of matching steps, number of visual diffs, number of missing steps, and display size. Additionally, it includes information about each step, indicating its name and status.

Stitch Mode​

In Applitools Eyes, when taking a full-page screenshot, the SDK captures multiple screenshots of the viewport at different positions on the page and then combines them into a single image. This process is known as "stitching."

The stitch mode determines how images are pasted together:

  • Scroll stitch mode - This mode simulates scrolling behavior by capturing the viewport screenshot and then scrolling the page to capture additional screenshots at calculated positions. The screenshots are stitched together to create a complete image of the entire page. However, one limitation of this mode is that if the page responds to scroll events and changes its visual appearance, it might result in inconsistencies between the stitched screenshots.

  • CSS stitch mode - In this mode, the page is moved by manipulating the CSS property transform on the HTML element. The SDK changes the translate(x, y) values to capture different portions of the page. This method is not affected by scroll events, making it more reliable in scenarios where the page dynamically adjusts its layout during scrolling.

The default stitch mode is Scroll. To change it:

const { Eyes, StitchMode } = require('@applitools/eyes-webdriverio');

const eyes = new Eyes();
eyes.setStitchMode(StitchMode.CSS);

To revert to scroll mode:

eyes.setStitchMode(StitchMode.SCROLL);

Stitch Overlap​

The stitch overlap refers to the length of the intersecting area between two screenshots that are stitched together to create a full-page screenshot. It represents the amount of overlapping pixels between adjacent images. The stitch overlap is particularly useful when dealing with fixed elements, such as a footer, that appear in each sub-screenshot. By setting a stitch overlap larger than the size of the footer, you can ensure that the footer is excluded from each individual screenshot and only appears once at the bottom of the full-page screenshot.

The default stitch overlap is 50 pixels. You can change the stitch overlap by using the setStitchOverlap method as shown in the following example:

eyes.setStitchOverlap(60);

Match Level​

The match level determines how Eyes compares the checkpoint image with the baseline image.

The following match levels are available:

  • Strict - (Default) Detects changes in text, font, color, graphics, and position of elements. It aims to detect differences that are visible to the human eye while ignoring differences in pixel values that are platform dependent due to the rendering software and hardware.

  • Layout - Identifies changes in various page elements, such as text, images, buttons, and columns, and verifies that the relative positions of these elements are consistent. This match level can detect elements that have appeared, disappeared, or moved. With this match level, Eyes ignores differences in the actual content text and graphics, color, and other style changes. This level is useful for pages with dynamic content, language localization, and cross-environment testing where a single baseline is used for multiple execution environments.

  • Ignore colors - Similar to the strict match level but ignores changes in colors. It is effective when your content is static but the color varies, for example if there are buttons or screen elements that can appear in a variety of colors.

  • Exact - Pixel-to-pixel comparison of the checkpoint and baseline images. It is sensitive to differences such as rendering anomalies that are not visible to the human eye. It is not recommended for ordinary verification purposes.

  • Dynamic - Recognizes defined text patterns such as a date, email address, or URL. For details, see Dynamic text match level

For more information, see How to use Eyes match levels.

The default match level is Strict.

To change the match level for the rest of the execution:

const { MatchLevel } = require('@applitools/eyes-webdriverio');
eyes.setMatchLevel(MatchLevel.Layout);

To change the match level for a single checkpoint:

await eyes.check(Target.window().layout());
await eyes.check(Target.window().strict());
await eyes.check(Target.window().ignoreColors());
await eyes.check(Target.window().exact());
await eyes.check(Target.window().dynamic());

Ignore Displacements​

Use ignore displacements to hide differences that arise from content whose position on the page has changed. For example, if text is longer in the checkpoint or the size of an image has changed, if IgnoreDisplacements is set to true, unchanged content that has shifted position because of the changed text or image will not be marked as a difference.

The default is false.

For more information, see Hide displacement diffs tool.

To change the displacement for the rest of the execution:

eyes.setIgnoreDisplacements(true);

To change the displacement for a single checkpoint:

await eyes.check(Target.window().ignoreDisplacements());

Wait Before Screenshot​

Sets the number of milliseconds to wait before the screenshot is captured. This will also apply between page resizes when using layoutBreakpoints. This is useful if the page is slow to load.

config = { waitBeforeScreenshots: value_number };

Layout Breakpoints​

If true, a new snapshot of the DOM will be taken for each browser/device size in the browser configuration. For optimization purposes, an array of numbers can be passed. The DOM snapshot will be taken once for every width in the array.

config = new Configuration();
config.setLayoutBreakpoints(true);
config.setLayoutBreakpoints([800, 1200, 1600]);

Logging​

To enable logging to the console, use the ConsoleLogHandler class:

import { Eyes, ConsoleLogHandler } from '@applitools/eyes-webdriverio';

const eyes = new Eyes();
eyes.setLogHandler(new ConsoleLogHandler());

// To enable verbose logging:
eyes.setLogHandler(new ConsoleLogHandler(true));