eslint-plugin-cypress 4.0.0 → 4.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.node-version +1 -1
- package/.nvmrc +1 -1
- package/ESLINTRC-CONFIG.md +147 -0
- package/FLAT-CONFIG.md +2 -141
- package/README.md +123 -114
- package/circle.yml +4 -4
- package/docs/rules/no-xpath.md +25 -0
- package/eslint.config.mjs +0 -4
- package/legacy.js +1 -0
- package/lib/flat.js +1 -0
- package/lib/rules/no-xpath.js +35 -0
- package/package.json +4 -5
- package/tests/lib/rules/no-xpath.js +30 -0
package/.node-version
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
|
|
1
|
+
22.11.0
|
package/.nvmrc
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
|
|
1
|
+
22.11.0
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
# Cypress ESLint Plugin - Legacy Config
|
|
2
|
+
|
|
3
|
+
This document supplements the [README](./README.md) document and describes how to use the Cypress ESLint Plugin (`eslint-plugin-cypress`) in a [deprecated ESLint legacy config environment](https://eslint.org/docs/latest/use/configure/configuration-files-deprecated). The use of flat configurations with this plugin is described in the [README](./README.md) document.
|
|
4
|
+
|
|
5
|
+
Usage with ESLint `9.x` is described.
|
|
6
|
+
|
|
7
|
+
## Deprecations
|
|
8
|
+
|
|
9
|
+
The use of `eslintrc` configurations with `eslint-plugin-cypress` is deprecated and support will be removed in a future version of this plugin. This is tied in to the ESLint announcement in the blog post [Flat config rollout plans](https://eslint.org/blog/2023/10/flat-config-rollout-plans/) from October 2023 which describes that the `eslintrc` configuration system is planned to be removed in the future ESLint `v10.0.0`. Users are encouraged to migrate to using a [flat configuration](https://eslint.org/docs/latest/use/configure/configuration-files).
|
|
10
|
+
|
|
11
|
+
## Installation
|
|
12
|
+
|
|
13
|
+
Use a minimum ESLint `9.x`.
|
|
14
|
+
|
|
15
|
+
```shell
|
|
16
|
+
npm install eslint eslint-plugin-cypress --save-dev
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
or
|
|
20
|
+
|
|
21
|
+
```shell
|
|
22
|
+
yarn add eslint eslint-plugin-cypress --dev
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## Usage
|
|
26
|
+
|
|
27
|
+
To use a deprecated configuration with ESLint `v9`, such as `.eslintrc.json`, you must set the `ESLINT_USE_FLAT_CONFIG` environment variable to `false` (see [ESLint v9 > Configuration Files (Deprecated)](https://eslint.org/docs/latest/use/configure/configuration-files-deprecated)). The following examples use `json` format for the content of the configuration file:
|
|
28
|
+
|
|
29
|
+
```json
|
|
30
|
+
{
|
|
31
|
+
"plugins": [
|
|
32
|
+
"cypress"
|
|
33
|
+
]
|
|
34
|
+
}
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
You can add rules - see [Rules](./README.md#rules) for a list of the available rules:
|
|
38
|
+
|
|
39
|
+
```json
|
|
40
|
+
{
|
|
41
|
+
"rules": {
|
|
42
|
+
"cypress/no-assigning-return-values": "error",
|
|
43
|
+
"cypress/no-unnecessary-waiting": "error",
|
|
44
|
+
"cypress/assertion-before-screenshot": "warn",
|
|
45
|
+
"cypress/no-force": "warn",
|
|
46
|
+
"cypress/no-async-tests": "error",
|
|
47
|
+
"cypress/no-async-before": "error",
|
|
48
|
+
"cypress/no-pause": "error",
|
|
49
|
+
"cypress/no-debug": "error"
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
You can allow certain globals provided by Cypress:
|
|
55
|
+
|
|
56
|
+
```json
|
|
57
|
+
{
|
|
58
|
+
"env": {
|
|
59
|
+
"cypress/globals": true
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Recommended configuration
|
|
65
|
+
|
|
66
|
+
Use the recommended configuration and you can forego configuring _plugins_, _rules_, and _env_ individually. See [Rules](./README.md#rules) for which rules are included in the recommended configuration.
|
|
67
|
+
|
|
68
|
+
```json
|
|
69
|
+
{
|
|
70
|
+
"extends": [
|
|
71
|
+
"plugin:cypress/recommended"
|
|
72
|
+
]
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## Rules
|
|
77
|
+
|
|
78
|
+
See the [Rules](./README.md#rules) list in the main [README](./README.md) document.
|
|
79
|
+
|
|
80
|
+
## Mocha and Chai
|
|
81
|
+
|
|
82
|
+
Cypress is built on top of [Mocha](https://on.cypress.io/guides/references/bundled-libraries#Mocha) and [Chai](https://on.cypress.io/guides/references/bundled-libraries#Chai). See the following sections for information on using ESLint plugins [eslint-plugin-mocha](https://www.npmjs.com/package/eslint-plugin-mocha) and [eslint-plugin-chai-friendly](https://www.npmjs.com/package/eslint-plugin-chai-friendly) together with `eslint-plugin-cypress`.
|
|
83
|
+
|
|
84
|
+
## Mocha `.only` and `.skip`
|
|
85
|
+
|
|
86
|
+
During test spec development, [Mocha exclusive tests](https://mochajs.org/#exclusive-tests) `.only` or [Mocha inclusive tests](https://mochajs.org/#inclusive-tests) `.skip` may be used to control which tests are executed, as described in the Cypress documentation [Excluding and Including Tests](https://on.cypress.io/guides/core-concepts/writing-and-organizing-tests#Excluding-and-Including-Tests). To apply corresponding rules, you can install and use [eslint-plugin-mocha](https://www.npmjs.com/package/eslint-plugin-mocha). The rule [mocha/no-exclusive-tests](https://github.com/lo1tuma/eslint-plugin-mocha/blob/main/docs/rules/no-exclusive-tests.md) detects the use of `.only` and the [mocha/no-skipped-tests](https://github.com/lo1tuma/eslint-plugin-mocha/blob/main/docs/rules/no-skipped-tests.md) rule detects the use of `.skip`:
|
|
87
|
+
|
|
88
|
+
```sh
|
|
89
|
+
npm install --save-dev eslint-plugin-mocha
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
In your `.eslintrc.json`:
|
|
93
|
+
|
|
94
|
+
```json
|
|
95
|
+
{
|
|
96
|
+
"plugins": [
|
|
97
|
+
"cypress",
|
|
98
|
+
"mocha"
|
|
99
|
+
],
|
|
100
|
+
"rules": {
|
|
101
|
+
"mocha/no-exclusive-tests": "warn",
|
|
102
|
+
"mocha/no-skipped-tests": "warn"
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Or you can simply use the `cypress/recommended` and `mocha/recommended` configurations together, for example:
|
|
108
|
+
|
|
109
|
+
```json
|
|
110
|
+
{
|
|
111
|
+
"extends": [
|
|
112
|
+
"plugin:cypress/recommended",
|
|
113
|
+
"plugin:mocha/recommended"
|
|
114
|
+
]
|
|
115
|
+
}
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
## Chai and `no-unused-expressions`
|
|
119
|
+
|
|
120
|
+
Using an assertion such as `expect(value).to.be.true` can fail the ESLint rule `no-unused-expressions` even though it's not an error in this case. To fix this, you can install and use [eslint-plugin-chai-friendly](https://www.npmjs.com/package/eslint-plugin-chai-friendly).
|
|
121
|
+
|
|
122
|
+
```sh
|
|
123
|
+
npm install --save-dev eslint-plugin-chai-friendly
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
In your `.eslintrc.json`:
|
|
127
|
+
|
|
128
|
+
```json
|
|
129
|
+
{
|
|
130
|
+
"plugins": [
|
|
131
|
+
"cypress",
|
|
132
|
+
"chai-friendly"
|
|
133
|
+
],
|
|
134
|
+
"rules": {
|
|
135
|
+
"no-unused-expressions": 0,
|
|
136
|
+
"chai-friendly/no-unused-expressions": 2
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Or you can simply add its `recommended` config:
|
|
142
|
+
|
|
143
|
+
```json
|
|
144
|
+
{
|
|
145
|
+
"extends": ["plugin:chai-friendly/recommended"]
|
|
146
|
+
}
|
|
147
|
+
```
|
package/FLAT-CONFIG.md
CHANGED
|
@@ -1,144 +1,5 @@
|
|
|
1
1
|
# Cypress ESLint Plugin - Flat Config
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Please refer to the [README](./README.md) document where the previous contents of this document, describing how to use `eslint-plugin-cypress` with an ESLint `v9` (default) [flat configuration](https://eslint.org/docs/latest/use/configure/configuration-files), can now be found.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
## Introduction
|
|
8
|
-
|
|
9
|
-
[ESLint v9.0.0](https://eslint.org/blog/2024/04/eslint-v9.0.0-released/) was released on April 5, 2024, establishing flat config as the default for this version.
|
|
10
|
-
|
|
11
|
-
Previously, ESLint had announced in their blog post [Flat config rollout plans](https://eslint.org/blog/2023/10/flat-config-rollout-plans/) in October 2023 that flat config was planned to be the default in ESLint `v9.0.0` and that the eslintrc configuration system is planned to be removed in the future ESLint `v10.0.0`.
|
|
12
|
-
|
|
13
|
-
The following information details installation and usage examples for `eslint-plugin-cypress` together with related plugins in an ESLint flat config environment.
|
|
14
|
-
|
|
15
|
-
## Installation
|
|
16
|
-
|
|
17
|
-
Use a minimum ESLint `9.x`.
|
|
18
|
-
|
|
19
|
-
```shell
|
|
20
|
-
npm install eslint eslint-plugin-cypress --save-dev
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
or
|
|
24
|
-
|
|
25
|
-
```shell
|
|
26
|
-
yarn add eslint eslint-plugin-cypress --dev
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
## Usage examples
|
|
30
|
-
|
|
31
|
-
Add a flat configuration file `eslint.config.mjs` to the root directory of your Cypress project and include the following instructions to import the available flat configurations using:
|
|
32
|
-
|
|
33
|
-
```shell
|
|
34
|
-
import pluginCypress from 'eslint-plugin-cypress/flat'
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
There are two specific flat configurations available:
|
|
38
|
-
|
|
39
|
-
| Configuration | Content |
|
|
40
|
-
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
41
|
-
| `configs.globals` | defines globals `cy`, `Cypress`, `expect`, `assert` and `chai` used in Cypress test specs as well as `globals.browser` and `globals.mocha` from [globals](https://www.npmjs.com/package/globals). This version no longer specifies `languageOptions` for `ecmaVersion` and `sourceType` - see ESLint [JavaScript languageOptions](https://eslint.org/docs/latest/use/configure/language-options#specifying-javascript-options). There are no default rules enabled in this configuration. |
|
|
42
|
-
| `configs.recommended` | enables [recommended Rules](README.md#rules). It includes also `configs.global` (see above) |
|
|
43
|
-
|
|
44
|
-
In the following sections, different examples of possible configuration file contents are given, together with some brief explanations. Adapt these examples according to your needs.
|
|
45
|
-
|
|
46
|
-
### Cypress
|
|
47
|
-
|
|
48
|
-
All rules from `eslint-plugin-cypress` are available through `eslint-plugin-cypress/flat`.
|
|
49
|
-
- [cypress/unsafe-to-chain-command](https://github.com/cypress-io/eslint-plugin-cypress/blob/master/docs/rules/unsafe-to-chain-command.md) is active and set to `error`
|
|
50
|
-
|
|
51
|
-
```js
|
|
52
|
-
import pluginCypress from 'eslint-plugin-cypress/flat'
|
|
53
|
-
export default [
|
|
54
|
-
{
|
|
55
|
-
plugins: {
|
|
56
|
-
cypress: pluginCypress
|
|
57
|
-
},
|
|
58
|
-
rules: {
|
|
59
|
-
'cypress/unsafe-to-chain-command': 'error'
|
|
60
|
-
}
|
|
61
|
-
}
|
|
62
|
-
]
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
### Cypress recommended
|
|
66
|
-
|
|
67
|
-
The `eslint-plugin-cypress` [recommended rules](README.md#rules) `configs.recommended` are activated, except for
|
|
68
|
-
- [cypress/no-unnecessary-waiting](https://github.com/cypress-io/eslint-plugin-cypress/blob/master/docs/rules/no-unnecessary-waiting.md) set to `off`
|
|
69
|
-
|
|
70
|
-
```js
|
|
71
|
-
import pluginCypress from 'eslint-plugin-cypress/flat'
|
|
72
|
-
export default [
|
|
73
|
-
pluginCypress.configs.recommended,
|
|
74
|
-
{
|
|
75
|
-
rules: {
|
|
76
|
-
'cypress/no-unnecessary-waiting': 'off'
|
|
77
|
-
}
|
|
78
|
-
}
|
|
79
|
-
]
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
### Cypress globals
|
|
83
|
-
|
|
84
|
-
The `configs.globals` are activated.
|
|
85
|
-
|
|
86
|
-
```js
|
|
87
|
-
import pluginCypress from 'eslint-plugin-cypress/flat'
|
|
88
|
-
export default [
|
|
89
|
-
pluginCypress.configs.globals
|
|
90
|
-
]
|
|
91
|
-
```
|
|
92
|
-
|
|
93
|
-
### Cypress and Mocha recommended
|
|
94
|
-
|
|
95
|
-
[eslint-plugin-mocha](https://www.npmjs.com/package/eslint-plugin-mocha) is added to the example [Cypress recommended](#cypress-recommended). This plugin offers a flat file recommended option `configs.flat.recommended`.
|
|
96
|
-
|
|
97
|
-
The settings for individual `mocha` rules from the `configs.flat.recommended` option are changed.
|
|
98
|
-
- [mocha/no-exclusive-tests](https://github.com/lo1tuma/eslint-plugin-mocha/blob/main/docs/rules/no-exclusive-tests.md) and [mocha/no-skipped-tests](https://github.com/lo1tuma/eslint-plugin-mocha/blob/main/docs/rules/no-skipped-tests.md) are set to `error` instead of `warn`
|
|
99
|
-
- [mocha/no-mocha-arrows](https://github.com/lo1tuma/eslint-plugin-mocha/blob/main/docs/rules/no-mocha-arrows.md) is set to `off` instead of `error`
|
|
100
|
-
|
|
101
|
-
```shell
|
|
102
|
-
npm install eslint-plugin-mocha@^10.4.3 --save-dev
|
|
103
|
-
```
|
|
104
|
-
|
|
105
|
-
```js
|
|
106
|
-
import pluginMocha from 'eslint-plugin-mocha'
|
|
107
|
-
import pluginCypress from 'eslint-plugin-cypress/flat'
|
|
108
|
-
export default [
|
|
109
|
-
pluginMocha.configs.flat.recommended,
|
|
110
|
-
pluginCypress.configs.recommended,
|
|
111
|
-
{
|
|
112
|
-
rules: {
|
|
113
|
-
'mocha/no-exclusive-tests': 'warn',
|
|
114
|
-
'mocha/no-skipped-tests': 'warn',
|
|
115
|
-
'mocha/no-mocha-arrows': 'off',
|
|
116
|
-
'cypress/no-unnecessary-waiting': 'off'
|
|
117
|
-
}
|
|
118
|
-
}
|
|
119
|
-
]
|
|
120
|
-
```
|
|
121
|
-
|
|
122
|
-
### Cypress and Chai recommended
|
|
123
|
-
|
|
124
|
-
[eslint-plugin-chai-friendly](https://www.npmjs.com/package/eslint-plugin-chai-friendly) (minimum version [eslint-plugin-chai-friendly@0.8.0](https://github.com/ihordiachenko/eslint-plugin-chai-friendly/releases/tag/v0.8.0) required for ESLint v9 support and flat config support) is combined with the Cypress plugin `eslint-plugin-cypress`.
|
|
125
|
-
|
|
126
|
-
The recommended rules for both plugins are used: `pluginCypress.configs.recommended` and `pluginChaiFriendly.configs.recommended`:
|
|
127
|
-
|
|
128
|
-
```shell
|
|
129
|
-
npm install eslint-plugin-chai-friendly@^0.8.0 --save-dev
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
```js
|
|
133
|
-
import pluginCypress from 'eslint-plugin-cypress/flat'
|
|
134
|
-
import pluginChaiFriendly from 'eslint-plugin-chai-friendly'
|
|
135
|
-
export default [
|
|
136
|
-
pluginCypress.configs.recommended,
|
|
137
|
-
pluginChaiFriendly.configs.recommended,
|
|
138
|
-
{
|
|
139
|
-
rules: {
|
|
140
|
-
'cypress/no-unnecessary-waiting': 'off',
|
|
141
|
-
},
|
|
142
|
-
}
|
|
143
|
-
]
|
|
144
|
-
```
|
|
5
|
+
For instructions on using a deprecated [eslintrc-type](https://eslint.org/docs/latest/use/configure/configuration-files-deprecated) config file from previous ESLint `v8` versions and below, please refer to the [ESLINTRC-CONFIG](./ESLINTRC-CONFIG.md) document.
|
package/README.md
CHANGED
|
@@ -7,72 +7,113 @@ Note: If you installed ESLint globally then you must also install `eslint-plugin
|
|
|
7
7
|
## Installation
|
|
8
8
|
|
|
9
9
|
Prerequisites: [ESLint](https://www.npmjs.com/package/eslint) `v9`. Lower versions are no longer supported.
|
|
10
|
-
This plugin supports the use of [Flat config files](https://eslint.org/docs/latest/use/configure/configuration-files) with ESLint `9.0.0` and above.
|
|
11
10
|
|
|
12
11
|
```sh
|
|
13
|
-
npm install eslint-plugin-cypress --save-dev
|
|
12
|
+
npm install eslint eslint-plugin-cypress --save-dev
|
|
14
13
|
```
|
|
15
14
|
or
|
|
16
15
|
```sh
|
|
17
|
-
yarn add eslint-plugin-cypress --dev
|
|
16
|
+
yarn add eslint eslint-plugin-cypress --dev
|
|
18
17
|
```
|
|
19
18
|
|
|
20
19
|
## Usage
|
|
21
20
|
|
|
22
|
-
ESLint `v9` uses a [Flat config file](https://eslint.org/docs/latest/use/configure/configuration-files) format with filename `eslint.config.*js` by default.
|
|
21
|
+
ESLint `v9` uses a [Flat config file](https://eslint.org/docs/latest/use/configure/configuration-files) format with filename `eslint.config.*js` by default. For instructions on using a deprecated [eslintrc-type](https://eslint.org/docs/latest/use/configure/configuration-files-deprecated) config file from previous ESLint versions, please refer to the [ESLINTRC-CONFIG](./ESLINTRC-CONFIG.md) document.
|
|
23
22
|
|
|
24
|
-
|
|
23
|
+
To set up a flat configuration, add a file `eslint.config.mjs` to the root directory of your Cypress project and include the following instructions to import the available flat configurations using:
|
|
25
24
|
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
"plugins": [
|
|
29
|
-
"cypress"
|
|
30
|
-
]
|
|
31
|
-
}
|
|
25
|
+
```shell
|
|
26
|
+
import pluginCypress from 'eslint-plugin-cypress/flat'
|
|
32
27
|
```
|
|
33
28
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
29
|
+
## Configurations
|
|
30
|
+
|
|
31
|
+
There are two specific flat configurations available:
|
|
32
|
+
|
|
33
|
+
| Configuration | Content |
|
|
34
|
+
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
35
|
+
| `configs.globals` | defines globals `cy`, `Cypress`, `expect`, `assert` and `chai` used in Cypress test specs as well as `globals.browser` and `globals.mocha` from [globals](https://www.npmjs.com/package/globals). This version no longer specifies `languageOptions` for `ecmaVersion` and `sourceType` - see ESLint [JavaScript languageOptions](https://eslint.org/docs/latest/use/configure/language-options#specifying-javascript-options). There are no default rules enabled in this configuration. |
|
|
36
|
+
| `configs.recommended` | enables [recommended Rules](#rules). It includes also `configs.global` (see above). |
|
|
37
|
+
|
|
38
|
+
## Rules
|
|
39
|
+
|
|
40
|
+
These rules enforce some of the [best practices recommended for using Cypress](https://on.cypress.io/best-practices).
|
|
41
|
+
|
|
42
|
+
<!-- begin auto-generated rules list -->
|
|
43
|
+
|
|
44
|
+
💼 Configurations enabled in.\
|
|
45
|
+
✅ Set in the `recommended` configuration.
|
|
46
|
+
|
|
47
|
+
| Name | Description | 💼 |
|
|
48
|
+
| :----------------------------------------------------------------------- | :--------------------------------------------------------- | :- |
|
|
49
|
+
| [assertion-before-screenshot](docs/rules/assertion-before-screenshot.md) | require screenshots to be preceded by an assertion | |
|
|
50
|
+
| [no-assigning-return-values](docs/rules/no-assigning-return-values.md) | disallow assigning return values of `cy` calls | ✅ |
|
|
51
|
+
| [no-async-before](docs/rules/no-async-before.md) | disallow using `async`/`await` in Cypress `before` methods | |
|
|
52
|
+
| [no-async-tests](docs/rules/no-async-tests.md) | disallow using `async`/`await` in Cypress test cases | ✅ |
|
|
53
|
+
| [no-debug](docs/rules/no-debug.md) | disallow using `cy.debug()` calls | |
|
|
54
|
+
| [no-force](docs/rules/no-force.md) | disallow using `force: true` with action commands | |
|
|
55
|
+
| [no-pause](docs/rules/no-pause.md) | disallow using `cy.pause()` calls | |
|
|
56
|
+
| [no-unnecessary-waiting](docs/rules/no-unnecessary-waiting.md) | disallow waiting for arbitrary time periods | ✅ |
|
|
57
|
+
| [no-xpath](docs/rules/no-xpath.md) | disallow using `cy.xpath()` calls | |
|
|
58
|
+
| [require-data-selectors](docs/rules/require-data-selectors.md) | require `data-*` attribute selectors | |
|
|
59
|
+
| [unsafe-to-chain-command](docs/rules/unsafe-to-chain-command.md) | disallow actions within chains | ✅ |
|
|
60
|
+
|
|
61
|
+
<!-- end auto-generated rules list -->
|
|
62
|
+
|
|
63
|
+
## Usage examples
|
|
64
|
+
|
|
65
|
+
In the following sections, different examples of possible configuration file contents are given, together with some brief explanations. Adapt these examples according to your needs.
|
|
66
|
+
|
|
67
|
+
### Cypress
|
|
68
|
+
|
|
69
|
+
All rules from `eslint-plugin-cypress` are available through `eslint-plugin-cypress/flat` and can be individually activated.
|
|
70
|
+
- [cypress/unsafe-to-chain-command](https://github.com/cypress-io/eslint-plugin-cypress/blob/master/docs/rules/unsafe-to-chain-command.md) is activated and set to `error`
|
|
71
|
+
|
|
72
|
+
```js
|
|
73
|
+
import pluginCypress from 'eslint-plugin-cypress/flat'
|
|
74
|
+
export default [
|
|
75
|
+
{
|
|
76
|
+
plugins: {
|
|
77
|
+
cypress: pluginCypress
|
|
78
|
+
},
|
|
79
|
+
rules: {
|
|
80
|
+
'cypress/unsafe-to-chain-command': 'error'
|
|
81
|
+
}
|
|
47
82
|
}
|
|
48
|
-
|
|
83
|
+
]
|
|
49
84
|
```
|
|
50
85
|
|
|
51
|
-
|
|
86
|
+
### Cypress recommended
|
|
87
|
+
|
|
88
|
+
The `eslint-plugin-cypress` [recommended rules](#rules) `configs.recommended` are activated, except for
|
|
89
|
+
- [cypress/no-unnecessary-waiting](https://github.com/cypress-io/eslint-plugin-cypress/blob/master/docs/rules/no-unnecessary-waiting.md) which is set to `off`
|
|
52
90
|
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
91
|
+
```js
|
|
92
|
+
import pluginCypress from 'eslint-plugin-cypress/flat'
|
|
93
|
+
export default [
|
|
94
|
+
pluginCypress.configs.recommended,
|
|
95
|
+
{
|
|
96
|
+
rules: {
|
|
97
|
+
'cypress/no-unnecessary-waiting': 'off'
|
|
98
|
+
}
|
|
57
99
|
}
|
|
58
|
-
|
|
100
|
+
]
|
|
59
101
|
```
|
|
60
102
|
|
|
61
|
-
|
|
103
|
+
### Cypress globals
|
|
62
104
|
|
|
63
|
-
|
|
105
|
+
The `configs.globals` are activated.
|
|
64
106
|
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
}
|
|
107
|
+
```js
|
|
108
|
+
import pluginCypress from 'eslint-plugin-cypress/flat'
|
|
109
|
+
export default [
|
|
110
|
+
pluginCypress.configs.globals
|
|
111
|
+
]
|
|
71
112
|
```
|
|
72
113
|
|
|
73
114
|
## Disable rules
|
|
74
115
|
|
|
75
|
-
You can disable specific rules per file, for a portion of a file, or for a single line.
|
|
116
|
+
You can disable specific rules per file, for a portion of a file, or for a single line. See the [ESLint rules](https://eslint.org/docs/latest/use/configure/rules#disabling-rules) documentation. For example ...
|
|
76
117
|
|
|
77
118
|
Disable the `cypress/no-unnecessary-waiting` rule for the entire file by placing this at the start of the file:
|
|
78
119
|
|
|
@@ -113,99 +154,67 @@ it('waits for a second', () => {
|
|
|
113
154
|
})
|
|
114
155
|
```
|
|
115
156
|
|
|
116
|
-
For more, see the [ESLint rules](https://eslint.org/docs/user-guide/configuring/rules) documentation.
|
|
117
|
-
|
|
118
|
-
## Rules
|
|
119
|
-
|
|
120
|
-
These rules enforce some of the [best practices recommended for using Cypress](https://on.cypress.io/best-practices).
|
|
121
|
-
|
|
122
|
-
<!-- begin auto-generated rules list -->
|
|
123
|
-
|
|
124
|
-
💼 Configurations enabled in.\
|
|
125
|
-
✅ Set in the `recommended` configuration.
|
|
126
|
-
|
|
127
|
-
| Name | Description | 💼 |
|
|
128
|
-
| :----------------------------------------------------------------------- | :--------------------------------------------------------- | :- |
|
|
129
|
-
| [assertion-before-screenshot](docs/rules/assertion-before-screenshot.md) | require screenshots to be preceded by an assertion | |
|
|
130
|
-
| [no-assigning-return-values](docs/rules/no-assigning-return-values.md) | disallow assigning return values of `cy` calls | ✅ |
|
|
131
|
-
| [no-async-before](docs/rules/no-async-before.md) | disallow using `async`/`await` in Cypress `before` methods | |
|
|
132
|
-
| [no-async-tests](docs/rules/no-async-tests.md) | disallow using `async`/`await` in Cypress test cases | ✅ |
|
|
133
|
-
| [no-debug](docs/rules/no-debug.md) | disallow using `cy.debug()` calls | |
|
|
134
|
-
| [no-force](docs/rules/no-force.md) | disallow using `force: true` with action commands | |
|
|
135
|
-
| [no-pause](docs/rules/no-pause.md) | disallow using `cy.pause()` calls | |
|
|
136
|
-
| [no-unnecessary-waiting](docs/rules/no-unnecessary-waiting.md) | disallow waiting for arbitrary time periods | ✅ |
|
|
137
|
-
| [require-data-selectors](docs/rules/require-data-selectors.md) | require `data-*` attribute selectors | |
|
|
138
|
-
| [unsafe-to-chain-command](docs/rules/unsafe-to-chain-command.md) | disallow actions within chains | ✅ |
|
|
139
|
-
|
|
140
|
-
<!-- end auto-generated rules list -->
|
|
141
|
-
|
|
142
157
|
## Mocha and Chai
|
|
143
158
|
|
|
144
159
|
Cypress is built on top of [Mocha](https://on.cypress.io/guides/references/bundled-libraries#Mocha) and [Chai](https://on.cypress.io/guides/references/bundled-libraries#Chai). See the following sections for information on using ESLint plugins [eslint-plugin-mocha](https://www.npmjs.com/package/eslint-plugin-mocha) and [eslint-plugin-chai-friendly](https://www.npmjs.com/package/eslint-plugin-chai-friendly) together with `eslint-plugin-cypress`.
|
|
145
160
|
|
|
146
161
|
## Mocha `.only` and `.skip`
|
|
147
162
|
|
|
148
|
-
During test spec development, [Mocha exclusive tests](https://mochajs.org/#exclusive-tests) `.only` or [Mocha inclusive tests](https://mochajs.org/#inclusive-tests) `.skip` may be used to control which tests are executed, as described in the Cypress documentation [Excluding and Including Tests](https://on.cypress.io/guides/core-concepts/writing-and-organizing-tests#Excluding-and-Including-Tests). To apply corresponding rules, you can install and use [eslint-plugin-mocha](https://www.npmjs.com/package/eslint-plugin-mocha). The rule [mocha/no-exclusive-tests](https://github.com/lo1tuma/eslint-plugin-mocha/blob/main/docs/rules/no-exclusive-tests.md) detects the use of `.only` and the [mocha/no-skipped-tests](https://github.com/lo1tuma/eslint-plugin-mocha/blob/main/docs/rules/no-skipped-tests.md) rule detects the use of `.skip
|
|
163
|
+
During test spec development, [Mocha exclusive tests](https://mochajs.org/#exclusive-tests) `.only` or [Mocha inclusive tests](https://mochajs.org/#inclusive-tests) `.skip` may be used to control which tests are executed, as described in the Cypress documentation [Excluding and Including Tests](https://on.cypress.io/guides/core-concepts/writing-and-organizing-tests#Excluding-and-Including-Tests). To apply corresponding rules, you can install and use [eslint-plugin-mocha](https://www.npmjs.com/package/eslint-plugin-mocha). The rule [mocha/no-exclusive-tests](https://github.com/lo1tuma/eslint-plugin-mocha/blob/main/docs/rules/no-exclusive-tests.md) detects the use of `.only` and the [mocha/no-skipped-tests](https://github.com/lo1tuma/eslint-plugin-mocha/blob/main/docs/rules/no-skipped-tests.md) rule detects the use of `.skip`.
|
|
149
164
|
|
|
150
|
-
|
|
151
|
-
|
|
165
|
+
### Cypress and Mocha recommended
|
|
166
|
+
|
|
167
|
+
[eslint-plugin-mocha](https://www.npmjs.com/package/eslint-plugin-mocha) is added to the example [Cypress recommended](#cypress-recommended). This plugin offers a flat file recommended option `configs.flat.recommended`.
|
|
168
|
+
|
|
169
|
+
The settings for individual `mocha` rules from the `configs.flat.recommended` option are changed.
|
|
170
|
+
- [mocha/no-exclusive-tests](https://github.com/lo1tuma/eslint-plugin-mocha/blob/main/docs/rules/no-exclusive-tests.md) and [mocha/no-skipped-tests](https://github.com/lo1tuma/eslint-plugin-mocha/blob/main/docs/rules/no-skipped-tests.md) are set to `error` instead of `warn`
|
|
171
|
+
- [mocha/no-mocha-arrows](https://github.com/lo1tuma/eslint-plugin-mocha/blob/main/docs/rules/no-mocha-arrows.md) is set to `off` instead of `error`
|
|
172
|
+
|
|
173
|
+
```shell
|
|
174
|
+
npm install eslint-plugin-mocha@^10.5.0 --save-dev
|
|
152
175
|
```
|
|
153
176
|
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
177
|
+
```js
|
|
178
|
+
import pluginMocha from 'eslint-plugin-mocha'
|
|
179
|
+
import pluginCypress from 'eslint-plugin-cypress/flat'
|
|
180
|
+
export default [
|
|
181
|
+
pluginMocha.configs.flat.recommended,
|
|
182
|
+
pluginCypress.configs.recommended,
|
|
183
|
+
{
|
|
184
|
+
rules: {
|
|
185
|
+
'mocha/no-exclusive-tests': 'error',
|
|
186
|
+
'mocha/no-skipped-tests': 'error',
|
|
187
|
+
'mocha/no-mocha-arrows': 'off',
|
|
188
|
+
'cypress/no-unnecessary-waiting': 'off'
|
|
189
|
+
}
|
|
165
190
|
}
|
|
166
|
-
|
|
191
|
+
]
|
|
167
192
|
```
|
|
168
193
|
|
|
169
|
-
|
|
194
|
+
### Cypress and Chai recommended
|
|
170
195
|
|
|
171
|
-
|
|
172
|
-
{
|
|
173
|
-
"extends": [
|
|
174
|
-
"plugin:cypress/recommended",
|
|
175
|
-
"plugin:mocha/recommended"
|
|
176
|
-
]
|
|
177
|
-
}
|
|
178
|
-
```
|
|
196
|
+
Using an assertion such as `expect(value).to.be.true` can fail the ESLint rule `no-unused-expressions` even though it's not an error in this case. To fix this, you can install and use [eslint-plugin-chai-friendly](https://www.npmjs.com/package/eslint-plugin-chai-friendly).
|
|
179
197
|
|
|
180
|
-
|
|
198
|
+
[eslint-plugin-chai-friendly](https://www.npmjs.com/package/eslint-plugin-chai-friendly) is combined with the Cypress plugin `eslint-plugin-cypress`.
|
|
181
199
|
|
|
182
|
-
|
|
200
|
+
The recommended rules for both plugins are used: `pluginCypress.configs.recommended` and `pluginChaiFriendly.configs.recommendedFlat`:
|
|
183
201
|
|
|
184
|
-
```
|
|
185
|
-
npm install
|
|
202
|
+
```shell
|
|
203
|
+
npm install eslint-plugin-chai-friendly@^1.0.1 --save-dev
|
|
186
204
|
```
|
|
187
205
|
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
"chai-friendly/no-unused-expressions": 2
|
|
206
|
+
```js
|
|
207
|
+
import pluginCypress from 'eslint-plugin-cypress/flat'
|
|
208
|
+
import pluginChaiFriendly from 'eslint-plugin-chai-friendly'
|
|
209
|
+
export default [
|
|
210
|
+
pluginCypress.configs.recommended,
|
|
211
|
+
pluginChaiFriendly.configs.recommendedFlat,
|
|
212
|
+
{
|
|
213
|
+
rules: {
|
|
214
|
+
'cypress/no-unnecessary-waiting': 'off',
|
|
215
|
+
},
|
|
199
216
|
}
|
|
200
|
-
|
|
201
|
-
```
|
|
202
|
-
|
|
203
|
-
Or you can simply add its `recommended` config:
|
|
204
|
-
|
|
205
|
-
```json
|
|
206
|
-
{
|
|
207
|
-
"extends": ["plugin:chai-friendly/recommended"]
|
|
208
|
-
}
|
|
217
|
+
]
|
|
209
218
|
```
|
|
210
219
|
|
|
211
220
|
## Contributing
|
package/circle.yml
CHANGED
|
@@ -20,7 +20,7 @@ workflows:
|
|
|
20
20
|
jobs:
|
|
21
21
|
lint:
|
|
22
22
|
docker:
|
|
23
|
-
- image: cimg/node:
|
|
23
|
+
- image: cimg/node:22.11.0
|
|
24
24
|
steps:
|
|
25
25
|
- checkout
|
|
26
26
|
- run:
|
|
@@ -35,7 +35,7 @@ jobs:
|
|
|
35
35
|
|
|
36
36
|
test-v8:
|
|
37
37
|
docker:
|
|
38
|
-
- image: cimg/node:
|
|
38
|
+
- image: cimg/node:22.11.0
|
|
39
39
|
steps:
|
|
40
40
|
- checkout
|
|
41
41
|
- run:
|
|
@@ -53,7 +53,7 @@ jobs:
|
|
|
53
53
|
|
|
54
54
|
test-v9:
|
|
55
55
|
docker:
|
|
56
|
-
- image: cimg/node:
|
|
56
|
+
- image: cimg/node:22.11.0
|
|
57
57
|
steps:
|
|
58
58
|
- checkout
|
|
59
59
|
- run:
|
|
@@ -71,7 +71,7 @@ jobs:
|
|
|
71
71
|
|
|
72
72
|
release:
|
|
73
73
|
docker:
|
|
74
|
-
- image: cimg/node:
|
|
74
|
+
- image: cimg/node:22.11.0
|
|
75
75
|
steps:
|
|
76
76
|
- checkout
|
|
77
77
|
- run:
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Disallow using `cy.xpath()` calls (`cypress/no-xpath`)
|
|
2
|
+
|
|
3
|
+
<!-- end auto-generated rule header -->
|
|
4
|
+
|
|
5
|
+
This rule disallows the usage of `cy.xpath()` for selecting elements.
|
|
6
|
+
|
|
7
|
+
## Rule Details
|
|
8
|
+
|
|
9
|
+
Examples of **incorrect** code for this rule:
|
|
10
|
+
|
|
11
|
+
```js
|
|
12
|
+
cy.xpath('//div[@class=\"container\"]').click()
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Examples of **correct** code for this rule:
|
|
16
|
+
|
|
17
|
+
```js
|
|
18
|
+
cy.get('[data-cy="container"]').click();
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Further Reading
|
|
22
|
+
|
|
23
|
+
Both `@cypress/xpath` and `cypress-xpath` are deprecated.
|
|
24
|
+
|
|
25
|
+
See [the Cypress Best Practices guide](https://docs.cypress.io/guides/references/best-practices.html#Selecting-Elements).
|
package/eslint.config.mjs
CHANGED
|
@@ -1,13 +1,11 @@
|
|
|
1
1
|
import globals from 'globals'
|
|
2
2
|
import pluginJs from '@eslint/js'
|
|
3
3
|
import eslintPlugin from 'eslint-plugin-eslint-plugin'
|
|
4
|
-
import nodePlugin from 'eslint-plugin-n'
|
|
5
4
|
import mochaPlugin from 'eslint-plugin-mocha'
|
|
6
5
|
|
|
7
6
|
export default [
|
|
8
7
|
pluginJs.configs.recommended,
|
|
9
8
|
eslintPlugin.configs['flat/recommended'],
|
|
10
|
-
nodePlugin.configs['flat/recommended-script'],
|
|
11
9
|
mochaPlugin.configs.flat.recommended,
|
|
12
10
|
{
|
|
13
11
|
languageOptions: {
|
|
@@ -20,8 +18,6 @@ export default [
|
|
|
20
18
|
'eslint-plugin/require-meta-docs-description': 'error',
|
|
21
19
|
'eslint-plugin/meta-property-ordering': 'error',
|
|
22
20
|
'eslint-plugin/test-case-property-ordering': 'error',
|
|
23
|
-
'n/no-extraneous-require':
|
|
24
|
-
['error', { 'allowModules': ['jest-config'] }],
|
|
25
21
|
'mocha/no-mocha-arrows': 'off',
|
|
26
22
|
'mocha/no-setup-in-describe': 'off'
|
|
27
23
|
}
|
package/legacy.js
CHANGED
|
@@ -12,6 +12,7 @@ module.exports = {
|
|
|
12
12
|
'no-force': require('./lib/rules/no-force'),
|
|
13
13
|
'no-pause': require('./lib/rules/no-pause'),
|
|
14
14
|
'no-debug': require('./lib/rules/no-debug'),
|
|
15
|
+
'no-xpath': require('./lib/rules/no-xpath'),
|
|
15
16
|
},
|
|
16
17
|
configs: {
|
|
17
18
|
recommended: require('./lib/config/recommended'),
|
package/lib/flat.js
CHANGED
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
module.exports = {
|
|
4
|
+
meta: {
|
|
5
|
+
type: 'suggestion',
|
|
6
|
+
docs: {
|
|
7
|
+
description: 'disallow using `cy.xpath()` calls',
|
|
8
|
+
recommended: false,
|
|
9
|
+
url: 'https://github.com/cypress-io/eslint-plugin-cypress/blob/master/docs/rules/no-xpath.md'
|
|
10
|
+
},
|
|
11
|
+
fixable: null, // Or `code` or `whitespace`
|
|
12
|
+
schema: [], // Add a schema if the rule has options
|
|
13
|
+
messages: {
|
|
14
|
+
unexpected: 'Avoid using cy.xpath command',
|
|
15
|
+
},
|
|
16
|
+
},
|
|
17
|
+
|
|
18
|
+
create (context) {
|
|
19
|
+
return {
|
|
20
|
+
CallExpression (node) {
|
|
21
|
+
if (isCallingCyXpath(node)) {
|
|
22
|
+
context.report({ node, messageId: 'unexpected' })
|
|
23
|
+
}
|
|
24
|
+
},
|
|
25
|
+
}
|
|
26
|
+
},
|
|
27
|
+
};
|
|
28
|
+
|
|
29
|
+
function isCallingCyXpath (node) {
|
|
30
|
+
return node.callee.type === 'MemberExpression' &&
|
|
31
|
+
node.callee.object.type === 'Identifier' &&
|
|
32
|
+
node.callee.object.name === 'cy' &&
|
|
33
|
+
node.callee.property.type === 'Identifier' &&
|
|
34
|
+
node.callee.property.name === 'xpath'
|
|
35
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "eslint-plugin-cypress",
|
|
3
|
-
"version": "4.
|
|
3
|
+
"version": "4.2.0",
|
|
4
4
|
"description": "An ESLint plugin for projects using Cypress",
|
|
5
5
|
"main": "legacy.js",
|
|
6
6
|
"exports": {
|
|
@@ -29,13 +29,12 @@
|
|
|
29
29
|
"globals": "^15.11.0"
|
|
30
30
|
},
|
|
31
31
|
"devDependencies": {
|
|
32
|
-
"eslint": "^9.
|
|
33
|
-
"eslint-plugin-eslint-plugin": "^6.
|
|
32
|
+
"eslint": "^9.13.0",
|
|
33
|
+
"eslint-plugin-eslint-plugin": "^6.3.1",
|
|
34
34
|
"eslint-plugin-mocha": "^10.5.0",
|
|
35
|
-
"eslint-plugin-n": "^17.11.1",
|
|
36
35
|
"husky": "^9.1.6",
|
|
37
36
|
"jest": "^29.7.0",
|
|
38
|
-
"semantic-release": "24.
|
|
37
|
+
"semantic-release": "24.2.0"
|
|
39
38
|
},
|
|
40
39
|
"scripts": {
|
|
41
40
|
"lint": "eslint \"*.js\" \"**/**/*.js\"",
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
//------------------------------------------------------------------------------
|
|
4
|
+
// Requirements
|
|
5
|
+
//------------------------------------------------------------------------------
|
|
6
|
+
|
|
7
|
+
const rule = require("../../../lib/rules/no-xpath"),
|
|
8
|
+
RuleTester = require("eslint").RuleTester;
|
|
9
|
+
|
|
10
|
+
//------------------------------------------------------------------------------
|
|
11
|
+
// Tests
|
|
12
|
+
//------------------------------------------------------------------------------
|
|
13
|
+
|
|
14
|
+
const ruleTester = new RuleTester();
|
|
15
|
+
ruleTester.run("no-xpath", rule, {
|
|
16
|
+
valid: [
|
|
17
|
+
{ code: 'cy.get("button").click({force: true})' },
|
|
18
|
+
],
|
|
19
|
+
|
|
20
|
+
invalid: [
|
|
21
|
+
{
|
|
22
|
+
code: "cy.xpath('//div[@class=\"container\"]/p[1]').click()",
|
|
23
|
+
errors: [{ messageId: "unexpected" }],
|
|
24
|
+
},
|
|
25
|
+
{
|
|
26
|
+
code: "cy.xpath('//p[1]').should('exist')",
|
|
27
|
+
errors: [{ messageId: "unexpected" }]
|
|
28
|
+
}
|
|
29
|
+
],
|
|
30
|
+
});
|