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

Compatibility

• This plugin is NOT compatible with Cypress 10+ yet
• Tested with Cypress 4.8.0+, 5, 6, 7, 8, and 9
• Node 12+ is required
• Cypress 4.8.0 is the oldest Cypress version supported
• ES6 and Node 14+ is highly recommended

How to use the Wring Cypress plugin

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

2. Add the required config object to your cypress.json file:

   {...,
     "wring": {
       "serverTimeout": 180.0,
       "handleFailure": "exception",
       "filterEnabled": true,
       "filterDisplayed": true,
       "neighborMaxDist": 300.0,
       "fastHeal": false,
       "takeScreenshots": false,
       "imageComparison": false,
       "allSuggestEnabled": false,
       "useAttributes": null,
       "ignoreAttributes": null,
       "commandWaitSeconds": null
     }...
   }

   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/wring-cypress-plugin, using the ES6 module import syntax:

   import '@aichemy/wring-cypress-plugin';

   or CommonJS import syntax:

   require('@aichemy/wring-cypress-plugin');

4. Export the required environment variables before starting Cypress:

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

   Or place the corresponding items: TG_ENABLED and TG_TOKEN in your cypress.env.json file.

5. Review how to ignore selectors below if required for your use case.

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

   ./node_modules/.bin/cypress open

Plugin settings

• "serverTimeout" (default: 180.0) sets the maximum time in seconds to wait for a response from the Wring 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 Wring service. ( NOTE: "defaultCommandTimeout" is specified in milliseconds).
• "handleFailure" (default: exception) tells the plugin what to do when healing a selector fails because there is no previous training data. If this is set to the default exception, the plugin will not attempt to fix a broken selector that has no training data and fail with an exception so the test run fails normally. If set to suggest-xpaths, the plugin will request a best-effort heal from the Wring API for a broken selector without any prior training data. If a healed selector is found in this case, the plugin will retry the element query and attempt to continue with your test run.
• "filterEnabled" (default: true) 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" (default: true) 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" (default: 300.0) 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). Adjusting this parameter can greatly speed up the test run when our plugin is being used.
• "fastHeal" (default: false) tells the plugin to check if the Wring 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 Wring API should always be kept up to date on the current version.
• "takeScreenshots" (default: false) tells the plugin whether to take screenshots for every selector encountered during the Cypress test run. Setting this to true 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 greatly speed up your Cypress test run, since each Cypress screenshot invocation takes about 2 seconds.
• "imageComparison" (default: false) 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.
• "allSuggestEnabled" (default: false) tells the plugin whether it should collect information on all elements on the page whenever the URL changes during the test run. The plugin asks the Wring API to generate CSS selectors for all of these elements. This can help augment your test cases by presenting robust selectors for all elements encountered during the test run. This adds about 2 seconds per page encounter to the test run time. Note that generating selectors for all elements encountered on each page encountered is a CPU intensive task, and is performed asynchronously by the Wring API. In the worst case, all generated selectors may not appear in the Wring dashboard UI for a few minutes after your test run finishes.
• "useAttributes" (default: null) is used to specify a comma-separated string list of HTML element attributes that the Wring API should preferentially use when generating selector suggestions and when healing selectors, for example: "useAttributes": "data-test,data-cypresstest,data-formtest".
• "ignoreAttributes" (default: null) is used to specify a comma-separated string list of HTML element attributes that the Wring API should NOT use when generating selector suggestions and when healing selectors, for example: "ignoreAttributes": "id,href,class". This is useful when your webapp's HTML is generated by an SPA or no-code framework and the specified attributes have no semantic meaning, thus are not suitable for use in selectors.
• "commandWaitSeconds": (default: null) is used to specify a time period in seconds to wait before each Cypress command is executed. This can be useful to visualize the changes on the webpage as the test runs. Note that this option can be used even if the interceptor is not enabled. Setting the environment variable CYPRESS_TG_COMMANDWAIT=<some number greater than 0> will also enable the command-wait mode without requiring that the full interceptor is enabled. If this environment variable is set, it overrides the value in the wring object in the cypress.json file.

Tagging test runs

In addition to these settings, the plugin also supports adding tags to your test runs for better organization and easier viewing in the Wring dashboard. To add tags, set an environment variable:

export CYPRESS_TG_RUNTAGS='tag1,tag2,tag3'

By default, the plugin adds the tags: "cypress, interceptor, javascript". Any tags specified in the CYPRESS_TG_RUNTAGS environment variable will replace these tags.

Support for test suites

If your test scripts can be grouped into test suites, you can direct the Wring API to group your test scripts accordingly. Setting the environment variable CYPRESS_TG_SUITE with the name of your test suite will set up your test script to be counted as part of this suite in the Wring dashboard and instantiate a new test suite run for this test suite. Similarly, setting the environment variable CYPRESS_TG_SUITERUN will set up your test script to be counted as part of an existing test suite run if the name matches, or create a new test suite run by that name if it doesn't. The behavior of these settings is detailed below:

• Set CYPRESS_TG_SUITE only:
  • creates a new test suite with the given name if one doesn't exist with this name
  • creates a new test suite run named Default test suite run associated with this test suite
  • marks this test script as part of the new test suite run associated with this test suite
• Set CYPRESS_TG_SUITERUN only:
  • creates a new test suite named Default test suite if it doesn't exist
  • creates a new test suite run with the given name associated with this test suite
  • marks this test script as part of the new test suite run associated with this new test suite
• Set CYPRESS_TG_SUITE and CYPRESS_TG_SUITERUN:
  • creates a new test suite with the given name if it doesn't exist
  • creates a new test suite run with the given name associated with this test suite if it doesn't exist
  • marks this test script as part of the given test suite run associated with this test suite
• Unset CYPRESS_TG_SUITE and CYPRESS_TG_SUITERUN (default):
  • this test script is not associated with a test suite or test suite run

Ignoring selectors

Selectors that you don't want healed (e.g. for negative test scenarios) may be placed in a .tgignore file. In this 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

To make the Wring API aware of the ignored selectors in this file, you must run a pre-processing step before your test run. After the Wring Cypress plugin is installed, it places a script entry for this purpose in your package.json that you can run:

npm run tgignore [add|remove|check] [path to .tgignore file]

If the first script argument is add, all selectors in the provided .tgignore file will be added to the Cypress ignored selectors list. The Wring Cypress plugin will ignore these selectors when they are encountered in any test from now on.

If the first argument is remove, all selectors in the provided .tgignore file will be removed from the Cypress ignored selectors list. The Wring Cypress plugin will process these selectors when they are encountered in any test from now on.

If the first argument is check, the selectors in the provided .tgignore file will be sent to the Wring API to check if they are on the Cypress ignored selectors list. The script will print out each selector and its ignore status.

If no second argument is given, the script will look for a .tgignore file in the current working directory.

Examples

Run npm run tgignore add with a .tgignore file in the Cypress project directory:

{
  message: "Operation: 'add' for tgIgnore successful.",
  response: {
    userId: '96b755d1-8418-4aa2-b38f-049dda7bcd8e',
    ignoredSelectors: [ "a.btn.btn-primary.btn-lg[href='/login']" ],
    createdAt: '2021-09-20T19:37:11.193435+00:00',
    updatedAt: '2021-09-20T20:30:55.613033+00:00',
    isActive: true
  },
  status: 'success'
}

Run npm run tgignore remove with a .tgignore file in the Cypress project directory to remove all the selectors in the file from the ignored-selectors list:

{
  message: "Operation: 'remove' for tgIgnore successful.",
  response: {
    userId: '96b755d1-8418-4aa2-b38f-049dda7bcd8e',
    ignoredSelectors: [],
    createdAt: '2021-09-20T19:37:11.193435+00:00',
    updatedAt: '2021-09-20T20:31:49.128542+00:00',
    isActive: true
  },
  status: 'success'
}

Run npm run tgignore check with an updated .tgignore file in the Cypress project directory to see if all selectors in the file are registered as ignored selectors:

{
  message: "Operation: 'check' for tgIgnore successful.",
  response: {
    userId: '96b755d1-8418-4aa2-b38f-049dda7bcd8e',
    ignoredSelectors: [ "a.btn.btn-primary.btn-lg[href='/login']" ],
    createdAt: '2021-09-20T19:37:11.193435+00:00',
    updatedAt: '2021-09-20T20:34:26.122700+00:00',
    isActive: true,
    missingIgnoredSelectors: [ 'input[name="password"]' ]
  },
  status: 'success'
}

In this case, the missingIgnoredSelectors item contains selectors that are in the .tgignore file but aren't registered as ignored by the Wring API. To add these missing selectors, run npm run tgignore add again:

{
  message: "Operation: 'add' for tgIgnore successful.",
  response: {
    userId: '96b755d1-8418-4aa2-b38f-049dda7bcd8e',
    ignoredSelectors: [ "a.btn.btn-primary.btn-lg[href='/login']", 'input[name="password"]' ],
    createdAt: '2021-09-20T19:37:11.193435+00:00',
    updatedAt: '2021-09-20T20:35:19.811131+00:00',
    isActive: true
  },
  status: 'success'
}

Changelog

2.1.5 - 2023-03-10

New stuff

• The environment variables CYPRESS_TG_SUITE and CYPRESS_TG_SUITERUN can now be populated to set up a test script run that belongs to a test suite.

2.1.4 - 2023-02-28

Fixes

• Fixed a typo in the README.

2.1.3 - 2023-02-28

Changes

• The "commandWaitSeconds" option is now effective even if the interceptor is not in use. Setting the environment variable CYPRESS_TG_COMMANDWAIT=<some number greater than 0> will also enable the command-wait mode (and override the option set in the cypress.json file).

2.1.2 - 2023-02-28

New stuff

• There is a new option to enable waiting for a certain amount of seconds before every Cypress command is executed. Set the "commandWaitSeconds" item in the "tgConfig" options object to enable this feature.

2.1.1 - 2022-10-04

Fixes

• Removed inadvertently added json tags for the output listings of the tgignore script.

2.1.0 - 2022-10-04

New stuff

• Tags can now be added to your runs for better organization. See the settings section above for details.
• The plugin now adds "cypress, interceptor, javascript" as default run tags to help find Cypress test runs in the Wring dashboard.

Fixes

• Log messages now correctly reference the "Wring API" instead of the "TG API".

Changes

• Updated the Cypress version compatibility statement to include Cypress 6, 7, 8, and 9. A plugin version compatible with Cypress 10 will be made available later.
• The default max timeout when waiting for selector success has been increased to 4 seconds to reduce false-positive triggers for the heal-flow when the network connection is slow.
• Release notes for plugin versions older than 1.8.0 have been removed from this listing to save space. Find these at: https://www.npmjs.com/package/@aichemy/testgold-cypress-plugin

2.0.0 - 2022-09-17

This version of the plugin changes the product name from TestGold to Wring. The package is now called @aichemy/wring-cypress-plugin.

Fixes

• Fixes for analyzer requests breaking the test run if the plugin was not enabled.

1.8.4 - 2022-04-26

Fixes

• Updated node-fetch dependency for security advisory.

1.8.3 - 2022-04-26

New stuff

• Added the "useAttributes" and "ignoreAttributes" plugin settings items to control how the Wring API generates selector suggestions and healed selectors. See the plugin settings above for details.

1.8.2 - 2022-03-10

Fixes

• Fixed an arg not being populated correctly for the TG analyzer API.

1.8.1 - 2022-03-09

New stuff

• Added parsing of the input-element 'clear' action for test steps.

Fixes

• Correct parsing of the 'mouseover' action for test steps.
• Correct parsing of the 'wait' action for test steps.

1.8.0 - 2022-03-08

This version of the plugin adds compatibility with the analyzer feature of the Wring API. At the moment, this populates the "Run steps" tab in the Wring UI with a list of executed steps described in plain English. In the future, this will enable test script auto-maintenance. The following Cypress commands are currently recognized:

check
uncheck
click
dblclick
hover
rightclick
type
select
submit
get
visit
wait

New stuff

• Added TG analyzer API endpoint usage.

Versions older than 1.8.0 are described on the old aichemy/testgold-cypress-plugin page at: https://www.npmjs.com/package/@aichemy/testgold-cypress-plugin