eslint-plugin-cypress 3.6.0 → 4.1.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/ESLINTRC-CONFIG.md +147 -0
- package/FLAT-CONFIG.md +2 -143
- package/README.md +123 -119
- package/circle.yml +4 -27
- package/lib/flat.js +0 -7
- package/package.json +7 -9
|
@@ -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,146 +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
|
-
Cypress ESLint Plugin (`eslint-plugin-cypress`) in release [3.2.0](https://github.com/cypress-io/eslint-plugin-cypress/releases/tag/v3.2.0) offered the first support of ESLint `9.x` flat config files using the [Backwards compatibility utility](https://eslint.org/blog/2022/08/new-config-system-part-2/#backwards-compatibility-utility). Current releases have removed the dependency on this utility and the examples in this document have been updated correspondingly.
|
|
14
|
-
|
|
15
|
-
The following information details installation and usage examples for `eslint-plugin-cypress` together with related plugins in an ESLint flat config environment.
|
|
16
|
-
|
|
17
|
-
## Installation
|
|
18
|
-
|
|
19
|
-
It is recommended to use a minimum ESLint `8.x` version [eslint@8.57.0](https://github.com/eslint/eslint/releases/tag/v8.57.0) or ESLint `9.x`.
|
|
20
|
-
|
|
21
|
-
```shell
|
|
22
|
-
npm install eslint eslint-plugin-cypress --save-dev
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
or
|
|
26
|
-
|
|
27
|
-
```shell
|
|
28
|
-
yarn add eslint eslint-plugin-cypress --dev
|
|
29
|
-
```
|
|
30
|
-
|
|
31
|
-
## Usage examples
|
|
32
|
-
|
|
33
|
-
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:
|
|
34
|
-
|
|
35
|
-
```shell
|
|
36
|
-
import pluginCypress from 'eslint-plugin-cypress/flat'
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
There are two specific flat configurations available:
|
|
40
|
-
|
|
41
|
-
| Configuration | Content |
|
|
42
|
-
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
43
|
-
| `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). Additionally, `languageOptions` of `ecmaVersion: 2019` and `sourceType: 'module'` for backwards compatibility with earlier versions of this plugin are defined. There are no default rules enabled in this configuration. |
|
|
44
|
-
| `configs.recommended` | enables [recommended Rules](README.md#rules). It includes also `configs.global` (see above) |
|
|
45
|
-
|
|
46
|
-
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.
|
|
47
|
-
|
|
48
|
-
### Cypress
|
|
49
|
-
|
|
50
|
-
All rules from `eslint-plugin-cypress` are available through `eslint-plugin-cypress/flat`.
|
|
51
|
-
- [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`
|
|
52
|
-
|
|
53
|
-
```js
|
|
54
|
-
import pluginCypress from 'eslint-plugin-cypress/flat'
|
|
55
|
-
export default [
|
|
56
|
-
{
|
|
57
|
-
plugins: {
|
|
58
|
-
cypress: pluginCypress
|
|
59
|
-
},
|
|
60
|
-
rules: {
|
|
61
|
-
'cypress/unsafe-to-chain-command': 'error'
|
|
62
|
-
}
|
|
63
|
-
}
|
|
64
|
-
]
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
### Cypress recommended
|
|
68
|
-
|
|
69
|
-
The `eslint-plugin-cypress` [recommended rules](README.md#rules) `configs.recommended` are activated, except for
|
|
70
|
-
- [cypress/no-unnecessary-waiting](https://github.com/cypress-io/eslint-plugin-cypress/blob/master/docs/rules/no-unnecessary-waiting.md) set to `off`
|
|
71
|
-
|
|
72
|
-
```js
|
|
73
|
-
import pluginCypress from 'eslint-plugin-cypress/flat'
|
|
74
|
-
export default [
|
|
75
|
-
pluginCypress.configs.recommended,
|
|
76
|
-
{
|
|
77
|
-
rules: {
|
|
78
|
-
'cypress/no-unnecessary-waiting': 'off'
|
|
79
|
-
}
|
|
80
|
-
}
|
|
81
|
-
]
|
|
82
|
-
```
|
|
83
|
-
|
|
84
|
-
### Cypress globals
|
|
85
|
-
|
|
86
|
-
The `configs.globals` are activated.
|
|
87
|
-
|
|
88
|
-
```js
|
|
89
|
-
import pluginCypress from 'eslint-plugin-cypress/flat'
|
|
90
|
-
export default [
|
|
91
|
-
pluginCypress.configs.globals
|
|
92
|
-
]
|
|
93
|
-
```
|
|
94
|
-
|
|
95
|
-
### Cypress and Mocha recommended
|
|
96
|
-
|
|
97
|
-
[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`.
|
|
98
|
-
|
|
99
|
-
The settings for individual `mocha` rules from the `configs.flat.recommended` option are changed.
|
|
100
|
-
- [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`
|
|
101
|
-
- [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`
|
|
102
|
-
|
|
103
|
-
```shell
|
|
104
|
-
npm install eslint-plugin-mocha@^10.4.3 --save-dev
|
|
105
|
-
```
|
|
106
|
-
|
|
107
|
-
```js
|
|
108
|
-
import pluginMocha from 'eslint-plugin-mocha'
|
|
109
|
-
import pluginCypress from 'eslint-plugin-cypress/flat'
|
|
110
|
-
export default [
|
|
111
|
-
pluginMocha.configs.flat.recommended,
|
|
112
|
-
pluginCypress.configs.recommended,
|
|
113
|
-
{
|
|
114
|
-
rules: {
|
|
115
|
-
'mocha/no-exclusive-tests': 'warn',
|
|
116
|
-
'mocha/no-skipped-tests': 'warn',
|
|
117
|
-
'mocha/no-mocha-arrows': 'off',
|
|
118
|
-
'cypress/no-unnecessary-waiting': 'off'
|
|
119
|
-
}
|
|
120
|
-
}
|
|
121
|
-
]
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
### Cypress and Chai recommended
|
|
125
|
-
|
|
126
|
-
[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`.
|
|
127
|
-
|
|
128
|
-
The recommended rules for both plugins are used: `pluginCypress.configs.recommended` and `pluginChaiFriendly.configs.recommended`:
|
|
129
|
-
|
|
130
|
-
```shell
|
|
131
|
-
npm install eslint-plugin-chai-friendly@^0.8.0 --save-dev
|
|
132
|
-
```
|
|
133
|
-
|
|
134
|
-
```js
|
|
135
|
-
import pluginCypress from 'eslint-plugin-cypress/flat'
|
|
136
|
-
import pluginChaiFriendly from 'eslint-plugin-chai-friendly'
|
|
137
|
-
export default [
|
|
138
|
-
pluginCypress.configs.recommended,
|
|
139
|
-
pluginChaiFriendly.configs.recommended,
|
|
140
|
-
{
|
|
141
|
-
rules: {
|
|
142
|
-
'cypress/no-unnecessary-waiting': 'off',
|
|
143
|
-
},
|
|
144
|
-
}
|
|
145
|
-
]
|
|
146
|
-
```
|
|
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
|
@@ -6,77 +6,113 @@ Note: If you installed ESLint globally then you must also install `eslint-plugin
|
|
|
6
6
|
|
|
7
7
|
## Installation
|
|
8
8
|
|
|
9
|
-
Prerequisites: [ESLint](https://www.npmjs.com/package/eslint) `
|
|
10
|
-
This plugin supports the use of [Flat config files](https://eslint.org/docs/latest/use/configure/configuration-files) with ESLint `8.57.0` and above.
|
|
9
|
+
Prerequisites: [ESLint](https://www.npmjs.com/package/eslint) `v9`. Lower versions are no longer supported.
|
|
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
|
-
## Deprecations
|
|
21
|
-
|
|
22
|
-
The use of ESLint `v7` and `v8` with `eslint-plugin-cypress` is deprecated and support will be removed in a future version of this plugin. ESLint `v7` reached end-of-life on Apr 9, 2022 and ESLint `v8` reached end-of-life on Oct 5, 2024. Users are encouraged to migrate to ESLint `v9`. See [ESLint Version Support](https://eslint.org/version-support/) for ESLint's current release lines.
|
|
23
|
-
|
|
24
19
|
## Usage
|
|
25
20
|
|
|
26
|
-
|
|
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.
|
|
27
22
|
|
|
28
|
-
|
|
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:
|
|
29
24
|
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
"plugins": [
|
|
33
|
-
"cypress"
|
|
34
|
-
]
|
|
35
|
-
}
|
|
25
|
+
```shell
|
|
26
|
+
import pluginCypress from 'eslint-plugin-cypress/flat'
|
|
36
27
|
```
|
|
37
28
|
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
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
|
+
| [require-data-selectors](docs/rules/require-data-selectors.md) | require `data-*` attribute selectors | |
|
|
58
|
+
| [unsafe-to-chain-command](docs/rules/unsafe-to-chain-command.md) | disallow actions within chains | ✅ |
|
|
59
|
+
|
|
60
|
+
<!-- end auto-generated rules list -->
|
|
61
|
+
|
|
62
|
+
## Usage examples
|
|
63
|
+
|
|
64
|
+
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.
|
|
65
|
+
|
|
66
|
+
### Cypress
|
|
67
|
+
|
|
68
|
+
All rules from `eslint-plugin-cypress` are available through `eslint-plugin-cypress/flat` and can be individually activated.
|
|
69
|
+
- [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`
|
|
70
|
+
|
|
71
|
+
```js
|
|
72
|
+
import pluginCypress from 'eslint-plugin-cypress/flat'
|
|
73
|
+
export default [
|
|
74
|
+
{
|
|
75
|
+
plugins: {
|
|
76
|
+
cypress: pluginCypress
|
|
77
|
+
},
|
|
78
|
+
rules: {
|
|
79
|
+
'cypress/unsafe-to-chain-command': 'error'
|
|
80
|
+
}
|
|
51
81
|
}
|
|
52
|
-
|
|
82
|
+
]
|
|
53
83
|
```
|
|
54
84
|
|
|
55
|
-
|
|
85
|
+
### Cypress recommended
|
|
56
86
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
87
|
+
The `eslint-plugin-cypress` [recommended rules](#rules) `configs.recommended` are activated, except for
|
|
88
|
+
- [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`
|
|
89
|
+
|
|
90
|
+
```js
|
|
91
|
+
import pluginCypress from 'eslint-plugin-cypress/flat'
|
|
92
|
+
export default [
|
|
93
|
+
pluginCypress.configs.recommended,
|
|
94
|
+
{
|
|
95
|
+
rules: {
|
|
96
|
+
'cypress/no-unnecessary-waiting': 'off'
|
|
97
|
+
}
|
|
61
98
|
}
|
|
62
|
-
|
|
99
|
+
]
|
|
63
100
|
```
|
|
64
101
|
|
|
65
|
-
|
|
102
|
+
### Cypress globals
|
|
66
103
|
|
|
67
|
-
|
|
104
|
+
The `configs.globals` are activated.
|
|
68
105
|
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
}
|
|
106
|
+
```js
|
|
107
|
+
import pluginCypress from 'eslint-plugin-cypress/flat'
|
|
108
|
+
export default [
|
|
109
|
+
pluginCypress.configs.globals
|
|
110
|
+
]
|
|
75
111
|
```
|
|
76
112
|
|
|
77
113
|
## Disable rules
|
|
78
114
|
|
|
79
|
-
You can disable specific rules per file, for a portion of a file, or for a single line.
|
|
115
|
+
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 ...
|
|
80
116
|
|
|
81
117
|
Disable the `cypress/no-unnecessary-waiting` rule for the entire file by placing this at the start of the file:
|
|
82
118
|
|
|
@@ -117,99 +153,67 @@ it('waits for a second', () => {
|
|
|
117
153
|
})
|
|
118
154
|
```
|
|
119
155
|
|
|
120
|
-
For more, see the [ESLint rules](https://eslint.org/docs/user-guide/configuring/rules) documentation.
|
|
121
|
-
|
|
122
|
-
## Rules
|
|
123
|
-
|
|
124
|
-
These rules enforce some of the [best practices recommended for using Cypress](https://on.cypress.io/best-practices).
|
|
125
|
-
|
|
126
|
-
<!-- begin auto-generated rules list -->
|
|
127
|
-
|
|
128
|
-
💼 Configurations enabled in.\
|
|
129
|
-
✅ Set in the `recommended` configuration.
|
|
130
|
-
|
|
131
|
-
| Name | Description | 💼 |
|
|
132
|
-
| :----------------------------------------------------------------------- | :--------------------------------------------------------- | :- |
|
|
133
|
-
| [assertion-before-screenshot](docs/rules/assertion-before-screenshot.md) | require screenshots to be preceded by an assertion | |
|
|
134
|
-
| [no-assigning-return-values](docs/rules/no-assigning-return-values.md) | disallow assigning return values of `cy` calls | ✅ |
|
|
135
|
-
| [no-async-before](docs/rules/no-async-before.md) | disallow using `async`/`await` in Cypress `before` methods | |
|
|
136
|
-
| [no-async-tests](docs/rules/no-async-tests.md) | disallow using `async`/`await` in Cypress test cases | ✅ |
|
|
137
|
-
| [no-debug](docs/rules/no-debug.md) | disallow using `cy.debug()` calls | |
|
|
138
|
-
| [no-force](docs/rules/no-force.md) | disallow using `force: true` with action commands | |
|
|
139
|
-
| [no-pause](docs/rules/no-pause.md) | disallow using `cy.pause()` calls | |
|
|
140
|
-
| [no-unnecessary-waiting](docs/rules/no-unnecessary-waiting.md) | disallow waiting for arbitrary time periods | ✅ |
|
|
141
|
-
| [require-data-selectors](docs/rules/require-data-selectors.md) | require `data-*` attribute selectors | |
|
|
142
|
-
| [unsafe-to-chain-command](docs/rules/unsafe-to-chain-command.md) | disallow actions within chains | ✅ |
|
|
143
|
-
|
|
144
|
-
<!-- end auto-generated rules list -->
|
|
145
|
-
|
|
146
156
|
## Mocha and Chai
|
|
147
157
|
|
|
148
158
|
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`.
|
|
149
159
|
|
|
150
160
|
## Mocha `.only` and `.skip`
|
|
151
161
|
|
|
152
|
-
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
|
|
162
|
+
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`.
|
|
153
163
|
|
|
154
|
-
|
|
155
|
-
|
|
164
|
+
### Cypress and Mocha recommended
|
|
165
|
+
|
|
166
|
+
[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`.
|
|
167
|
+
|
|
168
|
+
The settings for individual `mocha` rules from the `configs.flat.recommended` option are changed.
|
|
169
|
+
- [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`
|
|
170
|
+
- [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`
|
|
171
|
+
|
|
172
|
+
```shell
|
|
173
|
+
npm install eslint-plugin-mocha@^10.5.0 --save-dev
|
|
156
174
|
```
|
|
157
175
|
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
176
|
+
```js
|
|
177
|
+
import pluginMocha from 'eslint-plugin-mocha'
|
|
178
|
+
import pluginCypress from 'eslint-plugin-cypress/flat'
|
|
179
|
+
export default [
|
|
180
|
+
pluginMocha.configs.flat.recommended,
|
|
181
|
+
pluginCypress.configs.recommended,
|
|
182
|
+
{
|
|
183
|
+
rules: {
|
|
184
|
+
'mocha/no-exclusive-tests': 'error',
|
|
185
|
+
'mocha/no-skipped-tests': 'error',
|
|
186
|
+
'mocha/no-mocha-arrows': 'off',
|
|
187
|
+
'cypress/no-unnecessary-waiting': 'off'
|
|
188
|
+
}
|
|
169
189
|
}
|
|
170
|
-
|
|
190
|
+
]
|
|
171
191
|
```
|
|
172
192
|
|
|
173
|
-
|
|
193
|
+
### Cypress and Chai recommended
|
|
174
194
|
|
|
175
|
-
|
|
176
|
-
{
|
|
177
|
-
"extends": [
|
|
178
|
-
"plugin:cypress/recommended",
|
|
179
|
-
"plugin:mocha/recommended"
|
|
180
|
-
]
|
|
181
|
-
}
|
|
182
|
-
```
|
|
195
|
+
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).
|
|
183
196
|
|
|
184
|
-
|
|
197
|
+
[eslint-plugin-chai-friendly](https://www.npmjs.com/package/eslint-plugin-chai-friendly) is combined with the Cypress plugin `eslint-plugin-cypress`.
|
|
185
198
|
|
|
186
|
-
|
|
199
|
+
The recommended rules for both plugins are used: `pluginCypress.configs.recommended` and `pluginChaiFriendly.configs.recommendedFlat`:
|
|
187
200
|
|
|
188
|
-
```
|
|
189
|
-
npm install
|
|
201
|
+
```shell
|
|
202
|
+
npm install eslint-plugin-chai-friendly@^1.0.1 --save-dev
|
|
190
203
|
```
|
|
191
204
|
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
"chai-friendly/no-unused-expressions": 2
|
|
205
|
+
```js
|
|
206
|
+
import pluginCypress from 'eslint-plugin-cypress/flat'
|
|
207
|
+
import pluginChaiFriendly from 'eslint-plugin-chai-friendly'
|
|
208
|
+
export default [
|
|
209
|
+
pluginCypress.configs.recommended,
|
|
210
|
+
pluginChaiFriendly.configs.recommendedFlat,
|
|
211
|
+
{
|
|
212
|
+
rules: {
|
|
213
|
+
'cypress/no-unnecessary-waiting': 'off',
|
|
214
|
+
},
|
|
203
215
|
}
|
|
204
|
-
|
|
205
|
-
```
|
|
206
|
-
|
|
207
|
-
Or you can simply add its `recommended` config:
|
|
208
|
-
|
|
209
|
-
```json
|
|
210
|
-
{
|
|
211
|
-
"extends": ["plugin:chai-friendly/recommended"]
|
|
212
|
-
}
|
|
216
|
+
]
|
|
213
217
|
```
|
|
214
218
|
|
|
215
219
|
## Contributing
|
package/circle.yml
CHANGED
|
@@ -5,13 +5,11 @@ workflows:
|
|
|
5
5
|
main:
|
|
6
6
|
jobs:
|
|
7
7
|
- lint
|
|
8
|
-
- test-v7
|
|
9
8
|
- test-v8
|
|
10
9
|
- test-v9
|
|
11
10
|
- release:
|
|
12
11
|
requires:
|
|
13
12
|
- lint
|
|
14
|
-
- test-v7
|
|
15
13
|
- test-v8
|
|
16
14
|
- test-v9
|
|
17
15
|
filters:
|
|
@@ -22,7 +20,7 @@ workflows:
|
|
|
22
20
|
jobs:
|
|
23
21
|
lint:
|
|
24
22
|
docker:
|
|
25
|
-
- image: cimg/node:
|
|
23
|
+
- image: cimg/node:22.11.0
|
|
26
24
|
steps:
|
|
27
25
|
- checkout
|
|
28
26
|
- run:
|
|
@@ -35,30 +33,9 @@ jobs:
|
|
|
35
33
|
name: Lint code
|
|
36
34
|
command: npm run lint
|
|
37
35
|
|
|
38
|
-
test-v7:
|
|
39
|
-
docker:
|
|
40
|
-
- image: cimg/node:20.12.2
|
|
41
|
-
steps:
|
|
42
|
-
- checkout
|
|
43
|
-
- run:
|
|
44
|
-
name: Install dependencies
|
|
45
|
-
command: npm ci
|
|
46
|
-
- run:
|
|
47
|
-
name: Remove unneeded plugins # minimum eslint@8.23.0 required
|
|
48
|
-
command: npm uninstall eslint-plugin-eslint-plugin eslint-plugin-n
|
|
49
|
-
- run:
|
|
50
|
-
name: Install ESLint 7
|
|
51
|
-
command: npm install eslint@7
|
|
52
|
-
- run:
|
|
53
|
-
name: Show ESLint version
|
|
54
|
-
command: npx eslint --version
|
|
55
|
-
- run:
|
|
56
|
-
name: Test ESLint 7
|
|
57
|
-
command: npm run test:legacy
|
|
58
|
-
|
|
59
36
|
test-v8:
|
|
60
37
|
docker:
|
|
61
|
-
- image: cimg/node:
|
|
38
|
+
- image: cimg/node:22.11.0
|
|
62
39
|
steps:
|
|
63
40
|
- checkout
|
|
64
41
|
- run:
|
|
@@ -76,7 +53,7 @@ jobs:
|
|
|
76
53
|
|
|
77
54
|
test-v9:
|
|
78
55
|
docker:
|
|
79
|
-
- image: cimg/node:
|
|
56
|
+
- image: cimg/node:22.11.0
|
|
80
57
|
steps:
|
|
81
58
|
- checkout
|
|
82
59
|
- run:
|
|
@@ -94,7 +71,7 @@ jobs:
|
|
|
94
71
|
|
|
95
72
|
release:
|
|
96
73
|
docker:
|
|
97
|
-
- image: cimg/node:
|
|
74
|
+
- image: cimg/node:22.11.0
|
|
98
75
|
steps:
|
|
99
76
|
- checkout
|
|
100
77
|
- run:
|
package/lib/flat.js
CHANGED
|
@@ -27,11 +27,6 @@ const commonGlobals =
|
|
|
27
27
|
chai: false,
|
|
28
28
|
}, globals.browser, globals.mocha)
|
|
29
29
|
|
|
30
|
-
const commonLanguageOptions = {
|
|
31
|
-
ecmaVersion: 2019,
|
|
32
|
-
sourceType: 'module'
|
|
33
|
-
}
|
|
34
|
-
|
|
35
30
|
Object.assign(plugin.configs, {
|
|
36
31
|
globals: {
|
|
37
32
|
name: 'cypress/globals',
|
|
@@ -41,7 +36,6 @@ Object.assign(plugin.configs, {
|
|
|
41
36
|
languageOptions: {
|
|
42
37
|
globals:
|
|
43
38
|
commonGlobals,
|
|
44
|
-
...commonLanguageOptions
|
|
45
39
|
}
|
|
46
40
|
}
|
|
47
41
|
})
|
|
@@ -61,7 +55,6 @@ Object.assign(plugin.configs, {
|
|
|
61
55
|
languageOptions: {
|
|
62
56
|
globals:
|
|
63
57
|
commonGlobals,
|
|
64
|
-
...commonLanguageOptions
|
|
65
58
|
}
|
|
66
59
|
}
|
|
67
60
|
})
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "eslint-plugin-cypress",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "4.1.0",
|
|
4
4
|
"description": "An ESLint plugin for projects using Cypress",
|
|
5
5
|
"main": "legacy.js",
|
|
6
6
|
"exports": {
|
|
@@ -23,21 +23,19 @@
|
|
|
23
23
|
},
|
|
24
24
|
"homepage": "https://github.com/cypress-io/eslint-plugin-cypress#readme",
|
|
25
25
|
"peerDependencies": {
|
|
26
|
-
"eslint": ">=
|
|
26
|
+
"eslint": ">=9"
|
|
27
27
|
},
|
|
28
28
|
"dependencies": {
|
|
29
|
-
"globals": "^
|
|
29
|
+
"globals": "^15.11.0"
|
|
30
30
|
},
|
|
31
31
|
"devDependencies": {
|
|
32
|
-
"
|
|
33
|
-
"
|
|
34
|
-
"eslint": "^9.12.0",
|
|
35
|
-
"eslint-plugin-eslint-plugin": "^6.2.0",
|
|
32
|
+
"eslint": "^9.13.0",
|
|
33
|
+
"eslint-plugin-eslint-plugin": "^6.3.1",
|
|
36
34
|
"eslint-plugin-mocha": "^10.5.0",
|
|
37
|
-
"eslint-plugin-n": "^17.
|
|
35
|
+
"eslint-plugin-n": "^17.11.1",
|
|
38
36
|
"husky": "^9.1.6",
|
|
39
37
|
"jest": "^29.7.0",
|
|
40
|
-
"semantic-release": "24.
|
|
38
|
+
"semantic-release": "24.2.0"
|
|
41
39
|
},
|
|
42
40
|
"scripts": {
|
|
43
41
|
"lint": "eslint \"*.js\" \"**/**/*.js\"",
|