UI CoveragePremium Solution

allowedInteractionCommands

UI Coverage tracks all interaction commands by default for comprehensive coverage reporting. The allowedInteractionCommands configuration allows you to limit which interaction commands are tracked for specific elements by defining rules based on CSS selectors.

This is particularly useful for filtering out irrelevant interactions or focusing coverage tracking on specific interaction patterns for different types of elements.

Why use allowedInteractionCommands?

• Focused tracking: Limit coverage tracking to relevant interaction types for specific elements or components to reduce noise in reports.
• Component-specific rules: Apply different interaction tracking rules based on element types or component categories. For example, you may require specific kinds of interactions on complex data-visualization components that are not required in regular interactive elements.

Syntax

{
  "uiCoverage": {
    "allowedInteractionCommands": [
      {
        "selector": string,
        "commands": [string],
        "documentScope": [string],
        "comment": string
      }
    ]
  }
}

Options

The allowedInteractionCommands property accepts an array of objects, where each object defines a rule for limiting interaction commands for elements matching a specific selector.

Option	Required	Default	Description
selector	Required		A CSS selector to identify elements. Supports standard CSS selector syntax, including IDs, classes, attributes, and combinators.
commands	Required		An array of command names (strings) that should be tracked as interactions for elements matching the selector. All other interaction commands will be ignored for these elements.
documentScope	Optional		An array of CSS selectors that identify document hosts (iframes or shadow DOM hosts) that must be ancestors of the matched element. The selector will only match if all specified document hosts are found in the element's ancestor chain.
comment	Optional		A comment describing the purpose of this allowed interaction commands configuration.

Examples

Limiting button interactions to clicks only

Config

{
  "uiCoverage": {
    "allowedInteractionCommands": [
      {
        "selector": "button, [role='button']",
        "commands": ["click", "realClick"]
      }
    ]
  }
}

Usage in tests

// Only click and realClick will be tracked for buttons
cy.get('[data-cy="submit-button"]').click() // ✓ Tracked
cy.get('[data-cy="submit-button"]').realClick() // ✓ Tracked
cy.get('[data-cy="submit-button"]').hover() // ✗ Not tracked
cy.get('[data-cy="submit-button"]').focus() // ✗ Not tracked

Different rules for form elements

Config

{
  "uiCoverage": {
    "allowedInteractionCommands": [
      {
        "selector": "input[type='text'], textarea",
        "commands": ["type", "clear", "realType"]
      },
      {
        "selector": "select",
        "commands": ["select", "click"]
      },
      {
        "selector": "input[type='checkbox'], input[type='radio']",
        "commands": ["check", "uncheck", "click"]
      }
    ]
  }
}

Usage in tests

// Text inputs: only type, clear, and realType are tracked
cy.get('[data-cy="username"]').type('john_doe') // ✓ Tracked
cy.get('[data-cy="username"]').clear() // ✓ Tracked
cy.get('[data-cy="username"]').focus() // ✗ Not tracked

// Select elements: only select and click are tracked
cy.get('[data-cy="country"]').select('US') // ✓ Tracked
cy.get('[data-cy="country"]').click() // ✓ Tracked
cy.get('[data-cy="country"]').hover() // ✗ Not tracked

// Checkboxes/Radio buttons: check, uncheck, and click are tracked
cy.get('[data-cy="agree-terms"]').check() // ✓ Tracked
cy.get('[data-cy="agree-terms"]').click() // ✓ Tracked

Excluding hover interactions for mobile components

Config

{
  "uiCoverage": {
    "allowedInteractionCommands": [
      {
        "selector": "[data-mobile='true']",
        "commands": ["click", "tap", "swipe", "type"]
      }
    ]
  }
}

Usage in tests

// Mobile components: hover interactions are excluded
cy.get('[data-mobile="true"][data-cy="menu-item"]').click() // ✓ Tracked
cy.get('[data-mobile="true"][data-cy="menu-item"]').tap() // ✓ Tracked
cy.get('[data-mobile="true"][data-cy="menu-item"]').hover() // ✗ Not tracked

Allowing assertions as interactions

Note that because allowedInteractionCommands replaces the allowed interactions, if you add assert as an interaction, remember to also add any other acceptable interactions to the list.

Config

{
  "uiCoverage": {
    "allowedInteractionCommands": [
      {
        "selector": "button[data-no-explicit-interaction='true']",
        "commands": ["assert"]
      }
    ]
  }
}

Usage in tests

// Any assertions on matching elements are tracked
cy.get('button[data-no-explicit-interaction="true"]').should('exist) // ✓ Tracked
cy.get('button[data-no-explicit-interaction="true"]').should('be.visible) // ✓ Tracked
cy.get('button[data-no-explicit-interaction="true"]').click() // ✗ Not tracked

Scoping interaction commands to shadow DOM

When you need to limit interaction commands for elements within a specific shadow DOM host, use the documentScope property to scope your selector to that document context.

Config

{
  "uiCoverage": {
    "allowedInteractionCommands": [
      {
        "selector": "button",
        "commands": ["click"],
        "documentScope": ["custom-component"]
      }
    ]
  }
}

HTML

<body>
  <button id="root-button">Root Button</button>
  <custom-component>
    #shadow-dom
      <button id="shadow-button">Shadow Button</button>
  </custom-component>
</body>

Usage in tests

// Root button: all interactions tracked (default behavior)
cy.get('#root-button').click() // ✓ Tracked
cy.get('#root-button').hover() // ✓ Tracked

// Shadow DOM button: only click tracked
cy.get('custom-component').shadow().find('#shadow-button').click() // ✓ Tracked
cy.get('custom-component').shadow().find('#shadow-button').hover() // ✗ Not tracked

---

Scoping interaction commands to iframes

You can also scope interaction command rules to elements within specific iframes using documentScope.

Config

{
  "uiCoverage": {
    "allowedInteractionCommands": [
      {
        "selector": "input",
        "commands": ["type", "clear"],
        "documentScope": ["#embedded-form"]
      }
    ]
  }
}

HTML

<body>
  <input id="root-input" />
  <iframe id="embedded-form" src="http://www.foo.com">
    <html>
      <body>
        <input id="embedded-input" />
      </body>
    </html>
  </iframe>
</body>

Usage in tests

// Root input: all interactions tracked (default behavior)
cy.get('#root-input').type('text') // ✓ Tracked
cy.get('#root-input').focus() // ✓ Tracked

// Embedded input: only type and clear tracked
cy.get('#embedded-form').then(($iframe) => {
  cy.wrap($iframe.contents().find('#embedded-input')).type('text') // ✓ Tracked
  cy.wrap($iframe.contents().find('#embedded-input')).focus() // ✗ Not tracked
})

Notes

• Elements that don't match any selector will have all interaction commands tracked (default behavior).
• If an element matches multiple selectors, commands from all matching rules will be allowed. A high degree of specificity for these selectors is recommended.
• Command names are case-sensitive and must match exactly as they appear in your test code.
• This configuration works separately from additionalInteractionCommands. Custom commands do not need to be globally defined as additionalInteractionCommands in order to be declared here.