diff --git a/docs/accessibility/configuration/significantattributes.mdx b/docs/accessibility/configuration/significantattributes.mdx index 15a3dc8e66..5434c285f9 100644 --- a/docs/accessibility/configuration/significantattributes.mdx +++ b/docs/accessibility/configuration/significantattributes.mdx @@ -9,4 +9,6 @@ sidebar_position: 40 # significantAttributes +The `significantAttributes` property allows you to specify which attributes should be considered significant when identifying elements in Cypress Accessibility. + diff --git a/docs/partials/_significantattributes.mdx b/docs/partials/_significantattributes.mdx index 4c67dc3715..62b1c44371 100644 --- a/docs/partials/_significantattributes.mdx +++ b/docs/partials/_significantattributes.mdx @@ -1,10 +1,10 @@ -The `significantAttributes` property allows you to specify which attributes should be considered significant for UI Coverage analysis. - ## Why use significant attributes? -- **Focus on Important Changes**: Track attributes that are most relevant to user interaction and functionality -- **Reduce False Positives**: Avoid flagging changes in non-essential attributes as coverage issues -- **Improve Report Clarity**: Make coverage reports more meaningful by focusing on attributes that matter +Cypress uses a [default set of attributes](/accessibility/core-concepts/element-identification) (such as common test ID patterns), in a priority order, as the preferred way to identify elements in reports. + +The values of these attributes are used as element identifiers, which helps us recognize the same element in multiple contexts and deduplicate the findings. This helps when reviewing run reports, or comparing reports in Branch Review. + +You may have attributes already in place in your application that would help with element organization, such as `data-component-name`. If you would like Cypress to use and prioritize these attributes, or you want to change the default priority order, you can define your own list of significant attributes. ## Scope @@ -16,40 +16,25 @@ supported, if you need to split them up. ## Syntax +`significantAttributes` is an array of strings, with each string being the name of a HTML attribute. + ```json { "significantAttributes": [ - { - "selector": string, - "attributes": string[] - } + string ] } ``` -### Options - -The first `significantAttributes` rule for which the selector property matches the element is used to determine which attributes should be considered significant. Attributes that do not match any rules are not considered significant by default. - -| Option | Required | Default | Description | -| ------------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `selector` | Required | | A CSS selector to identify elements. Supports standard CSS selector syntax, including IDs, classes, attributes, and combinators. | -| `attributes` | Required | | An array of attribute names that should be considered significant for coverage analysis. | - ## Examples -### Marking specific attributes as significant for all elements +### Marking specific attributes as significant #### Config ```json { - "significantAttributes": [ - { - "selector": "*", - "attributes": ["class", "id", "role"] - } - ] + "significantAttributes": ["class", "id", "data-context"] } ``` @@ -57,7 +42,7 @@ The first `significantAttributes` rule for which the selector property matches t ```xml - @@ -66,73 +51,5 @@ The first `significantAttributes` rule for which the selector property matches t #### Significant attributes tracked ``` -class="primary", id="submit", role="button" -``` - ---- - -### Marking different attributes as significant for different elements - -#### Config - -```json -{ - "significantAttributes": [ - { - "selector": "input", - "attributes": ["type", "name", "required"] - }, - { - "selector": "button", - "attributes": ["type", "disabled"] - } - ] -} -``` - -#### HTML - -```xml - - - - -``` - -#### Significant attributes tracked - -``` -input: type="text", name="username", required="required" -button: type="submit", disabled="disabled" -``` - -### Using attribute patterns - -#### Config - -```json -{ - "significantAttributes": [ - { - "selector": "*", - "attributes": ["aria-*"] - } - ] -} -``` - -#### HTML - -```xml - -
- Content -
- -``` - -#### Significant attributes tracked - -``` -aria-label="Main content", aria-hidden="false" +class="primary", id="submit", data-context="user-signup" ``` diff --git a/docs/ui-coverage/configuration/significantattributes.mdx b/docs/ui-coverage/configuration/significantattributes.mdx index 9518e13cf2..c68fe732bd 100644 --- a/docs/ui-coverage/configuration/significantattributes.mdx +++ b/docs/ui-coverage/configuration/significantattributes.mdx @@ -9,4 +9,6 @@ sidebar_position: 50 # significantAttributes +The `significantAttributes` property allows you to specify which attributes should be considered significant when identifying elements in UI Coverage. + diff --git a/docs/ui-coverage/core-concepts/interactivity.mdx b/docs/ui-coverage/core-concepts/interactivity.mdx index 48216f1607..fae843af63 100644 --- a/docs/ui-coverage/core-concepts/interactivity.mdx +++ b/docs/ui-coverage/core-concepts/interactivity.mdx @@ -19,6 +19,16 @@ UI Coverage determines interactivity based on a combination of HTML semantics, [ These elements are tracked for interaction to provide actionable insights into test coverage. +### Customizing interactive elements + +Custom interactive elements that do not meet the criteria above can also be declared with a `data-cy-ui-interactive="include"` attribute, used as follows: + +```html +
Custom interactive widget
+``` + +It most cases we recommend **not** using this override, and instead updating the HTML to be something the browser would already consider to be interactive. This will likely produce better overall behavior, including for accessibility purposes. `data-cy-ui-interactive` is a fallback for situations where that may not be possible. + ## Interaction Commands Interactive elements are marked as "tested" when they are interacted with using specific Cypress commands. These include: @@ -39,7 +49,13 @@ Interactive elements are marked as "tested" when they are interacted with using - `type` - `uncheck` -By ensuring these commands interact with the appropriate elements, UI Coverage accurately reflects your test coverage. +By ensuring that at least one of these commands is used on every interactive element, UI Coverage accurately reflects your test coverage. + +### Customizing interaction commands + +Configuration is available to support adding [additional interaction commands](/ui-coverage/configuration/additionalinteractioncommands), such as custom commands or ones from third-party libraries, to count towards UI Coverage scores. + +It is also possible to adjust the [allowed commands](/ui-coverage/configuration/allowedinteractioncommands) for specific elements, to restrict or expand the commands that are accepted as coverage for specific elements. ## Untested Links