(deprecated) 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.

Project reached its dead end because of [recent feature introduced by @43081j]https://github.com/cypress-io/cypress/pull/7469.

Please consider using this experimental built-in feature as well as submitting issues and code contributions there.

Warmest thanks for all the contributors that helped this project evolve!

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, options);

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

• {Object?} options – (optional) contains following properties:

  • {Number?} timeout – (optional) time, in milliseconds, to wait until most DOM based commands are considered timed out (defaults to 4000)

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, options);

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

• {Object?} options – (optional) contains following properties:

  • {Number?} timeout – (optional) time, in milliseconds, to wait until most DOM based commands are considered timed out (defaults to 4000)

Example:

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

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

In order to set a custom timeout for dynamically loaded elements that appear later than 4 seconds after render, use custom timeout:

cy.shadowGet('todo-list').shadowFind('todo-form', { timeout: 8500 });

shadowEq

To take the nth element from found shadow DOM collection:

shadowSubject.shadowEq(index, options);

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

• {Object?} options – (optional) contains following properties:

  • {Number?} timeout – (optional) time, in milliseconds, to wait until most DOM based commands are considered timed out (defaults to 4000)

shadowFirst

To take the first element from found shadow DOM collection:

shadowSubject.shadowFirst(options);

• {Object?} options – (optional) contains following properties:

  • {Number?} timeout – (optional) time, in milliseconds, to wait until most DOM based commands are considered timed out (defaults to 4000)

So, simply:

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

shadowLast

To take the last element from found shadow DOM collection:

shadowSubject.shadowLast(options);

• {Object?} options – (optional) contains following properties:

  • {Number?} timeout – (optional) time, in milliseconds, to wait until most DOM based commands are considered timed out (defaults to 4000)

shadowContains

To validate some element's text content:

shadowSubject.shadowContains(content, options);

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

• {Object?} options – (optional) contains following properties:

  • {Number?} timeout – (optional) time, in milliseconds, to wait until most DOM based commands are considered timed out (defaults to 4000)

shadowTrigger

To trigger any event:

shadowSubject.shadowTrigger(eventName, options);

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

• {Object?} options – (optional) contains following properties:

  • {Boolean?} force
  • {Boolean?} bubbles
  • {Boolean?} cancelable
  • {Boolean?} composed

shadowClick

A shorthand to trigger a click event:

shadowSubject.shadowClick(options);

• {Object?} options – (optional) contains following properties:

  • {Boolean?} force
  • {Boolean?} bubbles
  • {Boolean?} cancelable
  • {Boolean?} composed

shadowType

Types some text content inside given shadow DOM input control:

shadowSubject.shadowType(content, options);

• {String} content – a string containing any text

• {Object?} options – (optional) contains following properties:

  • {Number?} delay – (optional) time, in milliseconds, between adding each letter/char (defaults to 10)

Contributors

Thanks goes to these wonderful people (emoji key):

tst 🐛

Joshua de Lange 🐛

Lucas Schnüriger 💻

Milan Andric 📖 🤔

Ryan Wheale 🤔 💻

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

License

MIT