Queries: Accessibility-First, Test-Id Last

// Component
export function LoginForm({ onSubmit }: { onSubmit: (email: string) => void }) {
  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        const email = new FormData(e.currentTarget).get('email') as string;
        onSubmit(email);
      }}
    >
      <label htmlFor="email">Email</label>
      <input id="email" name="email" type="email" required />
      <button type="submit">Sign in</button>
    </form>
  );
}

// ✅ Good — queries mirror how users find elements
import { render, screen } from '@testing-library/react';
import { LoginForm } from './login-form';

it('renders the form with the right controls', () => {
  render(<LoginForm onSubmit={() => {}} />);

  expect(screen.getByRole('textbox', { name: /email/i })).toBeInTheDocument();
  expect(screen.getByRole('button', { name: /sign in/i })).toBeInTheDocument();
});

// ❌ Anti-pattern — using test ids when role + name would work
it('renders the form (the brittle way)', () => {
  // Now the test depends on data-testid attributes the user can't see.
  // If a designer removes the data-testid, the test breaks but the UI works.
  render(<LoginForm onSubmit={() => {}} />);
  expect(screen.getByTestId('email-input')).toBeInTheDocument();
  expect(screen.getByTestId('submit-button')).toBeInTheDocument();
});

// Refining queries with options
import { render, screen } from '@testing-library/react';

it('finds the right heading level', () => {
  render(<ArticleWithMultipleHeadings />);

  // Match the h2 specifically, not the h1 or h3
  const sectionHeading = screen.getByRole('heading', {
    name: /related articles/i,
    level: 2,
  });

  expect(sectionHeading).toBeInTheDocument();
});

it('handles multiple buttons with disambiguation', () => {
  render(<DeleteConfirmDialog />);

  // The dialog has two buttons; the `name` option disambiguates.
  expect(
    screen.getByRole('button', { name: /confirm delete/i })
  ).toBeInTheDocument();
  expect(
    screen.getByRole('button', { name: /cancel/i })
  ).toBeInTheDocument();
});

// When test-id is genuinely the right answer
// (rare — usually for components that have no other accessible identifier)

import { render, screen } from '@testing-library/react';

it('finds a chart container', () => {
  render(<RevenueChart data={...} />);

  // Charts often render as <svg> with no inherent role or accessible name.
  // A test-id is honest here: there is no user-visible name to query by.
  expect(screen.getByTestId('revenue-chart')).toBeInTheDocument();
});

// Better, if you can add accessibility metadata:
// <svg role="img" aria-label="Revenue chart">  →  getByRole('img', { name: /revenue chart/i })