Add function-based overload to configure()

This commit prepares the way for configure() to be used other than
just for `testIdAttribute`: it exposes the whole config internally
and upgrades the configure() function so that it can take a function
that.

I've introduced explicit tests for this more complex configuration API
and a new documentation section for it. The documentation for the
function-based configure() API could be improved with a real example
once there is a real key for which it would be useful.

Author: RoystonS

README.md

@@ -104,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)
@@ -941,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
@@ -1129,6 +1143,7 @@ Thanks goes to these people ([emoji key][emojis]):
 | [<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 -->
 
 This project follows the [all-contributors][all-contributors] specification.

src/__tests__/config.js

@@ -0,0 +1,60 @@
+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', () => {
+      configure({newKey: 123})
+      const conf = getConfig()
+      expect(conf).toMatchObject({
+        newKey: 123,
+        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 => ({
+        newKey: existingConfig.testIdAttribute + '-derived',
+      }))
+      const conf = getConfig()
+
+      // The new value should be there, and existing values should be
+      // untouched
+      expect(conf).toMatchObject({
+        testIdAttribute: 'data-testid',
+        newKey: 'data-testid-derived',
+      })
+    })
+  })
+})

src/config.js

@@ -5,12 +5,20 @@ let config = {
   testIdAttribute: 'data-testid',
 }
 
-export function configure(configDelta) {
+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,
-    ...configDelta,
+    ...newConfig,
   }
 }
-export function getTestIdAttribute() {
-  return config.testIdAttribute
+
+export function getConfig() {
+  return config
 }

src/queries.js

@@ -6,7 +6,7 @@ import {
   queryAllByAttribute,
   queryByAttribute,
 } from './query-helpers'
-import {getTestIdAttribute} from './config'
+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
@@ -149,6 +149,10 @@ 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 = (...args) =>

typings/config.d.ts

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