From 3cc5fd07c577713088c656059657e027e39a204e Mon Sep 17 00:00:00 2001 From: Peter Stakoun Date: Thu, 5 Dec 2024 15:45:11 -0500 Subject: [PATCH 1/4] supplementalElements UI Coverage configuration --- .../configuration/supplementalElements.mdx | 145 ++++++++++++++++++ 1 file changed, 145 insertions(+) create mode 100644 docs/ui-coverage/configuration/supplementalElements.mdx diff --git a/docs/ui-coverage/configuration/supplementalElements.mdx b/docs/ui-coverage/configuration/supplementalElements.mdx new file mode 100644 index 0000000000..376827f487 --- /dev/null +++ b/docs/ui-coverage/configuration/supplementalElements.mdx @@ -0,0 +1,145 @@ +--- +title: 'Supplemental Elements | Cypress UI Coverage' +description: 'The `supplementalElements` configuration property allows users to specify additional elements that should be included in UI Coverage.' +sidebar_label: supplementalElements +--- + +# supplementalElements + + + +UI Coverage has logic that automatically [identifies](/ui-coverage/core-concepts/element-identification) and [groups](/ui-coverage/core-concepts/element-grouping) elements based on their appearance and structure in the DOM. + +Sometimes, an element may not have enough information for Cypress's UI Coverage algorithm to accurately perform identification and grouping. This can cause the same element to be identified as multiple different elements, or multiple different elements to be identified as the same element. + +The `supplementalElements` configuration property allows users to specify selectors for parent elements that should be used to supply additional information for identifying and grouping elements, thereby allowing UI Coverage to find more suitable identifiers for elements nested within these supplemental elements. + +For every element considered interactive and visible by UI Coverage, each element above it in the DOM is run through the `supplementalElements` configuration. For each parent element that matches a `supplementalSelector`, its significant attributes will be used to help identify and group elements that match the corresponding `elementSelector`. If no `elementSelector` is specified, the supplemental information will be applied to all descendant elements. + +## Syntax + +```json +{ + "uiCoverage": { + "supplementalElements": [ + { + "supplementalSelector": string, + "elementSelector": string + } + ] + } +} +``` + +### supplementalElements + +_Optional._ Object\[] + +An array of objects used to determine which parent elements should be used to supply additional information for identifying and grouping elements. _**Each object can have the following properties:**_ + +### supplementalSelector + +_Required._ String (CSS Selector) + +Used to match the parent elements that should be used to supply additional information for identifying and grouping elements. + +### elementSelector + +_Optional._ String (CSS Selector) + +_Default_: `*` (matches any value). + +Used to match elements that should receive supplemental information. + +## Examples + +### Using a parent element to provide supplemental data for all elements + +#### Config + +```json +{ + "uiCoverage": { + "supplementalElements": [ + { + "supplementalSelector": ".page-container", + "elementSelector": "*" + } + ] + } +} +``` + +#### HTML + +```xml + + +
+ + +
+ + + + +
+ + +
+ +``` + +#### Elements shown in UI + +``` +#login-page #submit +#login-page #cancel +#signup-page #submit +#signup-page #cancel +``` + +### Using a parent element to provide supplemental data for specific elements + +#### Config + +```json +{ + "uiCoverage": { + "supplementalElements": [ + { + "supplementalSelector": ".page-container", + "elementSelector": "#submit" + } + ] + } +} +``` + +#### HTML + +```xml + + +
+ + +
+ + + + +
+ + +
+ +``` + +#### Elements shown in UI + +``` +#login-page #submit +#signup-page #submit +#cancel +``` From f5f5b4b7e94393dca732e871a0f506408a00ffb8 Mon Sep 17 00:00:00 2001 From: Peter Stakoun Date: Thu, 5 Dec 2024 15:48:46 -0500 Subject: [PATCH 2/4] Fix classes --- docs/ui-coverage/configuration/supplementalElements.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/ui-coverage/configuration/supplementalElements.mdx b/docs/ui-coverage/configuration/supplementalElements.mdx index 376827f487..7528775e56 100644 --- a/docs/ui-coverage/configuration/supplementalElements.mdx +++ b/docs/ui-coverage/configuration/supplementalElements.mdx @@ -75,7 +75,7 @@ Used to match elements that should receive supplemental information. ```xml -
+
@@ -83,7 +83,7 @@ Used to match elements that should receive supplemental information. -
+
@@ -121,7 +121,7 @@ Used to match elements that should receive supplemental information. ```xml -
+
@@ -129,7 +129,7 @@ Used to match elements that should receive supplemental information. -
+
From d934073a749bb69a97d8c58369fbe15cf0a3a739 Mon Sep 17 00:00:00 2001 From: Peter Stakoun Date: Thu, 5 Dec 2024 16:33:50 -0500 Subject: [PATCH 3/4] Rename file for consistency --- .../{supplementalElements.mdx => supplementalelements.mdx} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/ui-coverage/configuration/{supplementalElements.mdx => supplementalelements.mdx} (100%) diff --git a/docs/ui-coverage/configuration/supplementalElements.mdx b/docs/ui-coverage/configuration/supplementalelements.mdx similarity index 100% rename from docs/ui-coverage/configuration/supplementalElements.mdx rename to docs/ui-coverage/configuration/supplementalelements.mdx From 8f42d43bd55a50c221ae0ad4af4cfe845f0200e0 Mon Sep 17 00:00:00 2001 From: Peter Stakoun Date: Fri, 13 Dec 2024 16:19:23 -0500 Subject: [PATCH 4/4] Fix description --- docs/ui-coverage/configuration/supplementalelements.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ui-coverage/configuration/supplementalelements.mdx b/docs/ui-coverage/configuration/supplementalelements.mdx index 7528775e56..d4a4855e82 100644 --- a/docs/ui-coverage/configuration/supplementalelements.mdx +++ b/docs/ui-coverage/configuration/supplementalelements.mdx @@ -1,6 +1,6 @@ --- title: 'Supplemental Elements | Cypress UI Coverage' -description: 'The `supplementalElements` configuration property allows users to specify additional elements that should be included in UI Coverage.' +description: 'The `supplementalElements` configuration property allows you to specify parent elements that should be used to supply additional information for identifying and grouping elements.' sidebar_label: supplementalElements ---