README
This is the TestGold plugin for Cypress. It enables auto-healing of failed selectors.
Compatibility
- Tested with Cypress 6.2.0+ and Node 12+
- Cypress 4.8.0 is the oldest Cypress version supported
- ES6 is highly recommended
How to use the TestGold Cypress plugin
Install the TestGold Cypress plugin package with NPM or yarn:
@aichemy/testgold-cypress-plugin
.Add the required config object to your
cypress.json
file:{..., "testGold": { "serverTimeout": 180.0, "handleFailure": "suggest-xpaths", "filterEnabled": true, "filterDisplayed": true, "neighborMaxDist": 300.0, "fastHeal": true, "takeScreenshots": true, "imageComparison": false }... }
See Plugin settings for what these settings do.
Update the
cypress/support/index.ts
orcypress/support/index.js
file in your tests' repo to include an import of the@aichemy/testgold-cypress-plugin
, using the ES6 module import syntax:import '@aichemy/testgold-cypress-plugin'
or CommonJS import syntax:
require('@aichemy/testgold-cypress-plugin')
Update the
cypress/plugins/index.ts
orcypress/plugins/index.js
file in your tests' repo to include an import of thetestgold-cypress-plugin
's screenshot hook:const { addScreenshotHook } = require( '@aichemy/testgold-cypress-plugin/src/tgScreenshotHook' ) module.exports = (on, config) => { // `on` is used to hook into various events Cypress emits // `config` is the resolved Cypress config addScreenshotHook(on, config) }
Export the required environment variables before starting Cypress:
export CYPRESS_TG_ENABLED=true export CYPRESS_TG_TOKEN='your TestGold AIO token'
Start Cypress from your repo and run your tests:
./node_modules/.bin/cypress open
Plugin settings
"serverTimeout"
sets the maximum time in seconds to wait for a response from the TestGold API. It's also a good idea to set the value of"defaultCommandTimeout"
in your cypress.json file to a similar value, so your Cypress tests don't time out while waiting for a selector to be healed by the TestGold service. ( NOTE:"defaultCommandTimeout"
is specified in milliseconds)."handleFailure"
tells the plugin what to do when healing a selector fails because there is no previous training data. The default value issuggest-xpaths
, which tells the plugin to request a best-effort heal from the TestGold API, despite not having trained it beforehand. Setting this to any other value (orfalse
) will disable this behavior. It's usually safe to leave this set to the default value."filterEnabled"
tells the plugin how to treat disabled elements. If set totrue
, elements on the page that are disabled will be ignored when collecting training data for a selector. In most cases, this will speed up the test run. If set tofalse
, disabled elements will still be considered when collecting training data."filterDisplayed"
tells the plugin how to treat invisible elements. If set totrue
, elements on the page that are hidden will be ignored when collecting training data for a selector. If you're sure your selectors will never try to find an invisible target element on the page, set this totrue
; this will speed up the test run. If set tofalse
, invisible elements will still be considered when collecting training data."neighborMaxDist"
tells the plugin the radius in pixels around each selector target element it should consider when collecting training data. Only elements within this radius will be processed for training if this option is set to a number greater than 0.0. Use this option when you're sure your target elements won't move too far from their current location when the page is revised (and their selectors need to be updated). Setting this option can greatly speed up the test run when our plugin is being used."fastHeal"
tells the plugin to check if the TestGold API has cached versions of training and healing data for a selector before processing it. If set totrue
, this check will be done for each selector. If your page has not changed between test runs, and cached versions of these data exist, the plugin will not need to collect training or healing data when processing the selector, thus speeding up your test run. Set this tofalse
when the page being tested is volatile, and the TestGold API should always be kept up to date on the current version."takeScreenshots"
tells the plugin whether to take screenshots for every selector encountered during the Cypress test run. Setting this totrue
(default) allows us to point out the candidate selected element locations on the page screenshot when we heal selectors. Disabling this option by setting it tofalse
can speed up your Cypress test run, since each Cypress screenshot invocation takes about 2 seconds."imageComparison"
is left in for compatibility with our Selenium selector auto-healing solution; it doesn't do much at this stage, so leave it as specified in the instructions above.
Changelog
1.4.0 - 2021-04-12
This version changes the default behavior of the plugin in the interest of making the selector training and auto-healing processes more performant out of the box. See the changes below.
Changes
- The options
"filterEnabled"
and"filterDisplayed"
are now set totrue
by default if not explicitly specified in the"testGold"
options object incypress.json
. This means the plugin will ignore any disabled or invisible elements while collecting training data. - The option
"neighborMaxDist"
is now set to300.0
by default if not explicitly specified in the"testGold"
options object incypress.json
. This means the plugin will now only search within a radius of 300 pixels around a target element while collecting training data.
1.3.3 - 2021-04-06
Changes
- Added a required request param for the payload sent by
startTestRequest()
to start a new TG API session.
1.3.2 - 2021-03-31
Added
- New
"takeScreenshots"
Cypress config item to control whether screenshots should be taken for every selector encountered during the test run. This is set totrue
by default.
1.3.1 - 2021-03-29
Changes
- Removed
export function
,export class
bits, changed to CommonJS exports for better ES5 compatibility. - The minimum version of Cypress where this plugin is expected to work is 4.8.0.
1.3.0 - 2021-03-29
This version of the TestGold Cypress plugin has fast-heal mode enabled by default.
Added
- Added compatibility notes to NPM package README.
- Added description of plugin options to NPM package README.
Changes
- Swapped out the @aws-crypto/sha256-browser dependency to use jsSHA instead.
- If the
fastHeal
option in the cypress.jsontestGold
configuration object is set totrue
,the plugin will first check with the TG API if the selector has any previous training or healing results.- If the selector works as-is, has been seen by the TG API before, and the page under test hasn't changed, re-training the selector is now unnecessary.
- If the selector being processed doesn't work, but has been seen by the TG API before, and the page under test hasn't changed, cached processing results from the TG API will be used to heal the selector immediately with no additional processing required.
- Setting this option to
true
should significantly speed up Cypress tests in most cases when this plugin is enabled.
Fixes
- Up to date screenshots are now available for fast-healed selectors.
1.2.2 - 2021-03-10
Fixes
- Trigger a TG API test-run "finished" event on Cypress "failed" and "uncaught:exception" events to catch more test-run-ended scenarios.
1.2.1 - 2021-02-26
Fixes
- Correct parsing of the values of TG_TOKEN and TG_ENABLED from the Cypress env object
1.2.0 - 2021-02-25
Changes
- Screenshots are now taken in the "runner" mode as opposed to "viewport" in 1.1.x.
1.1.19 - 2021-02-24
Initial complete NPM release.
1.1.18 - 2021-02-24
Testing NPM release.