i18n-aware test selectors

[lleifermann]

Problem Description

Hey folks! I've been writing Vitest browser-mode tests for React components that use Lingui for i18n. I saw you already document a simple test wrapper that loads a catalog so translated strings actually render, that's great!

But it introduces a new problem: any copy change in my .po files can now break my tests.

Why data-testid isn't the answer

The obvious workaround is data-testid, but that defeats the purpose of accessible testing:

• It's an invisible, meaningless attribute, a user can't see or interact with data-testid="save-btn". If the button loses its accessible name or role, your test still passes but the component is broken for real users.
• It creates a parallel "test-only" contract that drifts from the actual UX contract. You end up testing that a div exists, not that a button exists.
• You get zero accessibility coverage for free. You can ship a completely inaccessible component with a green test suite.

A concrete example

Here's a simple component:

// ProfileForm.tsx
import { Trans } from "@lingui/react/macro";

export function ProfileForm() {
  return (
    <form>
      <label htmlFor="name">
        <Trans>Full name</Trans>
      </label>
      <input id="name" type="text" />
      <button type="submit">
        <Trans>Update profile</Trans>
      </button>
    </form>
  );
}

And a well-written, accessible test:

// ProfileForm.test.tsx
it("should submit the form when clicking the save button", async () => {
  const screen = await render(<ProfileForm />);

  // ✅ Queries by role + accessible name — asserts real UX contract
  const saveButton = page.getByRole("button", { name: "Update profile" });
  await saveButton.click();

  // ... assert form submission
});

This test is correct, it validates what a real user (and assistive technology) sees.

But now a copywriter changes the .po file:

- msgstr "Update profile"
+ msgstr "Save changes"

Test breaks. Not because behavior changed, not because accessibility regressed, just because the label copy was updated. The test was asserting the right thing, but was coupled to a specific snapshot of the translation.

Proposed Solution

I can't shake the feeling that this is something that the i18n library should be concerned about.
Ideally lingui exposes a way to reference message descriptors in test selectors, so the expected string is resolved from the same catalog the component uses. Like this:

import { messages } from "./ProfileForm"; // or wherever descriptors live

it("should submit the form when clicking the save button", async () => {
  const screen = await render(<ProfileForm />);

  // ✅ Still asserts role + accessible name (real UX contract)
  // ✅ But the expected string comes from the catalog, not a hardcoded copy
  const saveButton = page.getByRole("button", {
    name: t(messages.updateProfile),
  });
  await saveButton.click();
});

Now when the .po file changes from "Update profile" → "Save changes", both the component and the test resolve the new string from the same source of truth. No test breakage, no loss of accessibility coverage.

I think Lingui could provide an opinionated testing utility for this. Additionally this would allow for some very sleek tests setup that generates test specs for each .po file! Automatically testing for each language the project defines, instead of hardcoding for a single language!

Alternatives Considered

Not applicable

Additional Context

No response

[timofei-iatsenko]

I could agree only partially, if someone changed the text - test should fail. Because there is no longer a button with "Save changes" but here is a button of "Update profile", otherwise it not much different from the using data-testid approach.

You will not be able to catch translations drifts or incorrect placeholders interpolation etc. So i personally would still stick to a static selectors in the tests to make tests more readable and valuable.

Yes this is expensive and fragile, but that makes your test trustworthy. If both app and test would use similar mechanism (source of truth) for the message, if this mechanism breaks - your test will not catch it.

Answering your question directly, there is no catalog with the keys unless you use "explicit ids".

The key - is a source message itself, so if you want to query by the translation of this message you can just:

it("should submit the form when clicking the save button", async () => {
  const screen = await render(<ProfileForm />);

  const saveButton = page.getByRole("button", {
    name: t`Update profile`, // <-- would resolve to whatever translation for this message is
  });
  await saveButton.click();
});

But as i said, if at some moment, both app and test will return "XdFgh" (id of the message instead of the translation) your test will perfectly pass, where in-fact application is broken.

Also you will have to maintain all the placeholders in the message manually, eq:

t`Started at {{date: new Date('2026-01-12')}}`; // <-- placeholder name and value should exactly match, otherwise it would be a different translation key

Anyway you raised a good point. I don't know about best practices of testing i18n application. Do people test it on all translations? If yes - how? On my full-time job we cover all components with almost 95% coverage, but we just test it with source language.

[lleifermann]

I think i disagree with your statement that locating and testing via data-testId is similar to testing by role and text/name. But i definitely also see that i18n feels generally "undertested". Especially scenarios where other languages significantly vary in length from the source language. I've had multiple occasions now where i forgot to check other languages, only to find out that layout breaks (no flex-wrap) on longer sentences. We thought about generating a dev only catalog that explicitly generates verbose translations with AI that one can use during development to see how text behaves if it becomes very long. Similar to how lingui exposes the pseudo-locale.

Additionally i also wonder how would one check for missing translations for keys? Should lingui itself expose utility for this? Right now i use an external package to test this (linguito) and i just noticed it doesn't work in some edge cases. (I guess this is more of a CI question rather than something one would do in tests)