taiko-eyes

Applitools API key

In order to authenticate via the Applitools server, you need to supply the Taiko-Eyes SDK with the API key you got from Applitools. Read more about how to obtain the API key here.

Installation

• npm install taiko-eyes --save

To to this, set the environment variable APPLITOOLS_API_KEY to the API key before running your tests. For example, on Linux/Mac:

export APPLITOOLS_API_KEY=<your_key>

And on Windows:

set APPLITOOLS_API_KEY=<your_key>

It's also possible to specify the API key in the fixtures/applitools.config.js file. The property name is apiKey. For example:

module.exports = {
  apiKey: 'YOUR_API_KEY',
  ...
}

Example

const { openBrowser, goto, closeBrowser, eyes } = require('taiko');
const { taikoEyes } = eyes;

jest.setTimeout(130000);

beforeEach(async () => {
  await openBrowser({ headless: true });
  await taikoEyes.open({
    appName: 'Taiko Eyes!',
    testName: 'Taiko Visual Test!',
  });
});

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

after(async () => {
  await taikoEyes.waitForResults();
});

test('Should set item in storage', async () => {
  await goto('https://gauge.org/');
  await taikoEyes.checkWindow();
});

Best practice for using the SDK

Every call to taikoEyes.open and taikoEyes.close defines a test in Applitools Eyes, and all the calls to taikoEyes.checkWindow between them are called "steps". In order to get a test structure in Applitools that corresponds to the test structure in taiko, it's best to open/close tests in every it call. This can be done via the beforeEach and afterEach.

Commands

Open

Create an Applitools test. This will start a session with the Applitools server.

taikoEyes.open({
  appName: '',
  testName: ''
});

Check window

Generate a screenshot of the current page and add it to the Applitools Test.

taikoEyes.checkWindow();

waitForResults

Wait until all tests in the suite are completed and return their results. Note that if you don't wait for the tests to be completed then in case of a visual test failure, eyes cannot fail the test.

• it is recommended to wait for the results in the afterAll() hook.

await taikoEyes.waitForResults()

Arguments to taikoEyes.checkWindow

• tag

  (optional): A logical name for this check.

• target

  (optional): Possible values are: 1. window This is the default value. If set then the captured image is of the entire page or the viewport, use fully for specifying what window mode to use. 2. region If set then the captured image is of the parts of the page, use this parameter with region or selector for specifying the areas to captured.

• fully

  (optional) In case target is window, if fully is true (default) then the snapshot is of the entire page, if fully is false then snapshot is of the viewport.

    // Capture viewport only
    taikoEyes.checkWindow({
      target: 'window',
      fully: false,
    });

• selector

  (optional): In case target is region, this should be the actual css or xpath selector to an element, and the screenshot would be the content of that element. For example:

  Using a css selector
  taikoEyes.checkWindow({
    target: 'region',
    selector: {
      type: 'css',
      selector: '.element-to-locate'
    }
  });
    
  Using an xpath selector
  taikoEyes.checkWindow({
    target: 'region',
    selector: {
      type: 'xpath',
      selector: '//button'
    }
  });
    
  The shorthand string version defaults to css selectors
  taikoEyes.checkWindow({
    target: 'region',
    tag: 'Step1',
    sizeMode: 'selector',
    selector: '.action-element',
  });

• region

  (optional): In case target is region, this should be an object describing the region's coordinates for capturing the image. For example:

  taikoEyes.checkWindow({
    target: 'region',
    region: {top: 100, left: 0, width: 1000, height: 200}
  });

• ignore

  (optional): A single or an array of regions to ignore when checking for visual differences. For example:

  taikoEyes.checkWindow({
    ignore: [
      {top: 100, left: 0, width: 1000, height: 100},
      {selector: '.some-div-to-ignore'}
    ]
  });

• floating

  (optional): A single or an array of floating regions to ignore when checking for visual differences. More information about floating regions can be found in Applitools docs here. For example:

  taikoEyes.checkWindow({
    floating: [
      {top: 100, left: 0, width: 1000, height: 100, maxUpOffset: 20, maxDownOffset: 20, maxLeftOffset: 20, maxRightOffset: 20},
      {selector: '.some-div-to-float', maxUpOffset: 20, maxDownOffset: 20, maxLeftOffset: 20, maxRightOffset: 20}
    ]
  });

• layout

  (optional): A single or an array of regions to match as layout level. For example:

  taikoEyes.checkWindow({
    layout: [
      {top: 100, left: 0, width: 1000, height: 100},
      {selector: '.some-div-to-test-as-layout'}
    ]
  });

• strict

  (optional): A single or an array of regions to match as strict level. For example:

  taikoEyes.checkWindow({
    strict: [
      {top: 100, left: 0, width: 1000, height: 100},
      {selector: '.some-div-to-test-as-strict'}
    ]
  });

• scriptHooks

  (optional): A set of scripts to be run by the browser during the rendering. It is intended to be used as a means to alter the page's state and structure at the time of rendering. An object with the following properties:

  • beforeCaptureScreenshot: a script that runs after the page is loaded but before taking the screenshot. For example:

    taikoEyes.checkWindow({
      scriptHooks: {
        beforeCaptureScreenshot: "document.body.style.backgroundColor = 'gold'"
      }
    })

Close

Close the applitools test and check that all screenshots are valid.

It is important to call this at the end of each test, symmetrically to eyesOpen(or in afterEach() Close receives no arguments.

await taikoEyes.close();