{"id":15415833,"url":"https://github.com/davidje13/flexible-testing-library-react","last_synced_at":"2026-05-11T09:04:15.036Z","repository":{"id":57238295,"uuid":"296152553","full_name":"davidje13/flexible-testing-library-react","owner":"davidje13","description":"A thin wrapper around React Testing Library which makes using custom queries easier.","archived":false,"fork":false,"pushed_at":"2023-08-28T00:49:30.000Z","size":46,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-08T14:02:52.387Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/davidje13.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-16T21:32:36.000Z","updated_at":"2023-08-28T00:49:29.000Z","dependencies_parsed_at":"2024-10-19T22:14:17.056Z","dependency_job_id":null,"html_url":"https://github.com/davidje13/flexible-testing-library-react","commit_stats":{"total_commits":7,"total_committers":1,"mean_commits":7.0,"dds":0.0,"last_synced_commit":"2b1be703c2c69ddad961f6ec54f3972aa68c39e1"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidje13%2Fflexible-testing-library-react","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidje13%2Fflexible-testing-library-react/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidje13%2Fflexible-testing-library-react/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidje13%2Fflexible-testing-library-react/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davidje13","download_url":"https://codeload.github.com/davidje13/flexible-testing-library-react/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244618448,"owners_count":20482319,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-01T17:09:55.007Z","updated_at":"2026-05-11T09:04:14.970Z","avatar_url":"https://github.com/davidje13.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Flexible Testing Library React\n\nA thin wrapper around [React Testing Library](https://github.com/testing-library/react-testing-library)\nwhich makes using custom queries easier.\n\nSee [this PR](https://github.com/testing-library/dom-testing-library/issues/266) for the\ndiscussion behind this and for reasoning why this isn't in core `@testing-library/dom`.\n\n## Install dependency\n\n```bash\nnpm install --save-dev flexible-testing-library-react\n```\n\n## Usage\n\nThis mostly follows the API of React Testing Library but with one important difference:\n\n```jsx\n// old\nimport { screen, render } from '@testing-library/react';\nrender(\u003cMyComponent /\u003e);\nscreen.getByLabelText('foo').something();\n\n// new\nimport { screen, render, labelText } from 'flexible-testing-library-react';\nrender(\u003cMyComponent /\u003e);\nscreen.getBy(labelText('foo')).something();\n```\n\nOr the alternative (scoped) syntax:\n\n```jsx\n// old\nimport { render } from '@testing-library/react';\nconst { getByLabelText } = render(\u003cMyComponent /\u003e);\ngetByLabelText('foo').something();\n\n// new\nimport { render, labelText } from 'flexible-testing-library-react';\nconst { getBy } = render(\u003cMyComponent /\u003e);\ngetBy(labelText('foo')).something();\n```\n\nAlso parameters for `findBy` now live in a more logical place:\n\n```jsx\n// old\nimport { screen, render } from '@testing-library/react';\nrender(\u003cMyComponent /\u003e);\nscreen.findByTitle('foo', {}, { timeout: 1000 }).something();\n\n// new\nimport { screen, render, title } from 'flexible-testing-library-react';\nrender(\u003cMyComponent /\u003e);\nscreen.findBy(title('foo'), { timeout: 1000 }).something();\n// no need to pass the empty {} argument to title() any more!\n```\n\nIf you are using Jest, a new matcher is also available:\n\n```jsx\nimport { screen, render, labelText } from 'flexible-testing-library-react';\nimport 'flexible-testing-library-react/extend-expect';\n\nrender(\u003cMyComponent /\u003e);\nexpect(screen).toContainElementWith(labelText('foo'));\nexpect(screen).not.toContainElementWith(labelText('nope'));\n```\n\n(this matcher improves on `toBeInTheDocument`, which has\n[problems with negation](https://github.com/testing-library/jest-dom/issues/106))\n\n## Reference\n\n### `getBy`\n\n```javascript\ngetBy(title('hello'));\n```\n\nReturns en element, or throws an exception if no elements were found (or multiple elements\nmatched).\n\n### `getAllBy`\n\n```javascript\ngetAllBy(title('hello'));\n```\n\nReturns a list of elements, or throws an exception if no elements were found.\n\n### `queryBy`\n\n```javascript\nqueryBy(title('hello'));\n```\n\nReturns an element, or `null` if no elements were found, or throws an exception if multiple\nelements matched.\n\n### `queryAllBy`\n\n```javascript\nqueryAllBy(title('hello'));\n```\n\nReturns a list of elements (which could be empty).\n\n### `findBy`\n\n```javascript\nawait findBy(title('hello'));\nawait findBy(title('hello'), { timeout: 1000 });\n```\n\nWaits until at least one matching element exists and returns it, or throws if the\ntimeout is reached before a matching element is found. Throws if multiple elements\nmatch.\n\nThe second parameter is an optional options dictionary, which is passed directly to\nDOM Testing Library's [`waitFor`](https://testing-library.com/docs/dom-testing-library/api-async#waitfor).\n\n### `findAllBy`\n\n```javascript\nawait findAllBy(title('hello'));\nawait findAllBy(title('hello'), { timeout: 1000 });\n```\n\nWaits until at least one matching element exists and returns a list of all matches,\nor throws if the timeout is reached before a matching element is found.\n\nThe second parameter is an optional options dictionary, which is passed directly to\nDOM Testing Library's [`waitFor`](https://testing-library.com/docs/dom-testing-library/api-async#waitfor).\n\n### Queries\n\nFor a list of supported queries, see the\n[DOM Testing Library documentation](https://testing-library.com/docs/dom-testing-library/api-queries#queries);\neach query is available here.\n\nExamples (note that the options can be omitted but are shown here to demonstrate their usage):\n\n| Function          | Example                                                | Upstream Docs                                                                                           |\n| ----------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |\n| `labelText`       | `getAllBy(labelText('hello', { exact: false }))`       | [ByLabelText](https://testing-library.com/docs/dom-testing-library/api-queries#bylabeltext)             |\n| `placeholderText` | `getAllBy(placeholderText('hello', { exact: false }))` | [ByPlaceholderText](https://testing-library.com/docs/dom-testing-library/api-queries#byplaceholdertext) |\n| `text`            | `getAllBy(text('hello', { exact: false }))`            | [ByText](https://testing-library.com/docs/dom-testing-library/api-queries#bytext)                       |\n| `altText`         | `getAllBy(altText('hello', { exact: false }))`         | [ByAltText](https://testing-library.com/docs/dom-testing-library/api-queries#byalttext)                 |\n| `title`           | `getAllBy(title('hello', { exact: false }))`           | [ByTitle](https://testing-library.com/docs/dom-testing-library/api-queries#bytitle)                     |\n| `displayValue`    | `getAllBy(displayValue('hello', { exact: false }))`    | [ByDisplayValue](https://testing-library.com/docs/dom-testing-library/api-queries#bydisplayvalue)       |\n| `role`            | `getAllBy(role('tab', { selected: true }))`            | [ByRole](https://testing-library.com/docs/dom-testing-library/api-queries#byrole)                       |\n| `testId`          | `getAllBy(testId('hello', { exact: false }))`          | [ByTestId](https://testing-library.com/docs/dom-testing-library/api-queries#bytestid)                   |\n\nAs a convenience another query is available as a shorthand:\n\n| Function       | Description                                        | Example                           |\n| -------------- | -------------------------------------------------- | --------------------------------- |\n| `textFragment` | Same as `text` with `exact: false` in the options. | `getAllBy(textFragment('hello'))` |\n\nFor other features, see the main [React Testing Library documentation](https://testing-library.com/docs/react-testing-library/intro).\n\n## Writing custom queries\n\n```javascript\nconst positionInTable = (column, row) =\u003e ({\n  // parameters can be anything you like\n  description: `in column ${column}, row ${row}`,\n  queryAll: (container) =\u003e {\n    // your query implementation here:\n    const rowElement = container.querySelectorAll('tr')[row];\n    if (!rowElement) {\n      return [];\n    }\n    const cellElement = rowElement.querySelectorAll('td')[column];\n    if (!cellElement) {\n      return [];\n    }\n    return [cellElement]; // always return a list, even if there is only one element\n  },\n});\n```\n\nThis can now be used easily with any of\n`getBy`, `getAllBy`, `findBy`, `findAllBy`, `queryBy`, `queryAllBy`:\n\n```jsx\nimport { screen, render } from 'flexible-testing-library-react';\nimport { positionInTable } from './positionInTable';\n\nrender(\u003cMyComponent /\u003e);\nscreen.getBy(positionInTable(2, 3)).something();\n```\n\nAnd can be used with `toContainElementWith`:\n\n```jsx\nimport { screen, render } from 'flexible-testing-library-react';\nimport 'flexible-testing-library-react/extend-expect';\nimport { positionInTable } from './positionInTable';\n\nrender(\u003cMyComponent /\u003e);\nexpect(screen).toContainElementWith(positionInTable(2, 3));\n```\n\n### Optional query configuration\n\nAs well as a `description` and `queryAll`, you can provide some other (optional)\nconfiguration:\n\n- `multipleErrorDetail`: a string to include in error messages about finding too many\n  matching elements.\n- `missingErrorDetail`: a string to include in error messages about not finding any\n  element.\n- `getAll`: a version of `queryAll` which throws if no elements are found (can be used\n  to provide more detailed error information). Note that you _must_ specify `queryAll`,\n  even if you also provide `getAll`.\n\n### TypeScript\n\nThe types for custom queries are:\n\n```typescript\nimport type { Query } from 'flexible-testing-library-react';\n\nconst tableCell = (row: number, column: number): Query =\u003e ({\n  description: `in column ${column}, row ${row}`,\n  queryAll: (container): NodeListOf\u003cHTMLElement\u003e | HTMLElement[] =\u003e {\n    /* implementation here */\n  },\n});\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidje13%2Fflexible-testing-library-react","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavidje13%2Fflexible-testing-library-react","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidje13%2Fflexible-testing-library-react/lists"}