Cypress Lit Component Test Definition

This is a custom Lit component test definition for cypress.

• Getting started
• Manual setup
  • Update your Cypress config
  • Update your component config
• Usage

Getting started

To install, run:

npm install -D cypress-ct-lit-element

Once you have the package installed alongside Cypress, you can run npx cypress open, choose "Component Testing", and Lit should appear in the list of frameworks available.

Learn more about third-party definitions

Manual setup

If you already have an existing configuration and can't go through the setup process again, you can update your configuration to work with cypress-ct-lit-element.

Before you can get started, you need to also install lit and vite. Once you have, you need to take two updates:

Update your Cypress config

First, update your cypress.config.{ts,js} to have 'cypress-ct-lit-element' as your framework and 'vite' or 'webpack' as your bundler:

export default defineConfig({
  component: {
    devServer: {
      framework: 'cypress-ct-lit-element',
      bundler: 'vite',
      // more config here
    }
  }
})

If you're using TypeScript, you may get a type error when setting the framework property. If so, you'll need to typecast it as any:

framework: 'cypress-ct-lit-element' as any,

Update your component config

Next, add the following to your cypress/component.{ts,js} file:

import { mount } from 'cypress-ct-lit-element'

Cypress.Commands.add('mount', mount)

If you're using TypeScript, you may also need to add the following block to get the types to work:

declare global {
  namespace Cypress {
    interface Chainable {
      mount: typeof mount
    }
  }
}

Once you've followed these steps, you should be ready to write some tests!

Usage

You can now mount any HTML in a component test, for example:

import { html } from 'lit'

it('should display content', () => {
  const text = 'I will show up in the test'
  cy.mount(html`<div id='content'>${text}</div>`)

  cy.get('#content').should('contain.text', text)
})

This also works with custom elements. You can either reach into the shadow root manually:

import { html } from 'lit'

it('should render its children', () => {
  cy.mount(html`<my-element></my-element>`)

  cy.get('my-element')
    .shadow().find('.my-part') // you have to go through the shadow root to access elements inside <my-element>
    .should('exist')
})

Or, you can turn on includeShadowDom (see the docs on configuring Cypress)

export default defineConfig({
  component: {
    includeShadowDom: true
    // more config here
  }
})

With this option set, you can simply access elements in your custom elements directly:

import { html } from 'lit'

it('should render its children', () => {
  cy.mount(html`<my-element></my-element>`)

  cy.get('.my-part') // reaches through the shadow root to find element(s) inside <my-element>
    .should('exist')
})