Configuring the Cypress SDK

There are 3 different ways to pass configuration options to the Cypress SDK:

1. The cy.eyesOpen() command
2. Environment variables
3. Creating an applitools.config.js file in the root of the project

The above options are written in order in precedence meaning, anything passed to cy.eyesOpen() will overwrite the same options set in the applitools.config.js file or an environment variable.

Additionally, some options are only available at the global level which means they cannot be passed to cy.eyesOpen().

Configuration options

Option ---- Environment Variable	Default	Description
testName	The name of the currently executing test defined in the Cypress it() block	The name of the test. One of the 5 variables that define a baseline.
browser	{width: 800, height: 600, name: 'chrome'}	Browser configuration for the Ultrafast Grid. See Available Browsers & Devices
batchId ---- APPLITOOLS_BATCH_ID	A random id	Provides ability to group tests into batches. See batching documentation
batchName ---- APPLITOOLS_BATCH_NAME	The name of the first test executed	Strictly cosmetic name for the test batch. See batching documentation
batchSequenceName ---- APPLITOOLS_BATCH_SEQUENCE_NAME	undefined	Track batch performance statistics over time. See Batch Statistics Documentation
baselineEnvName ---- APPLITOOLS_BASELINE_ENV_NAME	undefined	Perform cross environment tests. See Batch Statistics Documentation
envName ---- APPLITOOLS_ENV_NAME	undefined	Name for the environment in which the application under test is running.
ignoreCaret ---- APPLITOOLS_IGNORE_CARET	false	If true, Eyes Visual AI will ignore the blinking text caret when comparing images.
matchLevel ---- APPLITOOLS_MATCH_LEVEL	'Strict'	Select the Match Level to use when comparing screenshots. Available options: Strict, Layout, Ignore Colors
branchName ---- APPLITOOLS_BRANCH_NAME	'default'	Name of the current branch.
baselineBranchName ---- APPLITOOLS_BASELINE_BRANCH_NAME	undefined	Name of the baseline branch, this must be the name of an existing Eyes branch. The test will take a baseline from this branch. If the defined branch does not have a baseline, a new baseline will be created in the current branch.
parentBranchName ---- APPLITOOLS_PARENT_BRANCH_NAME	undefined	Sets the branch under which new branches are created.
compareWithParentBranch ---- APPLITOOLS_COMPARE_WITH_PARENT_BRANCH	false	If true, the test will take a baseline from the parent branch. If the parent branch does not have a baseline, a new baseline will be created in the current branch.
saveDiffs ---- APPLITOOLS_SAVE_DIFFS	false	If true, tests with diffs are saved by default as a baseline.
saveNewTests ---- APPLITOOLS_SAVE_NEW_TESTS	true	If true, new tests are saved by default as a baseline.
properties	undefined	Custom properties for the eyes test. The format is an array of objects with name/value properties. See Custom Properties.
ignoreDisplacements	false	If true, the Test Manager will initially only display real mismatches, not mismatches for image features that have only been displaced.
ignoreBaseline ---- APPLITOOLS_IGNORE_BASELINE	false
notifyOnCompletion ---- APPLITOOLS_NOTIFY_ON_COMPLETION	false	If true batch completion notifications are sent. See Batch Completion Notifications
accessibilityValidation	undefined	An object that specifies the accessibility level and guidelines version to use for the screenshots. Possible values for level are None, AA and AAA, and possible values for guidelinesVersion are WCAG_2_0 and WCAG_2_1. For example: {level: 'AA', guidelinesVersion: 'WCAG_2_0'} See Contrast Advisor
layoutBreakpoints	undefined	When set to true, a snapshot of the DOM will be taken once 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. See Layout Breakpoints
waitBeforeCapture	100	A parameter that is set to wait a certain amount of milliseconds before capturing the pages snapshot. This will also apply between page resizes when using layoutBreakpoints

Global Configuration Options

The following configuration properties cannot be defined using the first method of passing them to cy.eyesOpen(). They should be defined either in the applitools.config.js file or as environment variables.

The configuration file, applitools.config.js needs to be placed in the folder which contains cypress.json and must be in a valid JSON format, for example:

module.exports = {
  appName: 'My app',
  showLogs: true,
  batchName: 'My batch'
  ...
  // all other configuration variables apply
}

Option ---- Environment Variable	Default	Description
apiKey ---- APPLITOOLS_API_KEY	undefined	The API key used for working with the Applitools Eyes server. See Registering an account
batch	undefined	An object which describes a batch: batch: { id: 'myId', name: 'Batch Name' notifyOnCompletion: true properties: [{name: 'My prop', value: 'My value'}] sequenceName: 'my sequence' }
disableBrowserFetching	false	If true, page resources for rendering on the UFG will be fetched from outside of the browser.
dontCloseBatches ---- APPLITOOLS_DONT_CLOSE_BATCHES	false	If true, batches are not closed for notifyOnCompletion.
enablePatterns	false
failCypressAfterAllSpecs	false	If true, Eyes checks for diffs only after all specs are complete. This means that if there are multiple spec files, the suite will run faster, but will not identify diffs in individual spec files and the file will be shown as pass in the Cypress report even if there are diffs.
failCypressOnDiff	true	If true, then the Cypress test fails if an Eyes test fails. If false and an Eyes test fails, then the Cypress test does not fail.
isDisabled ---- APPLITOOLS_IS_DISABLED	false	If true, all calls to Eyes-Cypress commands will be silently ignored.
proxy ---- APPLITOOLS_PROXY	undefined	Sets the proxy settings to be used in network requests to Eyes server. This can be either a string to the proxy URI, or an object containing the URI, username and password. For example: { url: 'https://myproxy.com:443', username: 'user', password: 'password', isHttpOnly: false } or: "https://user:password@myproxy.com:443"
removeDuplicateTests	false	If true, all duplicate tests except for the latest test are deleted. This setting is needed if test retries are enabled in Cypress.
serverUrl	Default Eyes server URL	The URL of Eyes server. Only relevant for users running their tests against a private Applitools instance.
showLogs ---- APPLITOOLS_SHOW_LOGS	false	Whether or not you want to see logs of the Eyes-Cypress plugin. Logs are written to the same output of the Cypress process.
tapDirPath	undefined	Directory path of a results file. If set, then a TAP file is created in this directory, the tap file name is created with the name ISO-DATE-eyes.tap and contains the Eyes test results (Note that because of a current Cypress limitation the results are scoped per spec file, this means that the results file is created once for each spec file).
testConcurrency ---- APPLITOOLS_CONCURRENCY	5	The maximum number of tests that can run concurrently. The default value is the allowed amount for free accounts. For paid accounts, set this number to the quota set for your account.
useDom	false