Skip to content

Commit 3e3412d

Browse files
MikeMcC399MikeMcC399
committed
docs: swap flat and legacy config doc locations
1 parent 5210ab9 commit 3e3412d

File tree

3 files changed

+271
-255
lines changed

3 files changed

+271
-255
lines changed

‎ESLINTRC-CONFIG.md

+147
Original file line numberDiff line numberDiff line change
@@ -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+
```

‎FLAT-CONFIG.md

+2-141
Original file line numberDiff line numberDiff line change
@@ -1,144 +1,5 @@
11
# Cypress ESLint Plugin - Flat Config
22

3-
This document supplements the [README](README.md) document and describes how to use the Cypress ESLint Plugin (`eslint-plugin-cypress`) in an ESLint flat config environment.
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.
44

5-
Usage with ESLint `9.x` is described.
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': 'error',
114-
'mocha/no-skipped-tests': 'error',
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) 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.recommendedFlat`:
127-
128-
```shell
129-
npm install eslint-plugin-chai-friendly@^1.0.1 --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.recommendedFlat,
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.

0 commit comments

Comments
 (0)