feat(configureTestIdAttribute): add ability to override data-testid [generic config] (#164)

N.B. This is one of two alternative PRs with slightly differing configuration APIs.  This one contains a generic configuration API exposing one configuration function taking an object which could be extended for future use.  That may desirable or not, hence the two PRs.

**What**:

Introduce an API to allow `data-testid` to be overridden without consumers needing
to construct and maintain a set of higher level decorator functions to override the various 'xxxByTestId' functions as exposed in various places.

<!-- Why are these changes necessary? -->

**Why**:

The existing API, where `data-testid` cannot be changed at the low level, requires a significant amount of effort to customise the higher-level APIs. See issue #162 for more discussion.

**How**:

Ultimately we needed to parameterise what was previously some hardcoded strings in `queries.js`. I would have preferred to keep the changes local to `queries.js`, but we assume elsewhere that all exports from `queries.js` are queries, and I didn't want to alter that.  So I added a simple `config.js` module to store the actual configuration, and `queries.js` references that and `index.js` exposes the tiny configuration API.

<!-- Have you done all of these things?  -->

**Checklist**:

- [x] Documentation
- [x] Tests
- [x] Ready to be merged <!-- In your opinion, is this ready to be merged as soon as it's reviewed? -->
- [x] Added myself to contributors table <!-- this is optional, see the contributing guidelines for instructions -->

<!-- feel free to add additional comments -->

Author: RoystonS

.all-contributorsrc

@@ -419,6 +419,18 @@
       "contributions": [
         "code"
       ]
+    },
+    {
+      "login": "RoystonS",
+      "name": "Royston Shufflebotham",
+      "avatar_url": "https://avatars0.githubusercontent.com/u/19773?v=4",
+      "profile": "https://github.com/RoystonS",
+      "contributions": [
+        "bug",
+        "code",
+        "doc",
+        "test"
+      ]
     }
   ]
 }

README.md

@@ -10,19 +10,21 @@
 
 <hr />
 
+<!-- prettier-ignore-start -->
 [![Build Status][build-badge]][build]
 [![Code Coverage][coverage-badge]][coverage]
 [![version][version-badge]][package]
 [![downloads][downloads-badge]][npmtrends]
 [![MIT License][license-badge]][license]
 
-[![All Contributors](https://img.shields.io/badge/all_contributors-42-orange.svg?style=flat-square)](#contributors)
+[![All Contributors](https://img.shields.io/badge/all_contributors-43-orange.svg?style=flat-square)](#contributors)
 [![PRs Welcome][prs-badge]][prs]
 [![Code of Conduct][coc-badge]][coc]
 
 [![Watch on GitHub][github-watch-badge]][github-watch]
 [![Star on GitHub][github-star-badge]][github-star]
 [![Tweet][twitter-badge]][twitter]
+<!-- prettier-ignore-end -->
 
 <div align="center">
 <a href="https://testingjavascript.com">
@@ -102,6 +104,7 @@ when a real user uses it.
 - [`within` and `getQueriesForElement` APIs](#within-and-getqueriesforelement-apis)
 - [Debugging](#debugging)
   - [`prettyDOM`](#prettydom)
+- [Configuration](#configuration)
 - [Implementations](#implementations)
 - [Using Without Jest](#using-without-jest)
 - [FAQ](#faq)
@@ -456,6 +459,17 @@ const usernameInputElement = getByTestId(container, 'username-input')
 > `data-testid`s from the blog post
 > ["Making your UI tests resilient to change"][data-testid-blog-post]
 
+#### Overriding `data-testid`
+
+The `...ByTestId` functions in `dom-testing-library` use the attribute `data-testid`
+by default, following the precedent set by
+[React Native Web](https://github.com/kentcdodds/react-testing-library/issues/1)
+which uses a `testID` prop to emit a `data-testid` attribute on the element,
+and we recommend you adopt that attribute where possible.
+But if you already have an existing codebase that uses a different attribute
+for this purpose, you can override this value via
+`configure({testIdAttribute: 'data-my-test-attribute'})`.
+
 ### `wait`
 
 ```typescript
@@ -928,6 +942,19 @@ console.log(prettyDOM(div))
 
 This function is what also powers [the automatic debugging output described above](#debugging).
 
+## Configuration
+
+The library can be configured via the `configure` function, which accepts:
+
+- a plain JS object; this will be merged into the existing configuration. e.g. `configure({testIdAttribute: 'not-data-testid'})`
+- a function; the function will be given the existing configuration, and should return a plain JS object which will be merged as above, e.g.
+  `configure(existingConfig => ({something: [...existingConfig.something, 'extra value for the something array']}))`
+
+Configuration options:
+
+`testIdAttribute`: The attribute used by `getByTestId` and related queries.
+Defaults to `data-testid`. See [`getByTestId`](#getbytestid).
+
 ## Implementations
 
 This library was not built to be used on its own. The original implementation
@@ -1115,6 +1142,7 @@ Thanks goes to these people ([emoji key][emojis]):
 | [<img src="https://avatars2.githubusercontent.com/u/21689428?v=4" width="100px;"/><br /><sub><b>Jonathan Stoye</b></sub>](http://jonathanstoye.de)<br />[📖](https://github.com/kentcdodds/dom-testing-library/commits?author=JonathanStoye "Documentation") | [<img src="https://avatars2.githubusercontent.com/u/4126644?v=4" width="100px;"/><br /><sub><b>Sanghyeon Lee</b></sub>](https://github.com/yongdamsh)<br />[💡](#example-yongdamsh "Examples") | [<img src="https://avatars3.githubusercontent.com/u/8015514?v=4" width="100px;"/><br /><sub><b>Justice Mba </b></sub>](https://github.com/Dajust)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=Dajust "Code") [📖](https://github.com/kentcdodds/dom-testing-library/commits?author=Dajust "Documentation") [🤔](#ideas-Dajust "Ideas, Planning, & Feedback") | [<img src="https://avatars3.githubusercontent.com/u/340761?v=4" width="100px;"/><br /><sub><b>Wayne Crouch</b></sub>](https://github.com/wgcrouch)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=wgcrouch "Code") | [<img src="https://avatars1.githubusercontent.com/u/4996462?v=4" width="100px;"/><br /><sub><b>Ben Elliott</b></sub>](http://benjaminelliott.co.uk)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=benelliott "Code") | [<img src="https://avatars3.githubusercontent.com/u/577921?v=4" width="100px;"/><br /><sub><b>Ruben Costa</b></sub>](http://nuances.co)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=rubencosta "Code") | [<img src="https://avatars2.githubusercontent.com/u/4982001?v=4" width="100px;"/><br /><sub><b>Robert Smith</b></sub>](http://rbrtsmith.com/)<br />[🐛](https://github.com/kentcdodds/dom-testing-library/issues?q=author%3Arbrtsmith "Bug reports") [🤔](#ideas-rbrtsmith "Ideas, Planning, & Feedback") [📖](https://github.com/kentcdodds/dom-testing-library/commits?author=rbrtsmith "Documentation") |
 | [<img src="https://avatars3.githubusercontent.com/u/881986?v=4" width="100px;"/><br /><sub><b>dadamssg</b></sub>](https://github.com/dadamssg)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=dadamssg "Code") | [<img src="https://avatars1.githubusercontent.com/u/186971?v=4" width="100px;"/><br /><sub><b>Neil Kistner</b></sub>](https://neilkistner.com/)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=wyze "Code") | [<img src="https://avatars3.githubusercontent.com/u/1448597?v=4" width="100px;"/><br /><sub><b>Ben Chauvette</b></sub>](http://bdchauvette.net/)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=bdchauvette "Code") | [<img src="https://avatars2.githubusercontent.com/u/777527?v=4" width="100px;"/><br /><sub><b>Jeff Baumgardt</b></sub>](https://github.com/JeffBaumgardt)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=JeffBaumgardt "Code") [📖](https://github.com/kentcdodds/dom-testing-library/commits?author=JeffBaumgardt "Documentation") | [<img src="https://avatars0.githubusercontent.com/u/4658208?v=4" width="100px;"/><br /><sub><b>Matan Kushner</b></sub>](http://matchai.me)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=matchai "Code") [📖](https://github.com/kentcdodds/dom-testing-library/commits?author=matchai "Documentation") [🤔](#ideas-matchai "Ideas, Planning, & Feedback") [⚠️](https://github.com/kentcdodds/dom-testing-library/commits?author=matchai "Tests") | [<img src="https://avatars2.githubusercontent.com/u/5779538?v=4" width="100px;"/><br /><sub><b>Alex Wendte</b></sub>](http://www.wendtedesigns.com/)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=themostcolm "Code") [📖](https://github.com/kentcdodds/dom-testing-library/commits?author=themostcolm "Documentation") [⚠️](https://github.com/kentcdodds/dom-testing-library/commits?author=themostcolm "Tests") | [<img src="https://avatars0.githubusercontent.com/u/2196208?v=4" width="100px;"/><br /><sub><b>Tamas Fodor</b></sub>](https://github.com/ruffle1986)<br />[📖](https://github.com/kentcdodds/dom-testing-library/commits?author=ruffle1986 "Documentation") |
 | [<img src="https://avatars3.githubusercontent.com/u/14793495?v=4" width="100px;"/><br /><sub><b>Benjamin Eckardt</b></sub>](https://github.com/BenjaminEckardt)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=BenjaminEckardt "Code") | [<img src="https://avatars3.githubusercontent.com/u/205752?v=4" width="100px;"/><br /><sub><b>Ryan Campbell</b></sub>](https://github.com/campbellr)<br />[📖](https://github.com/kentcdodds/dom-testing-library/commits?author=campbellr "Documentation") | [<img src="https://avatars2.githubusercontent.com/u/1335519?v=4" width="100px;"/><br /><sub><b>Taylor Briggs</b></sub>](https://taylor-briggs.com)<br />[⚠️](https://github.com/kentcdodds/dom-testing-library/commits?author=TaylorBriggs "Tests") | [<img src="https://avatars2.githubusercontent.com/u/132233?v=4" width="100px;"/><br /><sub><b>John Gozde</b></sub>](https://github.com/jgoz)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=jgoz "Code") | [<img src="https://avatars2.githubusercontent.com/u/3382565?v=4" width="100px;"/><br /><sub><b>C. T. Lin</b></sub>](https://github.com/chentsulin)<br />[📖](https://github.com/kentcdodds/dom-testing-library/commits?author=chentsulin "Documentation") | [<img src="https://avatars3.githubusercontent.com/u/5312329?v=4" width="100px;"/><br /><sub><b>Terrence Wong</b></sub>](http://terrencewwong.com)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=terrencewwong "Code") | [<img src="https://avatars0.githubusercontent.com/u/12230408?v=4" width="100px;"/><br /><sub><b>Soo Jae Hwang</b></sub>](https://www.ossfinder.com)<br />[💻](https://github.com/kentcdodds/dom-testing-library/commits?author=misoguy "Code") |
+| [<img src="https://avatars0.githubusercontent.com/u/19773?v=4" width="100px;"/><br /><sub><b>Royston Shufflebotham</b></sub>](https://github.com/RoystonS)<br />[🐛](https://github.com/kentcdodds/dom-testing-library/issues?q=author%3ARoystonS "Bug reports") [💻](https://github.com/kentcdodds/dom-testing-library/commits?author=RoystonS "Code") [📖](https://github.com/kentcdodds/dom-testing-library/commits?author=RoystonS "Documentation") [⚠️](https://github.com/kentcdodds/dom-testing-library/commits?author=RoystonS "Tests") |
 
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 

src/__tests__/config.js

@@ -0,0 +1,55 @@
+import {configure, getConfig} from '../config'
+
+describe('configuration API', () => {
+  let originalConfig
+  beforeEach(() => {
+    // Grab the existing configuration so we can restore
+    // it at the end of the test
+    configure(existingConfig => {
+      originalConfig = existingConfig
+      // Don't change the existing config
+      return {}
+    })
+  })
+  afterEach(() => {
+    configure(originalConfig)
+  })
+
+  beforeEach(() => {
+    configure({other: 123})
+  })
+
+  describe('getConfig', () => {
+    test('returns existing configuration', () => {
+      const conf = getConfig()
+      expect(conf.testIdAttribute).toEqual('data-testid')
+    })
+  })
+
+  describe('configure', () => {
+    test('merges a delta rather than replacing the whole config', () => {
+      const conf = getConfig()
+      expect(conf).toMatchObject({testIdAttribute: 'data-testid'})
+    })
+
+    test('overrides existing values', () => {
+      configure({testIdAttribute: 'new-id'})
+      const conf = getConfig()
+      expect(conf.testIdAttribute).toEqual('new-id')
+    })
+
+    test('passes existing config out to config function', () => {
+      // Create a new config key based on the value of an existing one
+      configure(existingConfig => ({
+        testIdAttribute: `${existingConfig.testIdAttribute}-derived`,
+      }))
+      const conf = getConfig()
+
+      // The new value should be there, and existing values should be
+      // untouched
+      expect(conf).toMatchObject({
+        testIdAttribute: 'data-testid-derived',
+      })
+    })
+  })
+})

src/__tests__/element-queries.js

@@ -1,4 +1,5 @@
 import 'jest-dom/extend-expect'
+import {configure} from '../config'
 import {render, renderIntoDocument} from './helpers/test-utils'
 import document from './helpers/document'
 
@@ -258,16 +259,34 @@ test('query/get select by text with multiple options selected', () => {
   expect(queryBySelectText('Alaska').id).toEqual('state-select')
 })
 
-test('can get elements by data-testid attribute', () => {
-  const {queryByTestId} = render(`<div data-testid="firstName"></div>`)
-  expect(queryByTestId('firstName')).toBeTruthy()
-  expect(queryByTestId(/first/)).toBeTruthy()
-  expect(queryByTestId(testid => testid === 'firstName')).toBeTruthy()
-  // match should be exact, case-sensitive
-  expect(queryByTestId('firstname')).not.toBeTruthy()
-  expect(queryByTestId('first')).not.toBeTruthy()
-  expect(queryByTestId('firstNamePlusMore')).not.toBeTruthy()
-  expect(queryByTestId('first-name')).not.toBeTruthy()
+describe('query by test id', () => {
+  test('can get elements by test id', () => {
+    const {queryByTestId} = render(`<div data-testid="firstName"></div>`)
+    expect(queryByTestId('firstName')).toBeTruthy()
+    expect(queryByTestId(/first/)).toBeTruthy()
+    expect(queryByTestId(testid => testid === 'firstName')).toBeTruthy()
+    // match should be exact, case-sensitive
+    expect(queryByTestId('firstname')).not.toBeTruthy()
+    expect(queryByTestId('first')).not.toBeTruthy()
+    expect(queryByTestId('firstNamePlusMore')).not.toBeTruthy()
+    expect(queryByTestId('first-name')).not.toBeTruthy()
+  })
+
+  test('can override test id attribute', () => {
+    const {queryByTestId} = render(`<div data-my-test-id="theTestId"></div>`)
+
+    configure({testIdAttribute: 'data-my-test-id'})
+    expect(queryByTestId('theTestId')).toBeTruthy()
+
+    configure({testIdAttribute: 'something-else'})
+    expect(queryByTestId('theTestId')).toBeFalsy()
+  })
+
+  afterEach(() => {
+    // Restore the default test id attribute
+    // even if these tests failed
+    configure({testIdAttribute: 'data-testid'})
+  })
 })
 
 test('getAll* matchers return an array', () => {

src/config.js

@@ -0,0 +1,24 @@
+// It would be cleaner for this to live inside './queries', but
+// other parts of the code assume that all exports from
+// './queries' are query functions.
+let config = {
+  testIdAttribute: 'data-testid',
+}
+
+export function configure(newConfig) {
+  if (typeof newConfig === 'function') {
+    // Pass the existing config out to the provided function
+    // and accept a delta in return
+    newConfig = newConfig(config)
+  }
+
+  // Merge the incoming config delta
+  config = {
+    ...config,
+    ...newConfig,
+  }
+}
+
+export function getConfig() {
+  return config
+}

src/index.js

@@ -12,6 +12,7 @@ export * from './events'
 export * from './get-queries-for-element'
 export * from './query-helpers'
 export * from './pretty-dom'
+export {configure} from './config'
 
 export {
   // The original name of bindElementToQueries was weird

src/queries.js

@@ -6,6 +6,7 @@ import {
   queryAllByAttribute,
   queryByAttribute,
 } from './query-helpers'
+import {getConfig} from './config'
 
 // Here are the queries for the library.
 // The queries here should only be things that are accessible to both users who are using a screen reader
@@ -148,10 +149,16 @@ function queryBySelectText(...args) {
   return firstResultOrNull(queryAllBySelectText, ...args)
 }
 
+function getTestIdAttribute() {
+  return getConfig().testIdAttribute
+}
+
 const queryByPlaceholderText = queryByAttribute.bind(null, 'placeholder')
 const queryAllByPlaceholderText = queryAllByAttribute.bind(null, 'placeholder')
-const queryByTestId = queryByAttribute.bind(null, 'data-testid')
-const queryAllByTestId = queryAllByAttribute.bind(null, 'data-testid')
+const queryByTestId = (...args) =>
+  queryByAttribute(getTestIdAttribute(), ...args)
+const queryAllByTestId = (...args) =>
+  queryAllByAttribute(getTestIdAttribute(), ...args)
 const queryByValue = queryByAttribute.bind(null, 'value')
 const queryAllByValue = queryAllByAttribute.bind(null, 'value')
 const queryByRole = queryByAttribute.bind(null, 'role')
@@ -182,7 +189,7 @@ function getAllByTestId(container, id, ...rest) {
   const els = queryAllByTestId(container, id, ...rest)
   if (!els.length) {
     throw getElementError(
-      `Unable to find an element by: [data-testid="${id}"]`,
+      `Unable to find an element by: [${getTestIdAttribute()}="${id}"]`,
       container,
     )
   }

typings/config.d.ts

@@ -0,0 +1,9 @@
+export interface IConfig {
+  testIdAttribute: string
+}
+
+export interface IConfigFn {
+  (existingConfig: IConfig): Partial<IConfig>
+}
+
+export function configure(configDelta: Partial<IConfig> | IConfigFn): void

typings/index.d.ts

@@ -15,3 +15,4 @@ export * from './get-node-text'
 export * from './events'
 export * from './get-queries-for-element'
 export * from './pretty-dom'
+export * from './config'