feat: add support for @playwright/test via fixture

Going forward, two packages will be published:
- **playwright-testing-library** to support the standalone queries with the
  **playwright** package (no longer supports extending the Playwright
  prototypes via `/extend`)
- **@playwright-testing-library/test** to support both standalone queries with
  **@playwright/test** _as well as_ a Playwright Test
  [fixture](https://playwright.dev/docs/test-fixtures) (available at
  `@playwright-testing-library/test/fixture`)

BREAKING CHANGE: Removes support for extending Playwright prototypes (`/extend`
entrypoint) BREAKING CHANGE: Only Playwright 1.12+ is officially supported
going forward

Co-authored-by: Zacharias Björngren <[email protected]>

Author: jrolfs

.eslintrc.js

@@ -12,4 +12,12 @@ module.exports = {
     'no-restricted-syntax': 'off',
     'no-underscore-dangle': ['error', {allow: ['__regex', '__flags']}],
   },
+  overrides: [
+    {
+      files: ['playwright-test/*.+(js|ts)'],
+      rules: {
+        'import/no-extraneous-dependencies': ['error', {devDependencies: true}],
+      },
+    },
+  ],
 }

.github/workflows/build.yml

@@ -30,7 +30,7 @@ jobs:
     strategy:
       matrix:
         node: ['12', '14', '16']
-        playwright: ['1.1.0', 'latest']
+        playwright: ['1.12.0', 'latest']
 
     steps:
       - name: Checkout
@@ -40,9 +40,9 @@ jobs:
         uses: actions/setup-node@master
         with:
           node-version: ${{ matrix.node }}
-          
+
       - name: Update to npm 7
-        run: npm i -g npm@7 --registry=https://registry.npmjs.org  
+        run: npm i -g npm@7 --registry=https://registry.npmjs.org
 
       - uses: actions/cache@v2
         with:
@@ -54,27 +54,31 @@ jobs:
       - name: Install dependencies
         run: npm install
 
-      # Old versions of Playwright (<= 1.1.0) fail on Node 16
-
       - name: Install specific Playwright version
-        if: ${{ !(matrix.node == '16' && matrix.playwright == '1.1.0')  }}
         run: |
           npm install playwright@${{ matrix.playwright }}
-          npm why playwright
+          npm install @playwright/test@${{ matrix.playwright }}
 
-      - name: Build
-        if: ${{ !(matrix.node == '16' && matrix.playwright == '1.1.0')  }}
-        run: npm run rebuild
-
-      - name: Run lint + tests
-        if: ${{ !(matrix.node == '16' && matrix.playwright == '1.1.0')  }}
-        run: npm run validate
+      - name: Check types, run lint + tests
+        run: |
+          npm why playwright
+          npm why @playwright/test
+          npm run validate
 
       # Only release on Node 14
 
-      - name: Upload Coverage / Release
+      - name: Upload Coverage / Release / Playwright
         run: npm run ci-after-success
-        if: ${{ matrix.node == '14' }}
+        if: ${{ matrix.node == '14' && matrix.playwright == 'latest' }}
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Upload Coverage / Release / Playwright Test
+        run: |
+          npm run prepare:playwright-test
+          npm run ci-after-success
+        if: ${{ matrix.node == '14' && matrix.playwright == 'latest' }}
         env:
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -5,7 +5,7 @@ dist/
 yarn-error.log
 
 dom-testing-library.js
-extend.js
-extend.d.ts
+fixture.js
+fixture.d.ts
 
 .vscode/

.husky/commit-msg

@@ -1,4 +1,4 @@
 #!/bin/sh
 . "$(dirname "$0")/_/husky.sh"
 
-yarn hover-scripts commit-msg
+npm run commit-msg

.husky/pre-commit

@@ -1,4 +1,4 @@
 #!/bin/sh
 . "$(dirname "$0")/_/husky.sh"
 
-yarn hover-scripts pre-commit --no-toc
+npm run pre-commit

README.md

@@ -29,8 +29,8 @@
 
 All of your favorite user-centric querying functions from **@testing-library/react** and **@testing-library/dom** available from Playwright!
 
-- Standalone queries — **`playwright-testing-library`** or...
-- Playwright extensions — **`playwright-testing-library/extend`**
+- Playwright Test [fixture](https://playwright.dev/docs/test-fixtures) — **`@playwright-testing-library/test/fixture`** or...
+- Standalone queries — **`playwright-testing-library`**/**`@playwright-testing-library/test`**
 - Asynchronous assertion helper (via **[wait-for-expect](https://github.com/TheBrainFamily/wait-for-expect)**)
 
 ## 🌱 Getting Started
@@ -47,53 +47,66 @@ or
 yarn add --dev playwright-testing-library
 ```
 
-### 2a. Use _standalone queries_
+### 2a. Use _Playwright Test [fixture](https://playwright.dev/docs/test-fixtures)_
 
-```js
-const {webkit} = require('playwright') // or 'firefox' or 'chromium'
-const {getDocument, queries} = require('playwright-testing-library')
+```ts
+import {test as baseTest} from '@playwright/test'
+import {fixtures, TestingLibraryFixtures} from '@playwright-testing-library/test/fixture'
 
-const {getByTestId, getByLabelText} = queries
+// As only fixture
+const test = baseTest.extend<TestingLibraryFixtures>(fixtures)
 
-const browser = await webkit.launch()
-const page = await browser.newPage()
+// Alternatively, with other fixtures
+interface Fixtures extends TestingLibraryFixtures {
+  // ... additional fixture types
+}
 
-// Grab ElementHandle for document
-const $document = await getDocument(page)
+const test = baseTest.extend<Fixtures>({
+  ...fixtures,
+  // ... additional fixtures
+})
 
-// Your favorite query methods are available
-const $form = await getByTestId($document, 'my-form')
+const {expect} = test
 
-// Returned elements are ElementHandles too!
-const $email = await getByLabelText($form, 'Email')
+// Query methods are available in `test` blocks
+test('my form', ({queries: {getByTestId}}) => {
+  const $form = await getByTestId('my-form')
 
-// Interact with playwright like usual
-await $email.type('[email protected]')
+  // Scope queries with `getQueriesForElement`
+  const {getByLabelText} = $form.getQueriesForElement()
 
-// ...
+  const $email = await getByLabelText('Email')
+
+  // Interact with Playwright like usual
+  await $email.type('[email protected]')
+
+  expect($email).toHaveValue('[email protected]')
+
+  // ...
+})
 ```
 
-### 2b. Use _extensions_
+### 2b. Use _standalone queries_
 
 ```js
 const {webkit} = require('playwright') // or 'firefox' or 'chromium'
-require('playwright-testing-library/extend')
+const {getDocument, queries} = require('playwright-testing-library')
+
+const {getByTestId, getByLabelText} = queries
 
 const browser = await webkit.launch()
 const page = await browser.newPage()
 
-// Grab document with `getDocument`, which is added to the prototype of `Paqe`
-const $document = await page.getDocument()
-
-// Query methods are added directly to prototype of `ElementHandle`
-const $form = await $document.getByTestId('my-form')
+// Grab ElementHandle for document
+const $document = await getDocument(page)
 
-// Scope queries with `getQueriesForElement`
-const {getByLabelText} = $form.getQueriesForElement()
+// Your favorite query methods are available
+const $form = await getByTestId($document, 'my-form')
 
-const $email = await getByLabelText('Email')
+// Returned elements are ElementHandles too!
+const $email = await getByLabelText($form, 'Email')
 
-// Interact with Playwright like usual
+// Interact with playwright like usual
 await $email.type('[email protected]')
 
 // ...

rollup.input.js renamed to dom-testing-library.input.js

@@ -5,5 +5,6 @@ module.exports = {
   collectCoverageFrom: ['**/*.ts', '!**/*.d.ts'],
   coverageThreshold: {},
   setupFilesAfterEnv: ['./jest.setup.ts'],
-  testTimeout: 15000,
+  testMatch: ['<rootDir>/test/standalone/*.+(test.js|test.jsx|test.ts|test.tsx)'],
+  testTimeout: 30000,
 }

jest.config.js

@@ -0,0 +1,20 @@
+import type {PlaywrightTestArgs, TestFixture} from '@playwright/test'
+import type {IScopedQueryUtils as Queries} from './typedefs'
+import {getDocument, getQueriesForElement} from '.'
+
+interface TestingLibraryFixtures {
+  queries: Queries
+}
+
+const fixture: TestFixture<Queries, PlaywrightTestArgs> = async ({page}, use) => {
+  const document = await getDocument(page)
+
+  const queries = getQueriesForElement(document)
+
+  await use(queries)
+}
+
+const fixtures = {queries: fixture}
+
+export {fixture, fixtures}
+export type {Queries, TestingLibraryFixtures}