feat: add find* queries (testing-library/pptr-testing-library#44)

testing-library/pptr-testing-library#44

Author: umpox

README.md

@@ -90,30 +90,48 @@ Unique methods, not part of `@testing-library/dom`
   - `queryAllByPlaceholderText`
   - `getByPlaceholderText`
   - `getAllByPlaceholderText`
+  - `findByPlaceholderText`
+  - `findAllByPlaceholderText`
   - `queryByText`
   - `queryAllByText`
   - `getByText`
   - `getAllByText`
+  - `findByText`
+  - `findAllByText`
   - `queryByLabelText`
   - `queryAllByLabelText`
   - `getByLabelText`
   - `getAllByLabelText`
+  - `findByLabelText`
+  - `findAllByLabelText`
   - `queryByAltText`
   - `queryAllByAltText`
   - `getByAltText`
   - `getAllByAltText`
+  - `findByAltText`
+  - `findAllByAltText`
   - `queryByTestId`
   - `queryAllByTestId`
   - `getByTestId`
   - `getAllByTestId`
+  - `findByTestId`
+  - `findAllByTestId`
   - `queryByTitle`
   - `queryAllByTitle`
   - `getByTitle`
   - `getAllByTitle`
+  - `findByTitle`
+  - `findAllByTitle`
+  - `queryByDisplayValue`,
+  - `queryAllByDisplayValue`,
+  - `getByDisplayValue`,
+  - `getAllByDisplayValue`,
+  - `findByDisplayValue`,
+  - `findAllByDisplayValue`,
 
 ## Known Limitations
 
-- `waitForElement` method is not exposed. Playwright has its own set of wait utilities that somewhat conflict with the style used in `@testing-library/dom`. See [#3](https://github.com/testing-library/playwright-testing-library/issues/3).
+- Async utilities `waitForElement`, `waitForElementToBeRemoved` and `waitForDomChange` are not exposed. Consider using a `find*` query.
 - `fireEvent` method is not exposed, use Playwright's built-ins instead.
 - `expect` assertion extensions are not available.
 

lib/index.ts

@@ -164,41 +164,57 @@ export function getQueriesForElement<T>(
     'queryAllByPlaceholderText',
     'getByPlaceholderText',
     'getAllByPlaceholderText',
+    'findByPlaceholderText',
+    'findAllByPlaceholderText',
 
     'queryByText',
     'queryAllByText',
     'getByText',
     'getAllByText',
+    'findByText',
+    'findAllByText',
 
     'queryByLabelText',
     'queryAllByLabelText',
     'getByLabelText',
     'getAllByLabelText',
+    'findByLabelText',
+    'findAllByLabelText',
 
     'queryByAltText',
     'queryAllByAltText',
     'getByAltText',
     'getAllByAltText',
+    'findByAltText',
+    'findAllByAltText',
 
     'queryByTestId',
     'queryAllByTestId',
     'getByTestId',
     'getAllByTestId',
+    'findByTestId',
+    'findAllByTestId',
 
     'queryByTitle',
     'queryAllByTitle',
     'getByTitle',
     'getAllByTitle',
+    'findByTitle',
+    'findAllByTitle',
 
     'queryByRole',
     'queryAllByRole',
     'getByRole',
     'getAllByRole',
+    'findByRole',
+    'findAllByRole',
 
     'queryByDisplayValue',
     'queryAllByDisplayValue',
     'getByDisplayValue',
     'getAllByDisplayValue',
+    'findByDisplayValue',
+    'findAllByDisplayValue',
   ]
   functionNames.forEach(functionName => {
     o[functionName] = createDelegateFor(functionName, contextFn)

lib/typedefs.ts

@@ -1,4 +1,4 @@
-import {Matcher, MatcherOptions, SelectorMatcherOptions} from '@testing-library/dom'
+import {Matcher, MatcherOptions, SelectorMatcherOptions, waitForOptions} from '@testing-library/dom'
 import {ElementHandle as PlaywrightElementHandle} from 'playwright'
 
 export type ElementHandle = PlaywrightElementHandle<SVGElement | HTMLElement>
@@ -10,57 +10,160 @@ interface IQueryMethods {
   queryAllByPlaceholderText(el: Element, m: Matcher, opts?: MatcherOptions): Promise<Element[]>
   getByPlaceholderText(el: Element, m: Matcher, opts?: MatcherOptions): Promise<Element>
   getAllByPlaceholderText(el: Element, m: Matcher, opts?: MatcherOptions): Promise<Element[]>
+  findByPlaceholderText(
+    el: Element,
+    m: Matcher,
+    opts?: SelectorMatcherOptions,
+    waitForOpts?: waitForOptions,
+  ): Promise<Element>
+  findAllByPlaceholderText(
+    el: Element,
+    m: Matcher,
+    opts?: SelectorMatcherOptions,
+    waitForOpts?: waitForOptions,
+  ): Promise<Element[]>
 
   queryByText(el: Element, m: Matcher, opts?: SelectorMatcherOptions): Promise<Element | null>
   queryAllByText(el: Element, m: Matcher, opts?: SelectorMatcherOptions): Promise<Element[]>
   getByText(el: Element, m: Matcher, opts?: SelectorMatcherOptions): Promise<Element>
   getAllByText(el: Element, m: Matcher, opts?: SelectorMatcherOptions): Promise<Element[]>
+  findByText(
+    el: Element,
+    m: Matcher,
+    opts?: SelectorMatcherOptions,
+    waitForOpts?: waitForOptions,
+  ): Promise<Element>
+  findAllByText(
+    el: Element,
+    m: Matcher,
+    opts?: SelectorMatcherOptions,
+    waitForOpts?: waitForOptions,
+  ): Promise<Element[]>
 
   queryByLabelText(el: Element, m: Matcher, opts?: SelectorMatcherOptions): Promise<Element | null>
   queryAllByLabelText(el: Element, m: Matcher, opts?: SelectorMatcherOptions): Promise<Element[]>
   getByLabelText(el: Element, m: Matcher, opts?: SelectorMatcherOptions): Promise<Element>
   getAllByLabelText(el: Element, m: Matcher, opts?: SelectorMatcherOptions): Promise<Element[]>
+  findByLabelText(
+    el: Element,
+    m: Matcher,
+    opts?: SelectorMatcherOptions,
+    waitForOpts?: waitForOptions,
+  ): Promise<Element>
+  findAllByLabelText(
+    el: Element,
+    m: Matcher,
+    opts?: SelectorMatcherOptions,
+    waitForOpts?: waitForOptions,
+  ): Promise<Element[]>
 
   queryByAltText(el: Element, m: Matcher, opts?: MatcherOptions): Promise<Element | null>
   queryAllByAltText(el: Element, m: Matcher, opts?: MatcherOptions): Promise<Element[]>
   getByAltText(el: Element, m: Matcher, opts?: MatcherOptions): Promise<Element>
   getAllByAltText(el: Element, m: Matcher, opts?: MatcherOptions): Promise<Element[]>
+  findByAltText(
+    el: Element,
+    m: Matcher,
+    opts?: SelectorMatcherOptions,
+    waitForOpts?: waitForOptions,
+  ): Promise<Element>
+  findAllByAltText(
+    el: Element,
+    m: Matcher,
+    opts?: SelectorMatcherOptions,
+    waitForOpts?: waitForOptions,
+  ): Promise<Element[]>
 
   queryByTestId(el: Element, m: Matcher, opts?: MatcherOptions): Promise<Element | null>
   queryAllByTestId(el: Element, m: Matcher, opts?: MatcherOptions): Promise<Element[]>
   getByTestId(el: Element, m: Matcher, opts?: MatcherOptions): Promise<Element>
   getAllByTestId(el: Element, m: Matcher, opts?: MatcherOptions): Promise<Element[]>
+  findByTestId(
+    el: Element,
+    m: Matcher,
+    opts?: SelectorMatcherOptions,
+    waitForOpts?: waitForOptions,
+  ): Promise<Element>
+  findAllByTestId(
+    el: Element,
+    m: Matcher,
+    opts?: SelectorMatcherOptions,
+    waitForOpts?: waitForOptions,
+  ): Promise<Element[]>
 
   queryByTitle(el: Element, m: Matcher, opts?: MatcherOptions): Promise<Element | null>
   queryAllByTitle(el: Element, m: Matcher, opts?: MatcherOptions): Promise<Element[]>
   getByTitle(el: Element, m: Matcher, opts?: MatcherOptions): Promise<Element>
   getAllByTitle(el: Element, m: Matcher, opts?: MatcherOptions): Promise<Element[]>
+  findByTitle(
+    el: Element,
+    m: Matcher,
+    opts?: SelectorMatcherOptions,
+    waitForOpts?: waitForOptions,
+  ): Promise<Element>
+  findAllByTitle(
+    el: Element,
+    m: Matcher,
+    opts?: SelectorMatcherOptions,
+    waitForOpts?: waitForOptions,
+  ): Promise<Element[]>
 
   queryByRole(el: Element, m: Matcher, opts?: MatcherOptions): Promise<Element | null>
   queryAllByRole(el: Element, m: Matcher, opts?: MatcherOptions): Promise<Element[]>
   getByRole(el: Element, m: Matcher, opts?: MatcherOptions): Promise<Element>
   getAllByRole(el: Element, m: Matcher, opts?: MatcherOptions): Promise<Element[]>
+  findByRole(
+    el: Element,
+    m: Matcher,
+    opts?: SelectorMatcherOptions,
+    waitForOpts?: waitForOptions,
+  ): Promise<Element>
+  findAllByRole(
+    el: Element,
+    m: Matcher,
+    opts?: SelectorMatcherOptions,
+    waitForOpts?: waitForOptions,
+  ): Promise<Element[]>
 
   queryByDisplayValue(el: Element, m: Matcher, opts?: MatcherOptions): Promise<Element | null>
   queryAllByDisplayValue(el: Element, m: Matcher, opts?: MatcherOptions): Promise<Element[]>
   getByDisplayValue(el: Element, m: Matcher, opts?: MatcherOptions): Promise<Element>
   getAllByDisplayValue(el: Element, m: Matcher, opts?: MatcherOptions): Promise<Element[]>
-}
-
-type IScopedQueryMethods = {
-  [K in keyof IQueryMethods]: (
+  findByDisplayValue(
+    el: Element,
     m: Matcher,
-    opts?: Parameters<IQueryMethods[K]>[2],
-  ) => ReturnType<IQueryMethods[K]>
+    opts?: SelectorMatcherOptions,
+    waitForOpts?: waitForOptions,
+  ): Promise<Element>
+  findAllByDisplayValue(
+    el: Element,
+    m: Matcher,
+    opts?: SelectorMatcherOptions,
+    waitForOpts?: waitForOptions,
+  ): Promise<Element[]>
 }
 
-export interface IScopedQueryUtils extends IScopedQueryMethods {
-  getQueriesForElement(): IQueryUtils & IScopedQueryUtils
+export type BoundFunction<T> = T extends (
+  attribute: string,
+  element: Element,
+  text: infer P,
+  options: infer Q,
+) => infer R
+  ? (text: P, options?: Q) => R
+  : T extends (a1: any, text: infer P, options: infer Q, waitForElementOptions: infer W) => infer R
+  ? (text: P, options?: Q, waitForElementOptions?: W) => R
+  : T extends (a1: any, text: infer P, options: infer Q) => infer R
+  ? (text: P, options?: Q) => R
+  : never
+export type BoundFunctions<T> = {[P in keyof T]: BoundFunction<T[P]>}
+
+export interface IScopedQueryUtils extends BoundFunctions<IQueryMethods> {
+  getQueriesForElement(): IScopedQueryUtils
   getNodeText(): Promise<string>
 }
 
 export interface IQueryUtils extends IQueryMethods {
-  getQueriesForElement(): IQueryUtils & IScopedQueryUtils
+  getQueriesForElement(): IScopedQueryUtils
   getNodeText(el: Element): Promise<string>
 }
 

test/extend.test.ts

@@ -116,6 +116,29 @@ describe('lib/extend.ts', () => {
     expect(await queryByText('Hello h3')).toBeTruthy()
   })
 
+  describe('deferred page', () => {
+    beforeEach(async () => {
+      await page.goto(`file://${path.join(__dirname, 'fixtures/late-page.html')}`)
+      document = await page.getDocument()
+    })
+
+    it('should handle the findBy* methods', async () => {
+      expect(await document.findByText('Loaded!', {}, {timeout: 7000})).toBeTruthy()
+    }, 9000)
+
+    it('should handle the findByAll* methods', async () => {
+      const elements = await document.findAllByText(/Hello/, {}, {timeout: 7000})
+      expect(elements).toHaveLength(2)
+
+      const text = await Promise.all([
+        page.evaluate(el => el.textContent, elements[0]),
+        page.evaluate(el => el.textContent, elements[1]),
+      ])
+
+      expect(text).toEqual(['Hello h1', 'Hello h2'])
+    }, 9000)
+  })
+
   afterAll(async () => {
     await browser.close()
   })

test/fixtures/late-page.html

@@ -7,6 +7,14 @@
         const loaded = document.createElement('span')
         loaded.textContent = 'Loaded!'
         document.body.appendChild(loaded)
+
+        const heading1 = document.createElement('h1')
+        heading1.textContent = 'Hello h1'
+        document.body.appendChild(heading1)
+
+        const heading2 = document.createElement('h2')
+        heading2.textContent = 'Hello h2'
+        document.body.appendChild(heading2)
       }, 5000)
     </script>
   </body>