{ "doc": { "id": "ui-coverage/configuration/additionalinteractioncommands", "title": "additionalInteractionCommands: count custom commands as coverage in UI Coverage", "description": "Make Cypress UI Coverage count your custom Cypress commands and third-party commands, such as cypress-real-events realClick and realType, as interactions so the elements they touch are marked as tested.", "section": "ui-coverage", "source_path": "/llm/markdown/ui-coverage/configuration/additionalinteractioncommands.md", "version": "29f95bf8bb06f320986f3749f5bf09a35a409eab", "updated_at": "2026-09-04T10:49:54.630Z", "headings": [ { "id": "ui-coverage/configuration/additionalinteractioncommands#track-custom-commands-additionalinteractioncommands", "text": "Track custom commands - additionalInteractionCommands", "level": 1 }, { "id": "ui-coverage/configuration/additionalinteractioncommands#why-use-additionalinteractioncommands", "text": "Why use additionalInteractionCommands?", "level": 2 }, { "id": "ui-coverage/configuration/additionalinteractioncommands#scope", "text": "Scope", "level": 2 }, { "id": "ui-coverage/configuration/additionalinteractioncommands#setting-additionalinteractioncommands", "text": "Setting additionalInteractionCommands", "level": 2 }, { "id": "ui-coverage/configuration/additionalinteractioncommands#syntax", "text": "Syntax", "level": 2 }, { "id": "ui-coverage/configuration/additionalinteractioncommands#validation-rules", "text": "Validation rules", "level": 3 }, { "id": "ui-coverage/configuration/additionalinteractioncommands#how-additional-interaction-commands-are-applied", "text": "How additional interaction commands are applied", "level": 2 }, { "id": "ui-coverage/configuration/additionalinteractioncommands#requirements-for-a-custom-command", "text": "Requirements for a custom command", "level": 3 }, { "id": "ui-coverage/configuration/additionalinteractioncommands#relationship-to-allowedinteractioncommands", "text": "Relationship to allowedInteractionCommands", "level": 3 }, { "id": "ui-coverage/configuration/additionalinteractioncommands#examples", "text": "Examples", "level": 2 }, { "id": "ui-coverage/configuration/additionalinteractioncommands#track-cypress-real-events-commands", "text": "Track cypress-real-events commands", "level": 3 }, { "id": "ui-coverage/configuration/additionalinteractioncommands#config", "text": "Config", "level": 4 }, { "id": "ui-coverage/configuration/additionalinteractioncommands#usage-in-tests", "text": "Usage in tests", "level": 4 }, { "id": "ui-coverage/configuration/additionalinteractioncommands#track-your-own-custom-commands", "text": "Track your own custom commands", "level": 3 }, { "id": "ui-coverage/configuration/additionalinteractioncommands#config", "text": "Config", "level": 4 }, { "id": "ui-coverage/configuration/additionalinteractioncommands#usage-in-tests", "text": "Usage in tests", "level": 4 }, { "id": "ui-coverage/configuration/additionalinteractioncommands#see-also", "text": "See also", "level": 2 } ] }, "content": { "type": "root", "children": [ { "type": "heading", "depth": 1, "children": [ { "type": "text", "value": "Track custom commands - `additionalInteractionCommands`" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "The `additionalInteractionCommands` configuration tells UI Coverage that your own Cypress commands, or commands from a third-party plugin, count as interactions. Commands you list are added to the built-in set, so the elements they touch are marked as tested and contribute to your coverage score." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "UI Coverage marks an " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/core-concepts/interactivity.md", "children": [ { "type": "text", "value": "interactive element" } ] }, { "type": "text", "value": " as tested when a recognized " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/core-concepts/interactivity.md#Interaction-Commands", "children": [ { "type": "text", "value": "interaction command" } ] }, { "type": "text", "value": " targets it. Out of the box it recognizes a fixed set of built-in Cypress commands such as `click`, `type`, and `check`. A command it doesn't recognize doesn't count, so an element that your tests only ever exercise through a custom command like `selectDate()`, or a third-party command like " }, { "type": "link", "title": null, "url": "#Track-cypress-real-events-commands", "children": [ { "type": "text", "value": "`cypress-real-events`" } ] }, { "type": "text", "value": "' `realClick()`, is reported as untested even though your suite interacts with it on every run. Listing those command names in `additionalInteractionCommands` closes that gap, so your coverage score reflects what your tests actually do." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Why use additionalInteractionCommands?" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Get credit for custom commands: If your team wraps interactions in " }, { "type": "link", "title": null, "url": "/llm/markdown/api/cypress-api/custom-commands.md", "children": [ { "type": "text", "value": "custom commands" } ] }, { "type": "text", "value": ", such as a `login()` helper that types and clicks, list them so the elements they touch count as tested." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Support third-party interaction plugins: Plugins like " }, { "type": "link", "title": null, "url": "#Track-cypress-real-events-commands", "children": [ { "type": "text", "value": "`cypress-real-events`" } ] }, { "type": "text", "value": " add commands (`realClick`, `realType`, `realHover`) that fire native browser events. These aren't built-in Cypress commands, so UI Coverage doesn't recognize them until you list them." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Keep your score accurate: Every command your tests rely on that UI Coverage doesn't recognize leaves real coverage unreported. Declaring them removes false gaps from your reports." } ] } ] } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Scope" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Note: `additionalInteractionCommands` applies to UI Coverage only and must be nested under the `uiCoverage` key. Unlike properties such as `significantAttributes`, it has no root-level or Cypress Accessibility equivalent, so it never affects Accessibility reports." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Setting additionalInteractionCommands" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "To add or edit `additionalInteractionCommands`, open the App Quality tab in your project settings in Cypress Cloud. See " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/overview.md#Setting-configuration", "children": [ { "type": "text", "value": "Setting configuration" } ] }, { "type": "text", "value": " for details, including how to regenerate past reports with a new configuration without rerunning your tests." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Syntax" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "App Quality Config" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{\n \"uiCoverage\": {\n \"additionalInteractionCommands\": [string]\n }\n}" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Each entry is the name of a Cypress command, such as `\"realClick\"` or `\"selectDate\"`, written exactly as it appears in your test code. Entries are command names only: not CSS selectors and not the `cy.` prefix. The property is optional and defaults to an empty list, so the " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/core-concepts/interactivity.md#Interaction-Commands", "children": [ { "type": "text", "value": "built-in interaction commands" } ] }, { "type": "text", "value": " always apply on their own." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Validation rules" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Cypress Cloud rejects a configuration when the same command name appears twice in the list, or when an entry isn't a plain string." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "How additional interaction commands are applied" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "A command you list here counts as an interaction only when it logs a " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/core-concepts/element-identification.md#Snapshots", "children": [ { "type": "text", "value": "snapshot" } ] }, { "type": "text", "value": " that highlights the element it acts on. UI Coverage reads that snapshot to know which element the interaction belongs to, so a command with no subject-referencing snapshot is ignored even when its name is listed. Built-in commands log this snapshot automatically; a custom command must do it explicitly (see " }, { "type": "link", "title": null, "url": "#Requirements-for-a-custom-command", "children": [ { "type": "text", "value": "Requirements for a custom command" } ] }, { "type": "text", "value": ")." } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Keep these behaviors in mind:" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Your list is added to the defaults, not a replacement for them. The built-in commands keep counting; you're extending the set, not overriding it. To limit which commands count for specific elements, use " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/allowedinteractioncommands.md", "children": [ { "type": "text", "value": "`allowedInteractionCommands`" } ] }, { "type": "text", "value": "." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Listing a built-in command has no effect. The " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/core-concepts/interactivity.md#Interaction-Commands", "children": [ { "type": "text", "value": "built-in interaction commands" } ] }, { "type": "text", "value": " already count on their own. `additionalInteractionCommands` is only for names UI Coverage doesn't already recognize." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Overwriting a built-in command keeps its name. UI Coverage matches on the name a command logs under, so a built-in interaction command customized with " }, { "type": "link", "title": null, "url": "/llm/markdown/api/cypress-api/custom-commands.md#Overwrite-Existing-Commands", "children": [ { "type": "text", "value": "`Cypress.Commands.overwrite`" } ] }, { "type": "text", "value": " stays recognized automatically under its original name, without being listed here, as long as your version still logs a snapshot referencing the subject. Only a brand-new command name added with `Cypress.Commands.add` needs to be listed." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Custom command names are matched case-sensitively. `\"realClick\"` matches `realClick` but not `realclick`. Copy the name exactly as you registered it with `Cypress.Commands.add`." } ] } ] } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Requirements for a custom command" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Listing a command name isn't enough on its own. For UI Coverage to credit the interaction to an element, the custom command must give it an element to credit, by logging a snapshot that references the subject element. In practice that means the command should:" } ] }, { "type": "list", "ordered": true, "start": 1, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Receive the element as its subject, by registering with " }, { "type": "link", "title": null, "url": "/llm/markdown/api/cypress-api/custom-commands.md#Arguments", "children": [ { "type": "text", "value": "`prevSubject`" } ] }, { "type": "text", "value": "." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Log the interaction against that element with " }, { "type": "link", "title": null, "url": "/llm/markdown/api/cypress-api/cypress-log.md", "children": [ { "type": "text", "value": "`Cypress.log`" } ] }, { "type": "text", "value": ", passing the subject as `$el`." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "Capture at least one snapshot on that log entry." } ] } ] } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "JavaScript" } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "text", "value": "TypeScript" } ] } ] } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "cypress/support/commands.js" } ] }, { "type": "code", "lang": null, "meta": null, "value": "// A custom command that UI Coverage can track\nCypress.Commands.add(\n 'selectDate',\n { prevSubject: ['element'] },\n (subject, date) => {\n const log = Cypress.log({ $el: subject, message: date, autoEnd: false })\n\n log.snapshot('before')\n // ...interact with the element to pick the date...\n\n return cy.wrap(subject, { log: false }).then(() => {\n log.snapshot('after').end()\n })\n }\n)" }, { "type": "paragraph", "children": [ { "type": "text", "value": "cypress/support/commands.ts" } ] }, { "type": "code", "lang": null, "meta": null, "value": "// A custom command that UI Coverage can track\nCypress.Commands.add(\n 'selectDate',\n { prevSubject: ['element'] },\n (subject: JQuery, date: string) => {\n const log = Cypress.log({ $el: subject, message: date, autoEnd: false })\n\n log.snapshot('before')\n // ...interact with the element to pick the date...\n\n return cy.wrap(subject, { log: false }).then(() => {\n log.snapshot('after').end()\n })\n }\n)" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Beyond letting UI Coverage credit the interaction, logging a snapshot that references the subject is what renders element highlights for the command in Cypress open mode and " }, { "type": "link", "title": null, "url": "/llm/markdown/cloud/features/test-replay.md", "children": [ { "type": "text", "value": "Test Replay" } ] }, { "type": "text", "value": ". See " }, { "type": "link", "title": null, "url": "/llm/markdown/api/cypress-api/custom-commands.md", "children": [ { "type": "text", "value": "Custom Commands" } ] }, { "type": "text", "value": " for the full API." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Relationship to allowedInteractionCommands" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "Any command name you list in " }, { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/allowedinteractioncommands.md", "children": [ { "type": "text", "value": "`allowedInteractionCommands`" } ] }, { "type": "text", "value": " is automatically recognized as an interaction command as well. You don't need to declare the same custom command in both places: use `additionalInteractionCommands` to count a command everywhere it's used, and `allowedInteractionCommands` when a command should count only for elements matching a specific selector." } ] }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "Examples" } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Track `cypress-real-events` commands" } ] }, { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "https://github.com/dmtrKovalenko/cypress-real-events", "children": [ { "type": "text", "value": "`cypress-real-events`" } ] }, { "type": "text", "value": " fires native browser events through commands like `realClick`, `realType`, and `realHover`. Because these aren't built-in Cypress commands, UI Coverage doesn't count them until you list them." } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Config" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "App Quality Config" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{\n \"uiCoverage\": {\n \"additionalInteractionCommands\": [\"realClick\", \"realType\", \"realHover\"]\n }\n}" }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Usage in tests" } ] }, { "type": "code", "lang": null, "meta": null, "value": "// Now these commands mark their target elements as tested\ncy.get('[data-cy=\"button\"]').realClick()\ncy.get('[data-cy=\"input\"]').realType('Hello World')\ncy.get('[data-cy=\"tooltip-trigger\"]').realHover()" }, { "type": "paragraph", "children": [ { "type": "text", "value": "Any plugin that adds commands acting on an element works the same way. `cypress-real-events` also provides `realPress`, `realSwipe`, and `realMouseDown`; other common examples are `drag` and `move` from " }, { "type": "link", "title": null, "url": "https://www.npmjs.com/package/@4tw/cypress-drag-drop", "children": [ { "type": "text", "value": "`@4tw/cypress-drag-drop`" } ] }, { "type": "text", "value": " and `tab` from " }, { "type": "link", "title": null, "url": "https://www.npmjs.com/package/cypress-plugin-tab", "children": [ { "type": "text", "value": "`cypress-plugin-tab`" } ] }, { "type": "text", "value": ". Whichever plugin you use, the command counts only if it meets the " }, { "type": "link", "title": null, "url": "#How-additional-interaction-commands-are-applied", "children": [ { "type": "text", "value": "requirement above" } ] }, { "type": "text", "value": ": it must log a snapshot that references the element it acts on." } ] }, { "type": "heading", "depth": 3, "children": [ { "type": "text", "value": "Track your own custom commands" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "List the custom commands your team defines with `Cypress.Commands.add`. Make sure each one meets the " }, { "type": "link", "title": null, "url": "#Requirements-for-a-custom-command", "children": [ { "type": "text", "value": "requirements for a custom command" } ] }, { "type": "text", "value": " so UI Coverage can credit the interaction to an element." } ] }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Config" } ] }, { "type": "paragraph", "children": [ { "type": "text", "value": "App Quality Config" } ] }, { "type": "code", "lang": null, "meta": null, "value": "{\n \"uiCoverage\": {\n \"additionalInteractionCommands\": [\"selectDate\", \"dragAndDrop\"]\n }\n}" }, { "type": "heading", "depth": 4, "children": [ { "type": "text", "value": "Usage in tests" } ] }, { "type": "code", "lang": null, "meta": null, "value": "// Custom commands that log a snapshot referencing their subject element\ncy.get('[data-testid=\"due-date\"]').selectDate('2026-01-01')\ncy.get('[data-testid=\"card\"]').dragAndDrop('[data-testid=\"done-column\"]')" }, { "type": "heading", "depth": 2, "children": [ { "type": "text", "value": "See also" } ] }, { "type": "list", "ordered": false, "start": null, "spread": false, "children": [ { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/core-concepts/interactivity.md", "children": [ { "type": "text", "value": "Interactivity" } ] }, { "type": "text", "value": ": how UI Coverage detects interactive elements and which commands count as interactions." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/allowedinteractioncommands.md", "children": [ { "type": "text", "value": "`allowedInteractionCommands`" } ] }, { "type": "text", "value": ": limit which interaction commands count for specific elements." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/api/cypress-api/custom-commands.md", "children": [ { "type": "text", "value": "Custom Commands" } ] }, { "type": "text", "value": ": create custom commands and overwrite built-in ones." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/configuration/overview.md", "children": [ { "type": "text", "value": "Configuration overview" } ] }, { "type": "text", "value": ": where to set configuration and regenerate reports." } ] } ] }, { "type": "listItem", "spread": false, "checked": null, "children": [ { "type": "paragraph", "children": [ { "type": "link", "title": null, "url": "/llm/markdown/ui-coverage/faq.md", "children": [ { "type": "text", "value": "UI Coverage FAQ" } ] }, { "type": "text", "value": ": common questions and troubleshooting." } ] } ] } ] } ] }, "token_estimate": 1584 }