DOM Testing

// 1. Role + accessible name. What a screen reader announces.
screen.getByRole('button', { name: 'Add to cart' });
screen.getByRole('heading', { level: 1, name: /field notes/i });
screen.getByRole('textbox', { name: 'Card number' });

// 2. Label, placeholder, or displayed text
screen.getByLabelText('Card number');
screen.getByText('Order confirmed');

// 3. An explicit test contract
screen.getByTestId('order-total');

// 4. Structure. Breaks on the next redesign.
container.querySelector('.card > div:nth-child(2) input');

<!-- aria-labelledby wins -->
<button aria-labelledby="lbl"><span id="lbl">Pay</span></button>

<!-- then aria-label -->
<button aria-label="Close dialog">×</button>

<!-- then the associated <label> -->
<label for="card">Card number</label><input id="card">

<!-- then the element's own text content -->
<button>Add to cart</button>

<!-- an icon-only button with no label has NO accessible name.
     getByRole('button', { name: ... }) cannot find it — and neither
     can a screen-reader user. The test failure is correct. -->
<button><svg aria-hidden="true">…</svg></button>

import userEvent from '@testing-library/user-event';

const user = userEvent.setup();

// Fires pointerdown, mousedown, focus, pointerup, mouseup, click — the
// sequence a real click produces.
await user.click(screen.getByRole('button', { name: 'Save' }));

// Fires keydown/keypress/input/keyup per character
await user.type(screen.getByLabelText('Card number'), '4242424242424242');

await user.selectOptions(screen.getByRole('combobox', { name: 'Country' }), 'GB');
await user.tab();
await user.keyboard('{Escape}');

// The low-level alternative, which dispatches exactly one event.
// Useful occasionally; misleading as a default, because real users do not
// produce isolated change events.
fireEvent.change(input, { target: { value: '4242' } });

// findBy* = getBy* + waitFor. Use it for anything that appears later.
expect(await screen.findByText('Order confirmed')).toBeInTheDocument();

// Asserting absence needs queryBy* — getBy* throws when nothing matches.
expect(screen.queryByRole('alert')).not.toBeInTheDocument();

// Waiting for disappearance
await waitForElementToBeRemoved(() => screen.queryByRole('progressbar'));

// Common setup for the last of those
Object.defineProperty(window, 'matchMedia', {
  value: (query: string) => ({
    matches: false, media: query, addEventListener: () => {}, removeEventListener: () => {}
  })
});

// A custom element, tested through its rendered DOM.
customElements.define('price-tag', PriceTag);

document.body.innerHTML = '<price-tag cents="1200" was="1500"></price-tag>';
await customElements.whenDefined('price-tag');

const tag = document.querySelector('price-tag')!;
expect(tag.shadowRoot!.textContent).toContain('£12.00');