Allow screen to use custom queries

[danieljcafonso]

Describe the feature you'd like:

Hey everyone 😄
I'd like to when using the screen object to be able to use custom queries previously created with the buildQueries helper.

Suggested implementation:

To avoid potential breaking changes and keeping screen as an object, I'd suggest creating an initializeScreen function that would take a custom queries object as a parameter and return a new screen object.

• This function would take the current code assigned to the screen object and return a new screen object every time it was called.
• We could also use it to instantiate the default screen.

Regarding implementation, I'd say it would be like this:

import * as defaultQueries from './queries'

...

export const initializeScreen = customQueries => {
  const queries = {...defaultQueries, ...customQueries}

  return typeof document !== 'undefined' && document.body
    ? getQueriesForElement(document.body, queries, {debug})
    : Object.keys(queries).reduce(
        (helpers, key) => {
          helpers[key] = () => {
            throw new TypeError(
              'For queries bound to document.body a global document has to be available... Learn more: https://testing-library.com/s/screen-global-error',
            )
          }
          return helpers
        },
        {debug},
      )
}

export const screen = initializeScreen()

Teachability, Documentation, Adoption, Migration Strategy:

1. The users can import the initializeScreen on some test-utils file they may have.
2. They call the function with their custom queries and obtain a new screen object that references it
3. They can re-export that screen as the default one and use it on their tests.

[alexkrolick]

Will this work?

// custom renderer
// pre-bind custom queries to document body
const customScreen = { ...screen, ...customQueries }
export customScreen as screen

Another thing is that render still returns bound queries, so it almost makes sense to make queries a configurable option

[danieljcafonso]

Will this work?

// custom renderer
// pre-bind custom queries to document body
const customScreen = { ...screen, ...customQueries }
export customScreen as screen

Another thing is that render still returns bound queries, so it almost makes sense to make queries a configurable option

Hey @alexkrolick,

when I try that approach I get the following error:
container.querySelectorAll is not a function

I replicated the issue on codesanbox https://codesandbox.io/s/react-testing-library-demo-08loc

[alexkrolick]

The "prebind queries part" needs something like this, unless you have default arguments for the container element in the query:

// pre-bind custom queries to document body
const boundQueries = Object.entries(customQueries).reduce(
  (queries, [queryName, queryFn]) => {
    queries[queryName] = queryFn.bind(null, document.body);
    return queries;
  },
  {}
);
const customScreen = { ...screen, ...boundQueries };

[timdeschryver]

FWIW, I needed to do this recently for the Angular Testing Library - this is how I did it.

Re-export screen:
testing-library/angular-testing-library@289c08b#diff-31c0eb2056cc7319c719fc39d70e4d7aR305

Helper method to replace the queries I needed to replace (for screen and for the render bound queries)
testing-library/angular-testing-library@289c08b#diff-31c0eb2056cc7319c719fc39d70e4d7aR247

[danieljcafonso]

Thank you, @alexkrolick and @timdeschryver 😄
This has been really helpful, closing this issue!

[Sultanyaron]

The "prebind queries part" needs something like this, unless you have default arguments for the container element in the query:

// pre-bind custom queries to document body
const boundQueries = Object.entries(customQueries).reduce(
  (queries, [queryName, queryFn]) => {
    queries[queryName] = queryFn.bind(null, document.body);
    return queries;
  },
  {}
);
const customScreen = { ...screen, ...boundQueries };

With typescript:

import { screen, BoundFunctions } from '@testing-library/react';
import { customQueries } from './queries/queries';

const boundQueries = Object.entries(customQueries).reduce((queries, [queryName, queryFn]) => {
  // eslint-disable-next-line no-param-reassign
  queries[queryName] = queryFn.bind(null, document.body);
  return queries;
}, {} as BoundFunctions<typeof customQueries>);

const customScreen = { ...screen, ...boundQueries };

export default customScreen;

[RandomDude123]

You can use within to do the binding.

import { screen, within } from '@testing-library/react';
import { customQueries } from './queries/queries';

const boundQueries = within<typeof customQueries>(document.body, customQueries);

const customScreen = { ...screen, ...boundQueries };

export default customScreen;