data-testid best practices.

If a test should fail when a button loses its accessible name, use its role and name. If the same action needs a stable hook across different labels or layouts, a test ID can be a better fit.

A test ID does not replace a label, alt text, or other accessibility work. It also cannot guarantee a test will pass through loading, network, or state problems.

Further reading: Playwright locator guidance and Testing Library’s query priority.

A useful convention is feature-purpose in lowercase kebab-case: checkout-submit, account-email, or cart-remove-item. This is a team convention, not a requirement of HTML.

Avoid color names, array positions, generated values, and personal data. In repeated components, a stable item key can help, but scope to a specific card or row when you already have a clear way to identify it.

Keep the attribute on the actual interactive element. Putting it on a wrapper can make the test click the wrapper instead of the button.

Switch the example below from its original design to a new label and layout. Then introduce a duplicate ID. The match count comes from the rendered elements in the example.

The lesson: a stable name helps only when it still identifies the intended element. A changed label might be harmless in one test and exactly the regression another test needs to catch.

Start with the example for your test setup. The Playwright version is self-contained; the other examples explain what your project needs. Keep the assertion after the action so the test verifies an outcome.

import { test, expect } from '@playwright/test';

test('places an order', async ({ page }) => {
  // Self-contained fixture; no application server needed.
  await page.setContent(`<button data-testid="checkout-submit">
  Place order
</button>
<p role="status" data-testid="checkout-status"></p>
<script>
  document.querySelector('button').addEventListener('click', () => {
    document.querySelector('[role="status"]').textContent = 'Order placed';
  });
</script>`);

  await page.getByTestId('checkout-submit').click();
  await expect(page.getByRole('status')).toHaveText('Order placed');
});

import { useState } from 'react';
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import '@testing-library/jest-dom';

function Checkout() {
  const [placed, setPlaced] = useState(false);
  return (
    <>
      <button data-testid="checkout-submit"
        onClick={() => setPlaced(true)}>Place order</button>
      <p role="status">{placed ? 'Order placed' : ''}</p>
    </>
  );
}

test('places an order', async () => {
  const user = userEvent.setup();
  render(<Checkout />);
  await user.click(screen.getByTestId('checkout-submit'));
  expect(screen.getByRole('status')).toHaveTextContent('Order placed');
});

describe('checkout', () => {
  it('places an order', () => {
    cy.visit('/checkout');
    cy.get('[data-testid="checkout-submit"]').click();
    cy.get('[data-testid="checkout-status"]')
      .should('have.text', 'Order placed');
  });
});

const matches = document.querySelectorAll(
  '[data-testid="checkout-submit"]'
);

console.log(matches.length); // Expect 1 in this scope.

// The equivalent CSS attribute selector:
// [data-testid="checkout-submit"]

Already using data-cy or data-test-id?

The attribute name has to match your configuration. For example, point Playwright’s getByTestId at data-cy in the test config:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: { testIdAttribute: 'data-cy' },
});

// <button data-cy="checkout-submit">Place order</button>
// page.getByTestId('checkout-submit')

See the testIdAttribute option. Testing Library has its own configuration for custom attributes.

Two product cards can legitimately contain the same add-to-cart test ID. The problem is clicking it without identifying which card you mean.

<article data-testid="product-card">
  <h3>Trail shoes</h3>
  <button data-testid="add-to-cart">Add to cart</button>
</article>
<article data-testid="product-card">
  <h3>City shoes</h3>
  <button data-testid="add-to-cart">Add to cart</button>
</article>

Select the intended product first, then find its button. Checking the count makes your expectation explicit.

const product = page.getByTestId('product-card').filter({
  has: page.getByRole('heading', { name: 'Trail shoes' }),
});
const addToCart = product.getByTestId('add-to-cart');

await expect(addToCart).toHaveCount(1);
await addToCart.click();

A page-wide getByTestId('add-to-cart').click() is ambiguous here. Avoid reaching for .first() just to silence the error; a reordered list could make it click the wrong product.

Playwright: filtering by a child locator

A React prop needs to reach the DOM.

function CheckoutButton({ testId }: { testId: string }) {
  return <button data-testid={testId}>Place order</button>;
}

<CheckoutButton testId="checkout-submit" />

testId is just a prop on this custom component. The data-testid attribute on the native button is what the locator actually reads.

Playwright: actionability checks

The component owner and the test author should agree on the name and scope. Treat renaming a test ID as a change to a shared interface: update its callers in the same pull request.

Document one attribute convention, decide who reviews changes, and test the same kind of build you intend to ship. If you strip test IDs from production, make sure your production checks do not depend on them.