cypress-shadow-dom

Extend Cypress commands with shadow DOM support

This package adds a custom Cypress command that allows you to make an abstraction on how exactly you upload files through you HTML controls and focus on testing the functionality.

Table of Contents

• Installation
• Usage
• API
  • shadowGet
  • shadowFind
  • shadowEq
  • shadowFirst
  • shadowLast
  • shadowContains
  • shadowTrigger
  • shadowClick
  • shadowType
• Contributors
• License

Installation

The package is distributed via npm should be installed as one of your project's devDependencies:

npm install --save-dev cypress-shadow-dom

Usage

cypress-shadow-dom extends Cypress' cy command. Add this line to your project's cypress/support/commands.js:

import 'cypress-shadow-dom';

Here is a basic example:

cy.shadowGet('todo-list')
  .shadowFind('todo-list-item')
  .its('length')
  .should('eq', 4);

See more usage guidelines in example. It also contains all the available commands in their natural use case.

API

Here's a set of available commands:

shadowGet

Querying shadow DOM elements is made with:

cy.shadowGet(selector);

• {String} selector – a single selector which usually represents root shadow DOM elements you want to start with

This command returns shadowSubject that is a valid subject to execute any command below.

shadowFind

Additional querying within found shadow DOM elements:

shadowSubject.shadowFind(selector);

• {String} selector – a single selector which helps to get nested shadow DOM element under the root element

Example:

cy.shadowGet('todo-list').shadowFind('todo-form');

This command returns shadowSubject that is a valid subject to execute any command below.

shadowEq

To take the nth element from found shadow DOM collection:

shadowSubject.shadowEq(index);

• {Number} index – a positive or negative number within given collection range

shadowFirst

To take the first element from found shadow DOM collection:

shadowSubject.shadowFirst();

shadowLast

To take the last element from found shadow DOM collection:

shadowSubject.shadowLast();

shadowContains

To validate some element's text content:

shadowSubject.shadowContains(content);

• {String} content – a string containing any text for lookup

shadowTrigger

To trigger any event:

shadowSubject.shadowTrigger(eventName, eventOptions);

• {String} eventName – a string containing any text for lookup
• {Object?} eventOptions contains:
  • {Boolean?} log
  • {Boolean?} force
  • {Boolean?} bubbles
  • {Boolean?} cancelable
  • {Number?} timeout
  • {Boolean?} composed

shadowClick

A shorthand to trigger a click event:

shadowSubject.shadowClick(eventOptions);

• {Object?} eventOptions contains:
  • {Boolean?} log
  • {Boolean?} force
  • {Boolean?} bubbles
  • {Boolean?} cancelable
  • {Number?} timeout
  • {Boolean?} composed

shadowType

Types some text content inside given shadow DOM input control:

shadowSubject.shadowType(content);

• {String} content – a string containing any text

Contributors

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!

License

MIT