Shadow DOM access in Cypress - Framework Patterns

Framework Mode - Shadow DOM access

Folder Structure for Cypress Shadow DOM Testing

cypress/
├── e2e/
│   ├── shadowDomTests.cy.js      # Test files accessing Shadow DOM
│   └── otherTests.cy.js
├── support/
│   ├── commands.js               # Custom commands including Shadow DOM helpers
│   └── e2e.js                   # Global support file
├── fixtures/
│   └── testData.json             # Test data for data-driven tests
cypress.config.js                 # Cypress configuration file

Test Framework Layers for Shadow DOM Access in Cypress

• Test Layer: Contains test scripts in cypress/e2e that use Cypress commands to interact with Shadow DOM elements.
• Custom Commands Layer: Located in cypress/support/commands.js, includes reusable commands like shadowGet() to simplify Shadow DOM element selection.
• Fixtures Layer: Holds test data files in cypress/fixtures for consistent test inputs.
• Configuration Layer: The cypress.config.js file manages environment settings, base URLs, and experimental features like Shadow DOM support.

Configuration Patterns for Shadow DOM Testing in Cypress

• Enable Experimental Shadow DOM Support: In cypress.config.js, set experimentalShadowDomSupport: true to allow Cypress to pierce Shadow DOM.
• Environment Variables: Use env in config to store URLs, credentials, or flags to toggle Shadow DOM tests.
• Custom Command Setup: Define commands like shadowGet in cypress/support/commands.js to encapsulate Shadow DOM querying logic.
• Base URL: Configure baseUrl for easy test environment switching.

// cypress.config.js example snippet
import { defineConfig } from 'cypress'

export default defineConfig({
  e2e: {
    baseUrl: 'https://example.com',
    experimentalShadowDomSupport: true,
    env: {
      login_user: 'testuser',
      login_pass: 'password123'
    }
  }
})

Test Reporting and CI/CD Integration

• Built-in Cypress Reporter: Cypress provides clear pass/fail results in the Test Runner UI and CLI output.
• Mocha Reporter Integration: Use Mocha reporters like spec or junit for detailed reports consumable by CI tools.
• CI/CD Pipelines: Integrate Cypress tests in pipelines (GitHub Actions, Jenkins, GitLab CI) to run Shadow DOM tests automatically on code changes.
• Artifacts: Save screenshots and videos on test failures for debugging Shadow DOM interaction issues.

Best Practices for Shadow DOM Access in Cypress Framework

1. Use Custom Commands: Encapsulate Shadow DOM selectors in custom commands to keep tests clean and reusable.
2. Enable Experimental Shadow DOM Support: Always enable experimentalShadowDomSupport in config for reliable Shadow DOM interaction.
3. Prefer Data Attributes: Use stable data-cy or similar attributes inside Shadow DOM for selectors to avoid brittle tests.
4. Explicit Assertions: Assert visibility and content inside Shadow DOM elements to ensure correct rendering.
5. Isolate Shadow DOM Tests: Group Shadow DOM tests separately for easier maintenance and debugging.

Self-Check Question

Where would you add a new custom command to simplify selecting elements inside Shadow DOM in this Cypress framework structure?

Key Result

Use custom commands and enable experimentalShadowDomSupport in Cypress config to reliably test Shadow DOM elements.

Practice

1. What is the correct way to access an element inside a Shadow DOM using Cypress?

easy

A. Use cy.get('selector').shadow().find('inner-selector')

B. Use cy.get('selector').find('inner-selector') directly

C. Use cy.shadow('selector').get('inner-selector')

D. Use cy.getShadow('selector').find('inner-selector')

Solution

1. Step 1: Understand Shadow DOM access in Cypress

   Cypress requires the shadow() command to enter the Shadow DOM context before finding elements inside it.

2. Step 2: Use the correct chaining method

   The correct syntax is cy.get('selector').shadow().find('inner-selector') to access elements inside Shadow DOM.

3. Final Answer:

   Use cy.get('selector').shadow().find('inner-selector') -> Option A

4. Quick Check:

   Shadow DOM access = cy.get().shadow().find() [OK]

Hint: Always use .shadow() before .find() for Shadow DOM elements [OK]

Common Mistakes:

• Trying to find elements inside Shadow DOM without .shadow()
• Using non-existent commands like cy.shadow() or cy.getShadow()
• Assuming .find() works directly on Shadow DOM host

2. Which of the following Cypress commands correctly accesses a button with id submitBtn inside a Shadow DOM hosted by my-component?

easy

A. cy.get('my-component').find('#submitBtn')

B. cy.get('my-component').shadow().find('#submitBtn')

C. cy.shadow('my-component').get('#submitBtn')

D. cy.getShadow('my-component').find('#submitBtn')

Solution

1. Step 1: Identify the Shadow DOM host

   The element my-component is the Shadow DOM host, so we start with cy.get('my-component').

2. Step 2: Access the Shadow DOM and find the button

   We must use .shadow() to enter the Shadow DOM, then .find('#submitBtn') to locate the button inside.

3. Final Answer:

   cy.get('my-component').shadow().find('#submitBtn') -> Option B

4. Quick Check:

   Shadow DOM host + .shadow() + .find() = cy.get('my-component').shadow().find('#submitBtn') [OK]

Hint: Use .shadow() after host selector before .find() [OK]

Common Mistakes:

• Skipping .shadow() and using .find() directly
• Using non-existent commands like cy.shadow()
• Confusing host selector with inner element selector

3. Given the following Cypress code, what will be the result of the assertion?

cy.get('custom-element').shadow().find('.title').should('have.text', 'Welcome')

medium

A. The test throws a syntax error due to incorrect chaining.

B. The test fails because .shadow() cannot be chained after .get().

C. The test passes if the element with class 'title' inside the Shadow DOM has text 'Welcome'.

D. The test passes if any element with class 'title' on the page has text 'Welcome'.

Solution

1. Step 1: Understand the command chain

   The code correctly gets the Shadow DOM host custom-element, enters its Shadow DOM with .shadow(), then finds the element with class title.

2. Step 2: Evaluate the assertion

   The assertion checks if the found element's text is exactly 'Welcome'. If true, the test passes; otherwise, it fails.

3. Final Answer:

   The test passes if the element with class 'title' inside the Shadow DOM has text 'Welcome'. -> Option C

4. Quick Check:

   Correct chaining + assertion = The test passes if the element with class 'title' inside the Shadow DOM has text 'Welcome'. [OK]

Hint: Correct .shadow() chaining accesses Shadow DOM elements properly [OK]

Common Mistakes:

• Assuming .shadow() is invalid after .get()
• Confusing global elements with Shadow DOM elements
• Misunderstanding assertion target scope

4. You wrote this Cypress test but it fails to find the button inside Shadow DOM:

cy.get('widget-component').find('button.submit').click()

What is the most likely reason?

medium

A. You forgot to use .shadow() before .find() to access Shadow DOM.

B. The selector 'widget-component' is incorrect.

C. The button does not have class 'submit'.

D. Cypress cannot click buttons inside Shadow DOM.

Solution

1. Step 1: Analyze the command chain

   The code tries to find a button inside widget-component without entering Shadow DOM.

2. Step 2: Identify missing Shadow DOM access

   To access elements inside Shadow DOM, .shadow() must be used before .find(). Missing it causes failure to locate the button.

3. Final Answer:

   You forgot to use .shadow() before .find() to access Shadow DOM. -> Option A

4. Quick Check:

   Missing .shadow() causes element not found [OK]

Hint: Always insert .shadow() before .find() for Shadow DOM elements [OK]

Common Mistakes:

• Skipping .shadow() when accessing Shadow DOM
• Assuming .find() works globally inside Shadow DOM host
• Blaming selector syntax without checking Shadow DOM usage

5. You want to test a nested Shadow DOM structure where outer-component hosts a Shadow DOM containing inner-component, which itself hosts another Shadow DOM with a button #confirm. Which Cypress command chain correctly clicks the button?

hard

A. cy.get('outer-component').shadow().shadow().find('inner-component').find('#confirm').click()

B. cy.get('outer-component').find('inner-component').shadow().find('#confirm').click()

C. cy.get('outer-component').shadow().find('inner-component').find('#confirm').click()

D. cy.get('outer-component').shadow().find('inner-component').shadow().find('#confirm').click()

Solution

1. Step 1: Access the first Shadow DOM

   Start with cy.get('outer-component') and enter its Shadow DOM using .shadow().

2. Step 2: Access the nested Shadow DOM

   Find inner-component inside the first Shadow DOM, then enter its Shadow DOM again with .shadow().

3. Step 3: Find and click the button

   Inside the nested Shadow DOM, find the button with id #confirm and perform .click().

4. Final Answer:

   cy.get('outer-component').shadow().find('inner-component').shadow().find('#confirm').click() -> Option D

5. Quick Check:

   Nested Shadow DOM requires chaining .shadow() twice [OK]

Hint: Chain .shadow() for each Shadow DOM level before .find() [OK]

Common Mistakes:

• Trying to access nested Shadow DOM without multiple .shadow() calls
• Using .find() directly without entering Shadow DOM
• Confusing order of .shadow() and .find() calls