Skip to content

Commit 72e890d

Browse files
author
Mark Skelton
authored
v2 (#9)
* Remove support for jest-playwright * Make `matchers` the default export * Require page, frame, or locators for assertions * Update license * HTML reports * Allow configuration of default options * Frame locators * More change notes * Docs * Node versions * Update reporter * Support frame locators * Update deps * Update Yarn * Update all deps * Remove workflow * Auto retry assertions * Working version * Add timeout tests * Update timeout * Fix timeout * Less flaky polling
1 parent 6fb689f commit 72e890d

27 files changed

+1437
-1182
lines changed

‎.changeset/eleven-hairs-fold.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'expect-axe-playwright': major
3+
---
4+
5+
Remove support for jest-playwright.

‎.changeset/fuzzy-geckos-smash.md

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
'expect-axe-playwright': major
3+
---
4+
5+
Remove support for resolving iframes from element handles. Please use [`FrameLocator`s](https://playwright.dev/docs/api/class-framelocator) instead.
6+
7+
```diff
8+
-expect(page.$('iframe')).toBeAccessible()
9+
+expect(page.frameLocator('iframe')).toBeAccessible()
10+
```

‎.changeset/good-scissors-divide.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'expect-axe-playwright': minor
3+
---
4+
5+
Attach HTML report with full violation details to each failed test.

‎.changeset/hot-snails-cheat.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'expect-axe-playwright': minor
3+
---
4+
5+
Add ability to configure default rule settings in the Playwright config file.

‎.changeset/serious-melons-relate.md

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
'expect-axe-playwright': major
3+
---
4+
5+
Remove support for element handles. Please use locators instead.
6+
7+
```diff
8+
-expect(page.$('button')).toBeAccessible()
9+
+expect(page.locator('button')).toBeAccessible()
10+
```

‎.changeset/witty-worms-bow.md

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
'expect-axe-playwright': major
3+
---
4+
5+
Make `matchers` the default export.
6+
7+
```diff
8+
-import { matchers } from 'expect-axe-playwright'
9+
+import matchers from 'expect-axe-playwright'
10+
```

‎.github/workflows/build.yml

+2-2
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ jobs:
55
runs-on: ubuntu-latest
66
strategy:
77
matrix:
8-
node-version: [12.x, 14.x, 16.x]
8+
node-version: [14.x, 16.x]
99
steps:
1010
- uses: actions/checkout@v2
1111
- name: Use Node.js ${{ matrix.node-version }}
@@ -29,7 +29,7 @@ jobs:
2929
fetch-depth: 0
3030
- uses: actions/setup-node@v2
3131
with:
32-
node-version: 14.x
32+
node-version: 16.x
3333
cache: yarn
3434
- run: yarn install --immutable
3535
- name: Create release pull request or publish to npm

‎.github/workflows/format.yml

-21
This file was deleted.

‎.gitignore

+2-1
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
.vscode/
2-
node_modules/
32
lib/
3+
test-results/
44

55
# Yarn
6+
node_modules/
67
.yarn/*
78
!.yarn/releases
89
!.yarn/plugins

‎.prettierrc

+1-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
{
22
"semi": false,
3-
"singleQuote": true,
4-
"proseWrap": "always"
3+
"singleQuote": true
54
}

‎.yarn/plugins/@yarnpkg/plugin-outdated.cjs

+1-1
Large diffs are not rendered by default.

‎.yarn/releases/yarn-3.1.0.cjs ‎.yarn/releases/yarn-3.1.1.cjs

+150-150
Large diffs are not rendered by default.

‎.yarnrc.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,4 @@ plugins:
44
- path: .yarn/plugins/@yarnpkg/plugin-outdated.cjs
55
spec: "https://mskelton.dev/yarn-outdated/v2"
66

7-
yarnPath: .yarn/releases/yarn-3.1.0.cjs
7+
yarnPath: .yarn/releases/yarn-3.1.1.cjs

‎CONTRIBUTING.md

-10
Original file line numberDiff line numberDiff line change
@@ -35,13 +35,3 @@ yarn changeset
3535
After running this command, a new markdown file will be created in the
3636
`.changeset` folder. These files should be pushed to your branch and if you make
3737
a mistake, you can amend them at any time.
38-
39-
### Snapshot releases
40-
41-
When commits are pushed to a branch, snapshot releases will be published.
42-
Snapshot releases are not meant for production use, but can be installed in your
43-
application for testing purposes.
44-
45-
```sh
46-
yarn add [email protected]
47-
```

‎LICENSE

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
ISC License
22

3-
Copyright (c) 2021, Widen Enterprises, Inc.
3+
Copyright (c) 2022, Widen Enterprises, Inc.
44

55
Permission to use, copy, modify, and/or distribute this software for any
66
purpose with or without fee is hereby granted, provided that the above

‎README.md

+44-25
Original file line numberDiff line numberDiff line change
@@ -22,21 +22,10 @@ yarn add expect-axe-playwright
2222

2323
## Usage
2424

25-
### With [Playwright test runner](https://playwright.dev/docs/test-intro/)
26-
2725
```ts
2826
// playwright.config.ts
2927
import { expect } from '@playwright/test'
30-
import { matchers } from 'expect-axe-playwright'
31-
32-
expect.extend(matchers)
33-
```
34-
35-
### With Jest
36-
37-
```js
38-
// setup-jest.js
39-
import { matchers } from 'expect-axe-playwright'
28+
import matchers from 'expect-axe-playwright'
4029

4130
expect.extend(matchers)
4231
```
@@ -53,16 +42,17 @@ the rescue with the following features.
5342
- Direct integration with the `expect` API for simplicity and better error
5443
messaging.
5544
- Automatic Axe script injection.
56-
- Works with pages, frames, and element handles.
57-
- Automatic promise and frame resolution.
45+
- Auto-retry until timeout.
46+
- Works with [pages], [frames], and [locators].
47+
- HTML report with full violation details.
48+
- Project-level option configuration.
5849

5950
Here are a few examples:
6051

6152
```js
6253
await expect(page).toBeAccessible() // Page
63-
await expect(page).toBeAccessible('#foo') // Page + selector
64-
await expect(page.$('#foo')).toBeAccessible() // Element handle
65-
await expect(page.$('iframe')).toBeAccessible() // Iframe
54+
await expect(page.locator('#foo')).toBeAccessible() // Locator
55+
await expect(page.frameLocator('iframe')).toBeAccessible() // Frame locator
6656
```
6757

6858
## API Documentation
@@ -77,24 +67,53 @@ You can test the entire page:
7767
await expect(page).toBeAccessible()
7868
```
7969

80-
Or pass a selector to test part of the page:
70+
Or pass a locator to test part of the page:
8171

8272
```js
83-
await expect(element).toBeAccessible('#my-element')
73+
await expect(page.locator('#my-element')).toBeAccessible()
8474
```
8575

86-
Or pass a Playwright [ElementHandle]:
76+
#### Axe run options
77+
78+
You can configure options that should be passed to aXe at the project or
79+
assertion level.
80+
81+
To configure a single assertion to use a different set of options, pass an
82+
object with the desired arguments to the matcher.
8783

8884
```js
89-
const element = await page.$('#my-element')
90-
await expect(element).toBeAccessible()
85+
await expect(page).toBeAccessible({
86+
rules: {
87+
'color-contrast': { enabled: false },
88+
},
89+
})
90+
```
91+
92+
To configure the entire project to use a different set of options, specify
93+
options in `use.axeOptions` in your Playwright config file.
94+
95+
```ts
96+
// playwright.config.ts
97+
import { PlaywrightTestConfig } from '@playwright/test'
98+
99+
const config: PlaywrightTestConfig = {
100+
use: {
101+
axeOptions: {
102+
rules: {
103+
'color-contrast': { enabled: false },
104+
},
105+
},
106+
},
107+
}
108+
109+
export default config
91110
```
92111

93112
## Thanks
94113

95-
- [expect-playwright](https://github.com/playwright-community/expect-playwright)
96-
for the rock solid foundation for writing Playwright matchers.
97114
- [axe-playwright](https://github.com/abhinaba-ghosh/axe-playwright) for the
98115
inspiration and groundwork laid for using Axe with Playwright.
99116

100-
[elementhandle]: https://playwright.dev/docs/api/class-elementhandle/
117+
[pages]: https://playwright.dev/docs/api/class-page
118+
[frames]: https://playwright.dev/docs/api/class-frame
119+
[locators]: https://playwright.dev/docs/api/class-locator

‎global.d.ts

+11-28
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,32 @@
11
import { RunOptions } from 'axe-core'
22

3+
declare module '@playwright/test' {
4+
export interface PlaywrightTestOptions {
5+
axeOptions?: RunOptions
6+
}
7+
}
8+
39
interface MatcherOptions extends RunOptions {
410
/**
5-
* Defaults to `'visible'`. Can be either:
6-
* - `'attached'` - wait for element to be present in DOM.
7-
* - `'detached'` - wait for element to not be present in DOM.
8-
* - `'visible'` - wait for element to have non-empty bounding box and no
9-
* `visibility:hidden`. Note that element without any content or with
10-
* `display:none` has an empty bounding box and is not considered visible.
11-
* - `'hidden'` - wait for element to be either detached from DOM, or have
12-
* an empty bounding box or `visibility:hidden`. This is opposite to the
13-
* `'visible'` option.
14-
*/
15-
state?: 'attached' | 'detached' | 'visible' | 'hidden'
16-
/**
17-
* Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable
18-
* timeout. The default value can be changed by using the
19-
* [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout)
20-
* or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
11+
* Maximum time in milliseconds, defaults to 5 seconds.
2112
*/
2213
timeout?: number
2314
}
2415

2516
interface AxePlaywrightMatchers<R> {
2617
/**
27-
* Verifies that the page or element is accessible.
18+
* Verifies that the page, frame, or locator is accessible.
19+
* @param options - Options to pass to axe-core. See the [axe-core documentation](https://www.deque.com/axe/core-documentation/api-documentation/#options-parameter) for more details.
2820
*/
2921
toBeAccessible(options?: MatcherOptions): Promise<R>
30-
/**
31-
* Verifies that the element identified by the given selector is accessible.
32-
*/
33-
toBeAccessible(selector: string, options?: MatcherOptions): Promise<R>
3422
}
3523

3624
declare global {
37-
namespace jest {
38-
// eslint-disable-next-line @typescript-eslint/no-empty-interface
39-
interface Matchers<R> extends AxePlaywrightMatchers<R> {}
40-
}
41-
4225
namespace PlaywrightTest {
4326
// eslint-disable-next-line @typescript-eslint/no-empty-interface
4427
interface Matchers<R> extends AxePlaywrightMatchers<R> {}
4528
}
4629
}
4730

48-
// eslint-disable-next-line @typescript-eslint/no-explicit-any
49-
export const matchers: any
31+
declare const matchers: AxePlaywrightMatchers
32+
export default matchers

‎package.json

+13-11
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
"description": "Expect matchers to perform Axe accessibility tests in your Playwright tests.",
55
"author": "Widen",
66
"license": "ISC",
7-
"packageManager": "[email protected].0",
7+
"packageManager": "[email protected].1",
88
"repository": "github:Widen/expect-axe-playwright",
99
"homepage": "https://github.com/Widen/expect-axe-playwright#readme",
1010
"bugs": {
@@ -14,8 +14,7 @@
1414
"playwright",
1515
"axe",
1616
"axe-core",
17-
"playwright-test-runner",
18-
"jest-playwright"
17+
"playwright-test"
1918
],
2019
"main": "./lib/index.js",
2120
"types": "global.d.ts",
@@ -30,15 +29,18 @@
3029
"ts": "tsc"
3130
},
3231
"dependencies": {
33-
"axe-core": "^4.3.5"
32+
"axe-core": "^4.4.1",
33+
"axe-reporter-html": "^0.0.1",
34+
"merge-deep": "^3.0.3"
3435
},
3536
"devDependencies": {
36-
"@changesets/cli": "^2.18.0",
37-
"@playwright/test": "^1.16.3",
38-
"@typescript-eslint/eslint-plugin": "^5.3.1",
39-
"@typescript-eslint/parser": "^5.3.1",
40-
"eslint": "^8.2.0",
41-
"prettier": "^2.4.1",
42-
"typescript": "^4.4.4"
37+
"@changesets/cli": "^2.20.0",
38+
"@playwright/test": "^1.19.0",
39+
"@types/merge-deep": "^3.0.0",
40+
"@typescript-eslint/eslint-plugin": "^5.11.0",
41+
"@typescript-eslint/parser": "^5.11.0",
42+
"eslint": "^8.8.0",
43+
"prettier": "^2.5.1",
44+
"typescript": "^4.5.5"
4345
}
4446
}

‎playwright.config.ts

+17-3
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,23 @@
11
import { expect, PlaywrightTestConfig } from '@playwright/test'
2-
import { matchers } from './src'
2+
import { RunOptions } from 'axe-core'
3+
import matchers from './src'
34

45
expect.extend(matchers)
56

6-
export default {
7+
declare module '@playwright/test' {
8+
export interface PlaywrightTestOptions {
9+
axeOptions?: RunOptions
10+
}
11+
}
12+
13+
const config: PlaywrightTestConfig = {
714
globalSetup: require.resolve('./src/config/globalSetup'),
815
testDir: 'src',
9-
} as PlaywrightTestConfig
16+
use: {
17+
axeOptions: {
18+
rules: { 'empty-heading': { enabled: false } },
19+
},
20+
},
21+
}
22+
23+
export default config

‎src/index.ts

+2-1
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
1-
export { default as matchers } from './matchers'
1+
import matchers from './matchers'
2+
export default matchers

0 commit comments

Comments
 (0)