Here is a test I found in a codebase last year: document.querySelector('.card > div:nth-child(2) span.amount-red'). It broke when a designer changed the colour of negative amounts. Nothing the user could see had broken, except the colour, which nobody tested. The test was coupled to the DOM’s shape and the CSS, not to what the page says.
Testing Library’s core idea fits in one sentence: the more your tests resemble the way your software is used, the more confidence they can give you. Users don’t see class names or nth-child. They see a button labelled “Add expense”, a field labelled “Amount”, a list of balances. Screen reader users get exactly that information through the accessibility tree: each element’s role (button, list, textbox) and accessible name (its label or text).
So Testing Library’s queries find elements by role, label and text. A test that finds the “Settle up” button by role and name keeps passing through any redesign, and fails the day the button stops being reachable for keyboard and screen reader users. That is a bug worth catching.
\ngetByRole with a name option covers most cases: buttons, links, headings, form fields, lists, dialogs, alerts. getByLabelText is the natural choice for form fields. getByText finds non-interactive content like a message or a balance line. Test ids are for elements with no role or text, such as a chart canvas, and they prove nothing about accessibility.
Splitwise-lite renders balances as a plain list. With jsdom as the environment and @testing-library/dom installed, a test looks like this:
// @vitest-environment jsdom\nimport { afterEach, test, expect } from 'vitest';\nimport { screen, within } from '@testing-library/dom';\nimport { renderBalances } from './render-balances.js';\n\nafterEach(() => {\n document.body.innerHTML = '';\n});\n\ntest('lists each person with what they owe or are owed', () => {\n renderBalances(document.body, { Ben: -500, Ana: 1200, Cai: 0 });\n\n const list = screen.getByRole('list', { name: 'Balances' });\n const items = within(list).getAllByRole('listitem');\n\n expect(items.map((item) => item.textContent)).toEqual([\n 'Ana is owed $12.00',\n 'Ben owes $5.00',\n 'Cai is settled up',\n ]);\n});\n\ntest('shows an empty state instead of an empty list', () => {\n renderBalances(document.body, {});\n\n expect(screen.getByText('No expenses yet')).toBeTruthy();\n expect(screen.queryByRole('list')).toBeNull();\n});screen queries the whole document. within(element) scopes queries to part of it, which matters as soon as a page has two lists. Clearing document.body after each test keeps one test’s DOM from leaking into the next. (React Testing Library can do this cleanup for you; lesson four of this section shows when.)
Each query comes in three flavours, plus an All version of each:
| Prefix | \nNo match | \nSeveral matches | \nUse it for | \n
|---|---|---|---|
getBy | \nthrows | \nthrows | \nelements that must be there | \n
queryBy | \nreturns null | \nthrows | \nasserting something is absent | \n
findBy | \nrejects after waiting | \nrejects | \nelements that appear later | \n
getBy throwing on several matches is a feature: if your query is ambiguous, the test tells you instead of silently picking the first.
Role queries fail loudly, and the failure is useful. When getByRole('button', { name: 'Settle up' }) finds nothing, Testing Library prints every accessible role in the container with the names it computed, so you can see that the button is actually named “Settle up all debts”, or that your clickable div has no role at all. Call screen.debug() to print the current DOM when you need more context. Accessible names come from a handful of places, in roughly this order: aria-labelledby, aria-label, an associated <label>, then the element’s own text (or alt for images). If none of them give the name you expect, a screen reader user hears the same confusing thing your test sees.
The playground has no npm packages, so the exercises in this section start with about forty lines of stand-ins: getByRole, getAllByRole, queryByRole, getByText and queryByText, with the same names and behaviour for the cases you need. Like the plain (non-screen) exports of @testing-library/dom, they take the container as their first argument: getByRole(container, 'list'). They read the role from the tag (or a role attribute) and the name from aria-label, a <label> or the text. Real Testing Library computes the accessibility tree much more thoroughly, so in a project, install it.
Next lesson: clicking and typing like a user.
\n","toc":[{"id":"sec-1","text":"The guiding principle","level":2},{"id":"sec-2","text":"The priority order","level":2},{"id":"sec-3","text":"A DOM test with Testing Library","level":2},{"id":"sec-4","text":"getBy, queryBy, findBy","level":2},{"id":"sec-5","text":"When a query can’t find your element","level":2},{"id":"sec-6","text":"In the playground","level":2}],"takeaways":["Query by what users perceive (role and accessible name, label, visible text), not by CSS classes or DOM structure, so restyling doesn’t break tests.","The priority order is:getByRole, then getByLabelText, getByPlaceholderText, getByText, getByDisplayValue, then alt text and title, and getByTestId last.","getBy throws when it finds zero or several matches, queryBy returns null (use it to assert absence), and findBy waits for an element to appear.","If a role query can’t find your element, the markup is often not accessible yet; fix the markup rather than switching to a test id."],"further":[{"title":"Testing Library — About Queries","url":"https://testing-library.com/docs/queries/about"},{"title":"Testing Library — ByRole","url":"https://testing-library.com/docs/queries/byrole"},{"title":"MDN — ARIA roles","url":"https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles"}],"quiz":[{"q":"The “Settle up” button is rendered as <button class="btn btn-primary" data-testid="settle">Settle up</button>. Which query should a test use?
container.querySelector('.btn-primary')","why":"Class names are styling decisions; renaming them during a redesign would break the test though the button still works."},{"text":"screen.getByTestId('settle')","why":"It works and survives restyling, but it’s the last resort in the priority list because users can’t see test ids, so it proves nothing about accessibility."},{"text":"screen.getByRole('button', { name: 'Settle up' })","why":"Correct. It finds the element the way a screen reader user would, and it fails if the button loses its role or its accessible name."}],"answer":2},{"q":"You want to assert that the empty-state message is gone after an expense is added. Which query fits?
","options":[{"text":"expect(screen.queryByText('No expenses yet')).toBeNull()","why":"Correct. queryBy returns null when nothing matches, which is exactly what you want to assert."},{"text":"expect(screen.getByText('No expenses yet')).toBeNull()","why":"getBy throws when nothing matches, so the test errors before toBeNull runs; it can never pass."},{"text":"expect(screen.findByText('No expenses yet')).toBeNull()","why":"findBy returns a promise (which is never null) and waits for the element to appear, the opposite of what you want."}],"answer":0},{"q":"screen.getByRole('textbox', { name: 'Amount' }) fails with “Unable to find an accessible element with the role textbox and name Amount”. The page shows the word Amount next to the input. What’s the most likely fix?
data-testid="amount" and query with getByTestId.","why":"That makes the test pass but leaves the real problem; screen reader users still hear an unlabelled field."},{"text":"Associate the text with the input using a <label> (wrapping it or with for/id).","why":"Correct. Text that merely sits nearby is not a label. Once it’s associated, the input gets an accessible name and the query, and your users, find it."},{"text":"Use getByText('Amount') and then read .nextSibling.","why":"Walking siblings couples the test to the exact DOM structure, and the input is still unlabelled."}],"answer":1},{"q":"Which pair of queries is closest to how a sighted mouse user and a screen reader user would find a list of balances?
","options":[{"text":"document.querySelector('ul') and .children","why":"These follow DOM structure; adding a wrapper or a second list would break or confuse the test."},{"text":"getByTestId('balances') and getAllByTestId('row')","why":"Test ids are invisible to users and the last resort in the priority list."},{"text":"getByRole('list', { name: 'Balances' }) and within(list).getAllByRole('listitem')","why":"Correct. The list’s role and label are what assistive tech announces, and within scopes the item query to that list."}],"answer":2}],"exercise":{"kind":"web","mode":"test","subject":"function formatMoney(cents) {\n const sign = cents < 0 ? '-' : '';\n const abs = Math.abs(cents);\n return `${sign}$${Math.floor(abs / 100)}.${String(abs % 100).padStart(2, '0')}`;\n}\n\n// Renders balances (in cents) into container.\n// - A list labelled \"Balances\", one item per person, sorted by name:\n// positive -> \"Ana is owed $12.00\"\n// negative -> \"Ben owes $5.00\"\n// zero -> \"Cai is settled up\"\n// - With no people at all: a paragraph \"No expenses yet\" and no list.\nfunction renderBalances(container, balances) {\n const names = Object.keys(balances).sort((a, b) => a.localeCompare(b));\n if (names.length === 0) {\n const empty = document.createElement('p');\n empty.textContent = 'No expenses yet';\n container.replaceChildren(empty);\n return;\n }\n const list = document.createElement('ul');\n list.setAttribute('aria-label', 'Balances');\n for (const name of names) {\n const cents = balances[name];\n const item = document.createElement('li');\n item.textContent =\n cents > 0 ? `${name} is owed ${formatMoney(cents)}`\n : cents < 0 ? `${name} owes ${formatMoney(-cents)}`\n : `${name} is settled up`;\n list.append(item);\n }\n container.replaceChildren(list);\n}\n","mutants":[{"id":"swapped-wording","code":"function formatMoney(cents) {\n const sign = cents < 0 ? '-' : '';\n const abs = Math.abs(cents);\n return `${sign}$${Math.floor(abs / 100)}.${String(abs % 100).padStart(2, '0')}`;\n}\n\n// Renders balances (in cents) into container.\n// - A list labelled \"Balances\", one item per person, sorted by name:\n// positive -> \"Ana is owed $12.00\"\n// negative -> \"Ben owes $5.00\"\n// zero -> \"Cai is settled up\"\n// - With no people at all: a paragraph \"No expenses yet\" and no list.\nfunction renderBalances(container, balances) {\n const names = Object.keys(balances).sort((a, b) => a.localeCompare(b));\n if (names.length === 0) {\n const empty = document.createElement('p');\n empty.textContent = 'No expenses yet';\n container.replaceChildren(empty);\n return;\n }\n const list = document.createElement('ul');\n list.setAttribute('aria-label', 'Balances');\n for (const name of names) {\n const cents = balances[name];\n const item = document.createElement('li');\n item.textContent =\n cents > 0 ? `${name} owes ${formatMoney(cents)}`\n : cents < 0 ? `${name} is owed ${formatMoney(-cents)}`\n : `${name} is settled up`;\n list.append(item);\n }\n container.replaceChildren(list);\n}\n"},{"id":"hides-settled","code":"function formatMoney(cents) {\n const sign = cents < 0 ? '-' : '';\n const abs = Math.abs(cents);\n return `${sign}$${Math.floor(abs / 100)}.${String(abs % 100).padStart(2, '0')}`;\n}\n\n// Renders balances (in cents) into container.\n// - A list labelled \"Balances\", one item per person, sorted by name:\n// positive -> \"Ana is owed $12.00\"\n// negative -> \"Ben owes $5.00\"\n// zero -> \"Cai is settled up\"\n// - With no people at all: a paragraph \"No expenses yet\" and no list.\nfunction renderBalances(container, balances) {\n const names = Object.keys(balances).filter((n) => balances[n] !== 0).sort((a, b) => a.localeCompare(b));\n if (names.length === 0) {\n const empty = document.createElement('p');\n empty.textContent = 'No expenses yet';\n container.replaceChildren(empty);\n return;\n }\n const list = document.createElement('ul');\n list.setAttribute('aria-label', 'Balances');\n for (const name of names) {\n const cents = balances[name];\n const item = document.createElement('li');\n item.textContent =\n cents > 0 ? `${name} is owed ${formatMoney(cents)}`\n : cents < 0 ? `${name} owes ${formatMoney(-cents)}`\n : `${name} is settled up`;\n list.append(item);\n }\n container.replaceChildren(list);\n}\n"},{"id":"minus-sign","code":"function formatMoney(cents) {\n const sign = cents < 0 ? '-' : '';\n const abs = Math.abs(cents);\n return `${sign}$${Math.floor(abs / 100)}.${String(abs % 100).padStart(2, '0')}`;\n}\n\n// Renders balances (in cents) into container.\n// - A list labelled \"Balances\", one item per person, sorted by name:\n// positive -> \"Ana is owed $12.00\"\n// negative -> \"Ben owes $5.00\"\n// zero -> \"Cai is settled up\"\n// - With no people at all: a paragraph \"No expenses yet\" and no list.\nfunction renderBalances(container, balances) {\n const names = Object.keys(balances).sort((a, b) => a.localeCompare(b));\n if (names.length === 0) {\n const empty = document.createElement('p');\n empty.textContent = 'No expenses yet';\n container.replaceChildren(empty);\n return;\n }\n const list = document.createElement('ul');\n list.setAttribute('aria-label', 'Balances');\n for (const name of names) {\n const cents = balances[name];\n const item = document.createElement('li');\n item.textContent =\n cents > 0 ? `${name} is owed ${formatMoney(cents)}`\n : cents < 0 ? `${name} owes ${formatMoney(cents)}`\n : `${name} is settled up`;\n list.append(item);\n }\n container.replaceChildren(list);\n}\n"},{"id":"no-empty-state","code":"function formatMoney(cents) {\n const sign = cents < 0 ? '-' : '';\n const abs = Math.abs(cents);\n return `${sign}$${Math.floor(abs / 100)}.${String(abs % 100).padStart(2, '0')}`;\n}\n\n// Renders balances (in cents) into container.\n// - A list labelled \"Balances\", one item per person, sorted by name:\n// positive -> \"Ana is owed $12.00\"\n// negative -> \"Ben owes $5.00\"\n// zero -> \"Cai is settled up\"\n// - With no people at all: a paragraph \"No expenses yet\" and no list.\nfunction renderBalances(container, balances) {\n const names = Object.keys(balances).sort((a, b) => a.localeCompare(b));\n if (false) {\n const empty = document.createElement('p');\n empty.textContent = 'No expenses yet';\n container.replaceChildren(empty);\n return;\n }\n const list = document.createElement('ul');\n list.setAttribute('aria-label', 'Balances');\n for (const name of names) {\n const cents = balances[name];\n const item = document.createElement('li');\n item.textContent =\n cents > 0 ? `${name} is owed ${formatMoney(cents)}`\n : cents < 0 ? `${name} owes ${formatMoney(-cents)}`\n : `${name} is settled up`;\n list.append(item);\n }\n container.replaceChildren(list);\n}\n"}],"starter":{"js":"// ── Tiny stand-ins for Testing Library queries (no npm in the playground) ──\nconst ROLE_SELECTORS = {\n alert: '[role=\"alert\"]',\n button: 'button, [role=\"button\"]',\n list: 'ul, ol, [role=\"list\"]',\n listitem: 'li, [role=\"listitem\"]',\n status: '[role=\"status\"]',\n textbox: 'input:not([type]), input[type=\"text\"], textarea, [role=\"textbox\"]',\n};\nfunction accessibleName(el) {\n if (el.getAttribute('aria-label')) return el.getAttribute('aria-label');\n if (el.labels && el.labels.length) return el.labels[0].textContent.trim();\n return el.textContent.trim();\n}\nfunction queryAllByRole(root, role, { name } = {}) {\n return [...root.querySelectorAll(ROLE_SELECTORS[role])]\n .filter((el) => !el.closest('[hidden]'))\n .filter((el) => name === undefined || accessibleName(el) === name);\n}\nfunction queryByRole(root, role, options) {\n return queryAllByRole(root, role, options)[0] ?? null;\n}\nfunction getAllByRole(root, role, options = {}) {\n const found = queryAllByRole(root, role, options);\n if (!found.length) throw new Error(`Unable to find role \"${role}\"${options.name ? ` named \"${options.name}\"` : ''}`);\n return found;\n}\nfunction getByRole(root, role, options = {}) {\n const found = getAllByRole(root, role, options);\n if (found.length > 1) throw new Error(`Found ${found.length} elements with role \"${role}\"`);\n return found[0];\n}\nfunction queryByText(root, text) {\n return [...root.querySelectorAll('*')].find((el) =>\n !el.closest('[hidden]') &&\n el.textContent.trim() === text &&\n ![...el.children].some((child) => child.textContent.trim() === text)) ?? null;\n}\nfunction getByText(root, text) {\n const el = queryByText(root, text);\n if (!el) throw new Error(`Unable to find text \"${text}\"`);\n return el;\n}\n// ────────────────────────────────────────────────────────────────────────────\n\nlet container;\n\nbeforeEach(() => {\n container = document.createElement('div');\n document.body.append(container);\n});\n\nafterEach(() => {\n container.remove();\n});\n\ndescribe('renderBalances', () => {\n test('renders a list labelled Balances', () => {\n renderBalances(container, { Ana: 1200, Ben: -1200 });\n\n expect(getByRole(container, 'list', { name: 'Balances' })).toBeTruthy();\n });\n\n // Add tests that read what the user reads: the text of each item,\n // a settled-up person, and the empty state.\n});\n"},"solution":{"js":"// ── Tiny stand-ins for Testing Library queries (no npm in the playground) ──\nconst ROLE_SELECTORS = {\n alert: '[role=\"alert\"]',\n button: 'button, [role=\"button\"]',\n list: 'ul, ol, [role=\"list\"]',\n listitem: 'li, [role=\"listitem\"]',\n status: '[role=\"status\"]',\n textbox: 'input:not([type]), input[type=\"text\"], textarea, [role=\"textbox\"]',\n};\nfunction accessibleName(el) {\n if (el.getAttribute('aria-label')) return el.getAttribute('aria-label');\n if (el.labels && el.labels.length) return el.labels[0].textContent.trim();\n return el.textContent.trim();\n}\nfunction queryAllByRole(root, role, { name } = {}) {\n return [...root.querySelectorAll(ROLE_SELECTORS[role])]\n .filter((el) => !el.closest('[hidden]'))\n .filter((el) => name === undefined || accessibleName(el) === name);\n}\nfunction queryByRole(root, role, options) {\n return queryAllByRole(root, role, options)[0] ?? null;\n}\nfunction getAllByRole(root, role, options = {}) {\n const found = queryAllByRole(root, role, options);\n if (!found.length) throw new Error(`Unable to find role \"${role}\"${options.name ? ` named \"${options.name}\"` : ''}`);\n return found;\n}\nfunction getByRole(root, role, options = {}) {\n const found = getAllByRole(root, role, options);\n if (found.length > 1) throw new Error(`Found ${found.length} elements with role \"${role}\"`);\n return found[0];\n}\nfunction queryByText(root, text) {\n return [...root.querySelectorAll('*')].find((el) =>\n !el.closest('[hidden]') &&\n el.textContent.trim() === text &&\n ![...el.children].some((child) => child.textContent.trim() === text)) ?? null;\n}\nfunction getByText(root, text) {\n const el = queryByText(root, text);\n if (!el) throw new Error(`Unable to find text \"${text}\"`);\n return el;\n}\n// ────────────────────────────────────────────────────────────────────────────\n\nlet container;\n\nbeforeEach(() => {\n container = document.createElement('div');\n document.body.append(container);\n});\n\nafterEach(() => {\n container.remove();\n});\n\ndescribe('renderBalances', () => {\n test('renders a list labelled Balances', () => {\n renderBalances(container, { Ana: 1200, Ben: -1200 });\n\n expect(getByRole(container, 'list', { name: 'Balances' })).toBeTruthy();\n });\n\n test('says who owes and who is owed, sorted by name', () => {\n renderBalances(container, { Ben: -500, Cai: 0, Ana: 500 });\n\n const items = getAllByRole(container, 'listitem');\n expect(items.map((item) => item.textContent)).toEqual([\n 'Ana is owed $5.00',\n 'Ben owes $5.00',\n 'Cai is settled up',\n ]);\n });\n\n test('shows an empty state instead of an empty list', () => {\n renderBalances(container, {});\n\n expect(getByText(container, 'No expenses yet')).toBeTruthy();\n expect(queryByRole(container, 'list')).toBeNull();\n });\n});\n"},"checks":[{"id":"passes","suite":"subject"},{"id":"catches-swapped-wording","suite":"swapped-wording"},{"id":"catches-hides-settled","suite":"hides-settled"},{"id":"catches-minus-sign","suite":"minus-sign"},{"id":"catches-no-empty-state","suite":"no-empty-state"}],"title":"Query the balances like a user","prompt":"renderBalances(container, balances) renders a list labelled Balances: "Ana is owed $12.00", "Ben owes $5.00", "Cai is settled up", sorted by name. With no people it shows No expenses yet and no list.
The starter begins with small stand-ins for Testing Library’s queries (getByRole, getAllByRole, queryByRole, getByText, queryByText; each takes the container as its first argument) and creates a fresh container for every test. Add tests until your suite catches four hidden bugs: swapped owes/is owed wording, a version that hides settled-up people, one that prints a minus sign (“owes -$5.00”), and one with no empty state.
getAllByRole(container, 'listitem').map((li) => li.textContent) gives you every line of text.","Use one balance of each kind (positive, negative, zero) so a single toEqual on the texts covers the wording, the sign and the settled person.","For the empty state, call renderBalances(container, {}), then getByText(container, 'No expenses yet') and expect(queryByRole(container, 'list')).toBeNull()."],"explanation":"The strongest assertion here compares the visible text of every item with one balance of each kind. That single toEqual catches the swapped wording, the stray minus sign and the missing settled-up line, because each changes what a user would read. The empty-state test uses getByText for what must be there and queryByRole(...) with toBeNull() for what must not, the standard getBy/queryBy split. None of the tests depends on tag nesting or classes: you could render the balances as a <div role="list"> with role="listitem" rows, or restyle everything, and they would still pass.