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}

lib/extend.ts

@@ -4,19 +4,25 @@
   "description": "playwright + dom-testing-library",
   "main": "./dist/index.js",
   "scripts": {
-    "build": "npm run build:types && npm run build:rollup",
-    "build:rollup": "rollup -c rollup.config.js",
-    "build:types": "tsc",
+    "build": "run-s clean build:testing-library build:source",
+    "build:source": "tsc",
+    "build:testing-library": "rollup -c",
     "ci-after-success": "hover-scripts ci-after-success",
-    "clean": "rm -fR dist/",
+    "clean": "rimraf dist/*",
     "commit-msg": "hover-scripts commit-msg",
     "lint": "hover-scripts lint",
     "pre-commit": "hover-scripts pre-commit --no-toc",
     "prepare": "husky install",
-    "prepublishOnly": "npm run rebuild && generate-export-aliases",
-    "rebuild": "npm run clean && npm run build",
-    "test": "hover-scripts test",
-    "validate": "hover-scripts validate 'lint,test --coverage --runInBand --verbose'"
+    "prepare:playwright-test": "run-s prepare:playwright-test:package prepare:playwright-test:imports build:source prepare:playwright-test:entries",
+    "prepare:playwright-test:entries": "generate-export-aliases",
+    "prepare:playwright-test:imports": "./playwright-test/prepare-package.js",
+    "prepare:playwright-test:package": "jscodeshift -t ./playwright-test/rename-imports.ts --extensions=ts --parser=ts ./lib",
+    "prepublishOnly": "npm run build",
+    "test": "run-s build:testing-library test:*",
+    "test:fixture": "playwright test",
+    "test:standalone": "hover-scripts test --no-watch",
+    "test:types": "tsc --noEmit",
+    "validate": "run-s test"
   },
   "repository": {
     "type": "git",
@@ -37,7 +43,7 @@
   ],
   "config": {
     "exportAliases": {
-      "extend": "./dist/extend"
+      "fixture": "./dist/fixture"
     }
   },
   "dependencies": {
@@ -51,16 +57,20 @@
     "@rollup/plugin-node-resolve": "^13.0.5",
     "@rollup/plugin-replace": "^3.0.0",
     "@types/jest": "^27.0.2",
+    "@types/jscodeshift": "^0.11.2",
     "generate-export-aliases": "^1.1.0",
     "husky": "^7.0.2",
+    "jscodeshift": "^0.13.0",
+    "npm-run-all": "^4.1.5",
     "playwright": "^1.15.1",
+    "rimraf": "^3.0.2",
     "rollup": "^2.58.0",
     "setimmediate": "^1.0.5",
     "typescript": "^4.4.3"
   },
   "peerDependencies": {
-    "playwright": "^1.1.0",
-    "@playwright/test": "^1.12.0"
+    "@playwright/test": "^1.12.0",
+    "playwright": "^1.12.0"
   },
   "peerDependenciesMeta": {
     "playwright": {

lib/fixture.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+const fs = require('fs/promises')
+const path = require('path')
+
+const PACKAGE = path.join(__dirname, '..', 'package.json')
+
+const run = async () => {
+  const package = JSON.parse(await fs.readFile(PACKAGE, {encoding: 'utf-8'}))
+
+  const modifiedPackage = {
+    ...package,
+    name: '@playwright-testing-library/test',
+  }
+
+  await fs.writeFile(PACKAGE, JSON.stringify(modifiedPackage, undefined, 2))
+}
+
+run()
+  .then(() => process.exit(0))
+  .catch(error => {
+    console.error(error)
+    process.exit(1)
+  })

package.json

@@ -0,0 +1,11 @@
+import {API, FileInfo} from 'jscodeshift'
+
+const transformer = (file: FileInfo, {jscodeshift: j}: API) =>
+  j(file.source)
+    .find(j.ImportDeclaration)
+    .find(j.StringLiteral)
+    .filter(path => path.value.value === 'playwright')
+    .replaceWith(() => j.stringLiteral('@playwright/test'))
+    .toSource()
+
+export default transformer