@aichemy/testgold-cypress-plugin

This is the TestGold plugin for Cypress. It enables auto-healing of failed selectors.

Compatibility

• Tested with Cypress 6.2.0 to 6.9.1 and Node 12+
• Cypress 4.8.0 is the oldest Cypress version supported
• ES6 is highly recommended

How to use the TestGold Cypress plugin

1. Install the TestGold Cypress plugin package with NPM or yarn: @aichemy/testgold-cypress-plugin.

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

3. Update the cypress/support/index.ts or cypress/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');
   

4. Update the cypress/plugins/index.ts or cypress/plugins/index.js file in your tests' repo to include imports and registration of the testgold-cypress-plugin's screenshot and ignore-file hooks:

   const { addScreenshotHook } = require(
     '@aichemy/testgold-cypress-plugin/src/tgScreenshotHook'
   );
   const { tgIgnoreHook } = require(
     '@aichemy/testgold-cypress-plugin/src/tgIgnoreHook'
   );
   
   module.exports = (on, config) => {
     // `on` is used to hook into various events Cypress emits
     // `config` is the resolved Cypress config
   
     // register the TG plugin's screenshot hook
     addScreenshotHook(on, config);
   
     // register the TG plugin's ignoreFile hook
     on('task', {
       tgIgnore(ignoredArg) {
         return tgIgnoreHook(config);
       }
     });
   }
   

5. Export the required environment variables before starting Cypress:

   export CYPRESS_TG_ENABLED=true
   export CYPRESS_TG_TOKEN='your TestGold AIO token'
   

6. Start Cypress from your repo and run your tests:

   ./node_modules/.bin/cypress open
   

Ignoring selectors

Selectors that you don't want healed (e.g. for negative test scenarios) may be placed in a .tgignore file. Use the environment variable CYPRESS_TG_IGNORE to specify the path to this file. If this environment variable is not present, the plugin will look for a file called .tgignore in the root of your Cypress project (as returned by Cypress.config.projectRoot).

In the .tgignore file, specify selectors to be ignored during processing, listing them one per line, for example:

# comment lines starting with '#' are ignored
# list selectors to ignore, one per line
*[id="office_phone1234"]
.mobilePhoneClass1234

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 is suggest-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 (or false) 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 to true, 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 to false, disabled elements will still be considered when collecting training data.
• "filterDisplayed" tells the plugin how to treat invisible elements. If set to true, 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 to true; this will speed up the test run. If set to false, 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 to true, 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 to false 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 to true (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 to false 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.5.1 - 2021-05-10

Fixes

• Clean up for package contents.

1.5.0 - 2021-05-10

This version adds the ability to ignore selectors for heal processing by listing them in a .tgignore file. See Ignoring selectors for details.

Added

• New .tgignore handling to exclude selectors from TG heal processing.

Changes

• Internal API call changes for the next generation of the TG API.

Fixes

• Bugfixes for the case of fast-heal screenshots not working as expected.

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 to true by default if not explicitly specified in the "testGold" options object in cypress.json. This means the plugin will ignore any disabled or invisible elements while collecting training data.
• The option"neighborMaxDist" is now set to 300.0 by default if not explicitly specified in the "testGold" options object in cypress.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 to true 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.json testGold configuration object is set to true,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.