Why you should not ship test IDs to production

The API is already telling you what to do #

Testing Library already gives away the answer in its API design.

Its query priority recommends queries like getByRole, getByLabelText, and getByText first, and leaves getByTestId as a fallback. That is not a random preference. It is a signal about how tests should interact with UI.

When a team reaches for data-testid too early, two things usually happen.

First, tests drift away from how the application is actually used. Second, inaccessible markup becomes easier to ship because the test can still find an element that a user cannot.

You should go one step further for production systems: do not let data-testid land in shipped markup at all.

The name already tells the story #

It is called data-testid. Not data-userid. Not data-accessibility-hook. Not data-business-identifier.

It is test-only information.

Once something is clearly test-only, it does not belong in production markup by default. Production HTML should describe the UI for users and browsers. It should not carry attributes whose main purpose is helping a test runner find elements.

This is not primarily about saving a few bytes. It is about keeping a clean boundary.

Test code belongs to tests. Production markup belongs to the product.

React Testing Library works best when your markup is meaningful #

The core idea behind Testing Library is simple: the closer a test is to real user behavior, the more confidence it gives.

That is why semantic queries come first. Roles, labels, and visible text are not random selectors. They are part of the user-facing contract of the UI.

A button should be discoverable as a button. An input should be discoverable through its label. A dialog should be discoverable through its role and accessible name.

data-testid does not help with any of that. It only helps the test runner.

A test can pass while the UI is still wrong #

This is where the accessibility argument becomes important. A test ID can make a broken component look tested.

import assert from "node:assert/strict";
import test from "node:test";
import type { FunctionComponent } from "react";
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";

type WidgetTriggerProperties = {
  onOpen: () => void;
};

const WidgetTrigger: FunctionComponent<WidgetTriggerProperties> = (
  properties
) => {
  const { onOpen } = properties;

  return (
    <div data-testid="open-widget" onClick={onOpen}>
      Open widget
    </div>
  );
};

test("opens the widget", async () => {
  let wasOpened = false;
  const user = userEvent.setup();

  render(
    <WidgetTrigger
      onOpen={() => {
        wasOpened = true;
      }}
    />
  );

  await user.click(screen.getByTestId("open-widget"));

  assert.equal(wasOpened, true);
});

That test passes. But the UI is still wrong.

A clickable div is not a button. It does not give you the right semantics. It is easy to get keyboard interaction wrong. It is easy to make screen reader behavior worse.

Now look at the same behavior tested through the interface the user actually depends on.

import assert from "node:assert/strict";
import test from "node:test";
import type { FunctionComponent } from "react";
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";

type WidgetTriggerProperties = {
  onOpen: () => void;
};

const WidgetTrigger: FunctionComponent<WidgetTriggerProperties> = (
  properties
) => {
  const { onOpen } = properties;

  return (
    <button type="button" onClick={onOpen}>
      Open widget
    </button>
  );
};

test("opens the widget", async () => {
  let wasOpened = false;
  const user = userEvent.setup();

  render(
    <WidgetTrigger
      onOpen={() => {
        wasOpened = true;
      }}
    />
  );

  await user.click(screen.getByRole("button", { name: "Open widget" }));

  assert.equal(wasOpened, true);
});

This test is better for a simple reason: if someone breaks the semantics later, the test has a chance to fail for the right reason.

That is not brittle coupling to implementation details. That is coupling to the part of the UI that users actually experience.

Test IDs can hide an accessibility problem #

If a role-based query cannot find your element, the problem is often not the test. The problem is the markup.

Maybe a button is implemented as a div. Maybe an input has no associated label. Maybe the page structure has no meaningful landmarks. Maybe interactive controls have no accessible name.

A data-testid makes all of those mistakes easier to ignore. It gives the team a shortcut around fixing the actual problem.

That is why test IDs are often an accessibility smell. They do not merely select an element. They can hide that the element is not correctly exposed to real users.

Shipping test IDs creates an accidental API #

There is another problem once data-testid lands in production. It rarely stays local to the test that introduced it.

End-to-end tests start depending on it. Support tooling starts depending on it. Maybe browser scripts or internal automation start depending on it. Suddenly a test-only attribute has become a production contract.

Now renaming a selector becomes risky. Not because the product changed, but because hidden consumers started depending on a private implementation detail.

You should not let test markup become part of your public surface area. That is another reason it should not ship by default.

The usual objection is text changes #

A common pushback is that roles, labels, and visible text change too often. That argument is usually weaker than people think.

If the visible name of a button changes, the user experience changed. That is not noise. That is part of the contract.

And in practice, Testing Library gives you enough tools to stay precise without falling back to test IDs immediately. You can scope queries with within. You can query dialogs, forms, navigation regions, lists, and buttons by role. You can target form fields by label.

import test from "node:test";
import { render, screen, within } from "@testing-library/react";
import userEvent from "@testing-library/user-event";

test("confirms deletion from the dialog", async () => {
  const user = userEvent.setup();

  render(<DeleteAccountDialog />);

  const dialog = screen.getByRole("dialog", {
    name: "Delete account"
  });

  const confirmButton = within(dialog).getByRole("button", {
    name: "Confirm"
  });

  await user.click(confirmButton);
});

That reads like the user flow. And when a test reads like the user flow, it usually ages better than people expect.

The escape hatch is real, but it should stay an escape hatch #

To be fair, even the Testing Library documentation for ByTestId keeps getByTestId around as an escape hatch. There are cases where matching by role, label, or text is hard or temporarily impractical.

That exists.

But an escape hatch is not a default architecture. And it is definitely not a good reason to normalize test-only attributes in production markup.

A good rule is simple: if you absolutely need a test ID for a rare case, treat it as temporary and suspicious. Do not treat it as the preferred way to test React components. And do not let it become part of the shipped DOM. If a team still relies on it during a transition, it is better to strip it from production builds than normalize it as permanent markup.

What you should optimize for instead #

When you test React components with Testing Library, optimize for these things:

• semantic HTML first
• accessible names for interactive elements
• proper labels for form controls
• queries by role, label, and visible text before anything else
• within to scope queries to meaningful regions
• test IDs only as a last resort, never as the default path

That approach does more than make tests nicer. It pushes the component itself in a better direction.

The bottom line #

If a test can only find an element through data-testid, first assume the UI or the test design needs improvement. Not that the missing attribute should be added to production.

Treat data-testid as a test concern. And test concerns should not leak into the product by default.

React Testing Library already points you toward the better path.

So the position is straightforward: do not make test IDs your primary selector strategy. And definitely do not ship them to production markup.