Open-Source Testing · testing-library

cypress-testing-library

Cypress Testing Library extends Cypress with DOM Testing Library commands, enabling developers to write e2e tests using accessible query patterns (by label text, role, etc.). It bridges Cypress's jQuery-based API with DOM Testing Library's user-centric query methods.

Talk to DEV.co Discuss Implementation

Source: GitHub — github.com/testing-library/cypress-testing-library

1.8k

GitHub stars

160

Forks

JavaScript

Primary language

MIT

License (OSI-approved)

Key facts

Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.

Field	Value
Repository	testing-library/cypress-testing-library
Owner	testing-library
Primary language	JavaScript
License	MIT — OSI-approved
Stars	1.8k
Forks	160
Open issues	42
Latest release	v10.1.3 (2026-04-29)
Last updated	2026-04-29
Source	https://github.com/testing-library/cypress-testing-library

What cypress-testing-library is

A JavaScript/TypeScript plugin that adds custom Cypress commands wrapping DOM Testing Library's findBy/findAllBy queries. It handles conversion between Cypress jQuery subjects and DOM nodes, with built-in retry logic and configuration for testId attributes.

Quickstart

Get the cypress-testing-library source

Clone the repository and explore it locally.

terminalbash

1git clone https://github.com/testing-library/cypress-testing-library.git2cd cypress-testing-library3# follow the project's README for install & configuration

Need it deployed, integrated, or customized instead? DEV.co ships production installs.

Best use cases

E2E testing with accessibility-first queries

Teams already using Cypress who want to adopt DOM Testing Library's user-centric selectors (byLabelText, byRole, byPlaceholder) to encourage testing from the user's perspective rather than implementation details.

Multi-layer test coverage

Projects using both unit tests (Jest + DOM Testing Library) and e2e tests (Cypress) can standardize on the same query APIs across test layers, reducing cognitive load and selector maintenance.

Cross-browser e2e testing with maintainable selectors

Enterprises running Cypress against multiple browsers that want semantic, stable selectors that adapt to DOM changes, reducing brittle xpath/class-based locators in test suites.

Implementation considerations

Must add '@testing-library/cypress/add-commands' import to cypress/support/commands.js; missing this is a common configuration error.
TypeScript projects require explicit types entry in tsconfig.json ("types": ["cypress", "@testing-library/cypress"]); lack of setup breaks intellisense.
Chaining queries to jQuery elements requires understanding the conversion between jQuery subjects and DOM nodes; behavior differs from synchronous DOM Testing Library calls.
findAllBy* returns multiple elements; Cypress auto-handles single-element actions (click), but queries must be explicit about length assertions if enforcing single matches.
testIdAttribute configuration (default 'data-testId') must match your HTML; mismatches silently fail queries requiring debugging.

When to avoid it — and what to weigh

You are not using Cypress — This library is explicitly a Cypress plugin. If your e2e framework is Playwright, WebdriverIO, or Selenium, you need DOM Testing Library directly or a framework-specific equivalent.
You need query* or get* commands — DOM Testing Library's non-awaited query* (for testing absence) and get* (synchronous) APIs are not exposed. Only find* commands with Cypress retries are supported; absence checks use .should('not.exist') instead.
You require real-time performance metrics during testing — This library wraps queries but does not expose performance timing or Core Web Vitals measurements. Use dedicated performance testing tools or Cypress' native profiling if that is a hard requirement.
You need a zero-config solution — Installation requires explicit import in cypress/support/commands.js and potential configuration of testIdAttribute. Projects with minimal test infrastructure setup overhead may find this friction unwelcome.

License & commercial use

Licensed under MIT (MIT License), a permissive OSI-approved license permitting commercial use, modification, and distribution with inclusion of license and copyright notice.

MIT License explicitly permits commercial use in proprietary applications. No license-based restrictions on using this library in commercial products. Verify compliance with any linked dependencies (Cypress, DOM Testing Library) which carry their own licenses, though Cypress is broadly permissive for commercial use.

DEV.co evaluation signals

Editorial assessment — not user reviews. Directional, with an explicit confidence level.

Signal	Assessment
Maintenance	Active
Documentation	Adequate
License clarity	Clear
Deployment complexity	Low
DEV.co fit	Good
Assessment confidence	High

Security considerations

Library operates within Cypress sandbox; no direct file I/O or network calls beyond Cypress's own test runner. DOM query execution is client-side within the browser under test. No sensitive data handling or authentication. Standard npm supply-chain risks apply (dependency tree, typosquatting); verify @testing-library/cypress package identity on npm registry. Review DOM Testing Library and Cypress for any known vulnerabilities in transitive dependencies.

Alternatives to consider

Playwright with Testing Library (via @testing-library/playwright)

If moving from Cypress to Playwright: Playwright offers better browser support, faster execution, and similar Testing Library integration. Choose if you are not locked into Cypress.

Cypress with cy.get() + CSS selectors / data-testid

WebdriverIO with @testing-library/webdriverio

For teams needing a language-agnostic, WebDriver-standard test framework with Testing Library: WebdriverIO offers more granular control and supports multiple languages. Choose if Cypress's architecture doesn't fit your CI/CD.

Software development agency

Build on cypress-testing-library with DEV.co software developers

Cypress Testing Library lets you use the same accessibility-first DOM queries in both unit and e2e tests. Reduce selector maintenance and encourage best practices from day one.

Talk to DEV.co

Related open-source tools

Surfaced by semantic similarity across the DEV.co open-source index.

cypress dom-testing-library cypress-realworld-app

Related on DEV.co

Explore the category and the services that help you build with it.

Open-Source Testing Web App Development AI-Assisted Testing Development Custom Software & QA Integration Talk to DEV.co

cypress-testing-library FAQ

Can I use this with Cypress 12+ / 13+?

Unknown from provided data. Latest release is v10.1.3 (April 2026). Verify compatibility matrix in package.json or GitHub releases for your Cypress version; major version mismatches may break due to Cypress API changes.

Does this support shadow DOM queries?

Not clearly stated in documentation. DOM Testing Library's underlying getBy/findBy queries may not penetrate shadow DOM boundaries. Test directly or open an issue if shadow DOM support is required.

How do I debug a query that's not finding the element?

Use Cypress's built-in debugging: cy.debug(), Cypress DevTools, or add .should() assertions with explicit error messages. Review generated error messages from findBy failures; they include DOM snapshots. Check testIdAttribute configuration matches your HTML.

Can I use this with component testing (Cypress CT)?

Unknown from data provided. Cypress CT has different APIs; review current documentation or test in your project. Likely supported but may require separate setup vs. e2e testing.

Work with a software development agency

Need help beyond evaluating cypress-testing-library? DEV.co is a software development agency offering software development services and web development for teams of every size. Our software developers and web developers build custom software, web applications, APIs, and open-source testing integrations — and maintain them long-term.

Standardize Your Test Selectors Across Unit and E2E

Cypress Testing Library lets you use the same accessibility-first DOM queries in both unit and e2e tests. Reduce selector maintenance and encourage best practices from day one.

Talk to DEV.co Schedule a Consultation