wip: feat: add separate fixtures export with queries that return locators

Author: jrolfs

.eslintrc.js

@@ -25,5 +25,12 @@ module.exports = {
  'jest/no-done-callback': 'off',
  },
  },
+ {
+ files: ['lib/fixture/**/*.+(js|ts)'],
+ rules: {
+ 'no-empty-pattern': 'off',
+ 'no-underscore-dangle': ['error', {allow: ['__testingLibraryReviver']}],
+ },
+ },
  ],
 }

.github/workflows/build.yml

@@ -48,10 +48,18 @@ jobs:
  npm install @playwright/test@${{ matrix.playwright }}
 
  - name: Check types, run lint + tests
+ if: ${{ matrix.playwright == 'latest' }}
  run: |
  npm why playwright
  npm why @playwright/test
- npm run validate
+ npm run test
+
+ - name: Check types, run lint + tests
+ if: ${{ matrix.playwright != 'latest' }}
+ run: |
+ npm why playwright
+ npm why @playwright/test
+ npm run test:legacy
 
  # Only release on Node 14
 

lib/fixture/helpers.ts

@@ -0,0 +1,17 @@
+const replacer = (_: string, value: unknown) => {
+ if (value instanceof RegExp) return `__REGEXP ${value.toString()}`
+
+ return value
+}
+
+const reviver = (_: string, value: string) => {
+ if (value.toString().includes('__REGEXP ')) {
+ const match = /\/(.*)\/(.*)?/.exec(value.split('__REGEXP ')[1])
+
+ return new RegExp(match![1], match![2] || '')
+ }
+
+ return value
+}
+
+export {replacer, reviver}

lib/fixture/index.ts

@@ -3,15 +3,36 @@ import {
  Queries as ElementHandleQueries,
  queriesFixture as elementHandleQueriesFixture,
 } from './element-handle'
+import {
+ Queries as LocatorQueries,
+ queriesFixture as locatorQueriesFixture,
+ registerSelectorsFixture,
+ installTestingLibraryFixture,
+} from './locator'
 
 const elementHandleFixtures: Fixtures = {queries: elementHandleQueriesFixture}
+const locatorFixtures: Fixtures = {
+ queries: locatorQueriesFixture,
+ registerSelectors: registerSelectorsFixture,
+ installTestingLibrary: installTestingLibraryFixture,
+}
 
 interface ElementHandleFixtures {
  queries: ElementHandleQueries
 }
 
+interface LocatorFixtures {
+ queries: LocatorQueries
+ registerSelectors: void
+ installTestingLibrary: void
+}
+
 export type {ElementHandleFixtures as TestingLibraryFixtures}
 export {elementHandleQueriesFixture as fixture}
 export {elementHandleFixtures as fixtures}
 
+export type {LocatorFixtures}
+export {locatorQueriesFixture}
+export {locatorFixtures}
+
 export {configure} from '..'

lib/fixture/locator.ts

@@ -0,0 +1,111 @@
+import {promises as fs} from 'fs'
+
+import type {PlaywrightTestArgs, TestFixture} from '@playwright/test'
+import {selectors} from '@playwright/test'
+
+import {queryNames} from '../common'
+import type {LocatorQueries as Queries, AllQuery, Query, SelectorEngine} from './types'
+import {replacer, reviver} from './helpers'
+
+const queriesFixture: TestFixture<Queries, PlaywrightTestArgs> = async ({page}, use) => {
+ const queries = queryNames.reduce(
+ (rest, query) => ({
+ ...rest,
+ [query]: (...args: Parameters<Queries[keyof Queries]>) =>
+ page.locator(`__testing_library__=${JSON.stringify({query, args}, replacer)}`),
+ }),
+ {} as Queries,
+ )
+
+ await use(queries)
+}
+
+const isAllQuery = (query: Query): query is AllQuery => query.includes('All')
+
+const registerSelectorsFixture: [
+ TestFixture<void, PlaywrightTestArgs>,
+ {scope: 'worker'; auto?: boolean},
+] = [
+ async ({}, use) => {
+ try {
+ await selectors.register(
+ '__testing_library__',
+ (): SelectorEngine => ({
+ query(root, selector) {
+ const testingLibrary = window.TestingLibraryDom
+ const {args, query} = JSON.parse(
+ selector,
+ window.__testingLibraryReviver,
+ ) as unknown as {
+ query: keyof Queries
+ args: Parameters<Queries[keyof Queries]>
+ }
+
+ if (isAllQuery(query))
+ throw new Error(
+ `PlaywrightTestingLibrary: the plural '${query}' was used to create this Locator`,
+ )
+
+ // @ts-expect-error
+ const result = testingLibrary[query](root, ...args)
+
+ return result
+ },
+ queryAll(root, selector) {
+ const testingLibrary = window.TestingLibraryDom
+ const {args, query} = JSON.parse(
+ selector,
+ window.__testingLibraryReviver,
+ ) as unknown as {
+ query: keyof Queries
+ args: Parameters<Queries[keyof Queries]>
+ }
+
+ // @ts-expect-error
+ const result = testingLibrary[query](root, ...args)
+
+ if (!result)
+ throw new Error(
+ `PlaywrightTestingLibrary: '${query}' was used to create this Locator and the query returned \`null\``,
+ )
+
+ return Array.isArray(result) ? result : [result]
+ },
+ }),
+ )
+ } catch (err) {
+ // eslint-disable-next-line no-console
+ console.error('Did not register testing library functions:', err)
+ }
+ await use()
+ },
+ {scope: 'worker', auto: true},
+]
+
+const installTestingLibraryFixture: [
+ TestFixture<void, PlaywrightTestArgs>,
+ {scope: 'test'; auto?: boolean},
+] = [
+ async ({context}, use) => {
+ const testingLibraryDomUmdScript = await fs.readFile(
+ // The location of the `@testing-library/dom` UMD script
+ // is found inside the `node_modules/` directory.
+ require.resolve('@testing-library/dom/dist/@testing-library/dom.umd.js'),
+ 'utf8',
+ )
+
+ // On every page load, we must ensure that both `window['TestingLibraryDom']`
+ // and `stripWrappingQuotesFromSelector` are available to our custom selectors.
+ await context.addInitScript(`
+ ${testingLibraryDomUmdScript}
+ 
+ window.__testingLibraryReviver = ${reviver.toString()};
+ `)
+
+ await use()
+ },
+ {scope: 'test', auto: true},
+]
+
+export {queriesFixture, registerSelectorsFixture, installTestingLibraryFixture}
+export type {Queries}

lib/fixture/types.ts

@@ -0,0 +1,43 @@
+import type * as TestingLibraryDom from '@testing-library/dom'
+import {Locator} from '@playwright/test'
+import {queries} from '@testing-library/dom'
+import {reviver} from './helpers'
+
+/**
+ * This type was copied across from Playwright
+ *
+ * @see {@link https://github.com/microsoft/playwright/blob/82ff85b106e31ffd7b3702aef260c9c460cfb10c/packages/playwright-core/src/client/types.ts#L108-L117}
+ */
+export type SelectorEngine = {
+ /**
+ * Returns the first element matching given selector in the root's subtree.
+ */
+ query(root: HTMLElement, selector: string): HTMLElement | null
+ /**
+ * Returns all elements matching given selector in the root's subtree.
+ */
+ queryAll(root: HTMLElement, selector: string): HTMLElement[]
+}
+
+type Queries = typeof queries
+
+type StripNever<T> = {[P in keyof T as T[P] extends never ? never : P]: T[P]}
+type ConvertQuery<Query extends Queries[keyof Queries]> = Query extends (
+ el: HTMLElement,
+ ...rest: infer Rest
+) => HTMLElement | (HTMLElement[] | null) | (HTMLElement | null)
+ ? (...args: Rest) => Locator
+ : never
+
+export type LocatorQueries = StripNever<{[K in keyof Queries]: ConvertQuery<Queries[K]>}>
+
+export type Query = keyof Queries
+export type AllQuery = Extract<Query, `${string}All${string}`>
+export type FindQuery = Extract<Query, `find${string}`>
+
+declare global {
+ interface Window {
+ TestingLibraryDom: typeof TestingLibraryDom
+ __testingLibraryReviver: typeof reviver
+ }
+}

package.json

@@ -20,10 +20,11 @@
  "prepublishOnly": "npm run build",
  "start:standalone": "hover-scripts test",
  "test": "run-s build:testing-library test:*",
+ "test:legacy": "run-s build:testing-library test:standalone test:fixture:legacy",
  "test:fixture": "playwright test",
+ "test:fixture:legacy": "playwright test test/fixture/element-handles.test.ts",
  "test:standalone": "hover-scripts test --no-watch",
- "test:types": "tsc --noEmit",
- "validate": "run-s test"
+ "test:types": "tsc --noEmit"
  },
  "repository": {
  "type": "git",

test/fixture/locators.test.ts

@@ -0,0 +1,138 @@
+import * as playwright from '@playwright/test'
+import * as path from 'path'
+import {
+ locatorFixtures as fixtures,
+ LocatorFixtures as TestingLibraryFixtures,
+} from '../../lib/fixture'
+
+const test = playwright.test.extend<TestingLibraryFixtures>(fixtures)
+
+const {expect} = test
+
+test.describe('lib/fixture.ts (locators)', () => {
+ test.beforeEach(async ({page}) => {
+ await page.goto(`file://${path.join(__dirname, '../fixtures/page.html')}`)
+ })
+
+ test('should handle the query* methods', async ({queries: {queryByText}}) => {
+ const element = queryByText('Hello h1')
+
+ expect(element).toBeTruthy()
+ expect(await element.textContent()).toEqual('Hello h1')
+ })
+
+ test('should use the new v3 methods', async ({queries: {queryByRole}}) => {
+ const element = queryByRole('presentation')
+
+ expect(element).toBeTruthy()
+ expect(await element.textContent()).toContain('Layout table')
+ })
+
+ test('should handle regex matching', async ({queries: {queryByText}}) => {
+ const element = queryByText(/HeLlO h(1|7)/i)
+
+ expect(element).toBeTruthy()
+ expect(await element.textContent()).toEqual('Hello h1')
+ })
+
+ test('should handle the get* methods', async ({queries: {getByTestId}}) => {
+ const element = getByTestId('testid-text-input')
+
+ expect(await element.evaluate(el => el.outerHTML)).toMatch(
+ `<input type="text" data-testid="testid-text-input">`,
+ )
+ })
+
+ test('handles page navigations', async ({queries: {getByText}, page}) => {
+ await page.goto(`file://${path.join(__dirname, '../fixtures/page.html')}`)
+
+ const element = getByText('Hello h1')
+
+ expect(await element.textContent()).toEqual('Hello h1')
+ })
+
+ test('should handle the get* method failures', async ({queries}) => {
+ const {getByTitle} = queries
+ // Use the scoped element so the pretty HTML snapshot is smaller
+
+ await expect(async () => getByTitle('missing').textContent()).rejects.toThrow()
+ })
+
+ test('should handle the LabelText methods', async ({queries}) => {
+ const {getByLabelText} = queries
+ const element = getByLabelText('Label A')
+
+ /* istanbul ignore next */
+ expect(await element.evaluate(el => el.outerHTML)).toMatch(
+ `<input id="label-text-input" type="text">`,
+ )
+ })
+
+ test('should handle the queryAll* methods', async ({queries}) => {
+ const {queryAllByText} = queries
+ const elements = queryAllByText(/Hello/)
+
+ expect(await elements.count()).toEqual(3)
+
+ const text = await Promise.all([
+ elements.nth(0).textContent(),
+ elements.nth(1).textContent(),
+ elements.nth(2).textContent(),
+ ])
+
+ expect(text).toEqual(['Hello h1', 'Hello h2', 'Hello h3'])
+ })
+
+ test('should handle the queryAll* methods with a selector', async ({queries}) => {
+ const {queryAllByText} = queries
+ const elements = queryAllByText(/Hello/, {selector: 'h2'})
+
+ expect(await elements.count()).toEqual(1)
+
+ expect(await elements.textContent()).toEqual('Hello h2')
+ })
+
+ test('should handle the getBy* methods with a selector', async ({queries}) => {
+ const {getByText} = queries
+ const element = getByText(/Hello/, {selector: 'h2'})
+
+ expect(await element.textContent()).toEqual('Hello h2')
+ })
+
+ test('should handle the getBy* methods with a regex name', async ({queries}) => {
+ const {getByRole} = queries
+ const element = getByRole('button', {name: /getBy.*Test/})
+
+ expect(await element.textContent()).toEqual('getByRole Test')
+ })
+
+ test('supports `hidden` option when querying by role', async ({queries: {queryAllByRole}}) => {
+ const elements = queryAllByRole('img')
+ const hiddenElements = queryAllByRole('img', {hidden: true})
+
+ expect(await elements.count()).toEqual(1)
+ expect(await hiddenElements.count()).toEqual(2)
+ })
+
+ test.describe('querying by role with `level` option', () => {
+ test('retrieves the correct elements when querying all by role', async ({
+ queries: {queryAllByRole},
+ }) => {
+ const elements = queryAllByRole('heading')
+ const levelOneElements = queryAllByRole('heading', {level: 3})
+
+ expect(await elements.count()).toEqual(3)
+ expect(await levelOneElements.count()).toEqual(1)
+ })
+
+ test('does not throw when querying for a specific element', async ({queries: {getByRole}}) => {
+ expect.assertions(1)
+
+ await expect(getByRole('heading', {level: 3}).textContent()).resolves.not.toThrow()
+ })
+ })
+
+ // TODO: scoped queries with `within`
+ // TODO: configuration
+ // TDOO: deferred page (do we need some alternative to `findBy*`?)
+})