Skip to content

Commit

Permalink
Merge pull request #239 from MikeMcC399/docs/swap-flat-legacy
Browse files Browse the repository at this point in the history 
docs: swap flat and legacy config doc locations
  • Loading branch information
@jennifer-shehane
jennifer-shehane authored Oct 21, 2024
2 parents 5210ab9 + 3e3412d commit ee9980a
Show file tree
Hide file tree
Showing 3 changed files with 271 additions and 255 deletions.
147 changes: 147 additions & 0 deletions ESLINTRC-CONFIG.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,147 @@
# Cypress ESLint Plugin - Legacy Config

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.

Usage with ESLint `9.x` is described.

## Deprecations

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).

## Installation

Use a minimum ESLint `9.x`.

```shell
npm install eslint eslint-plugin-cypress --save-dev
```

or

```shell
yarn add eslint eslint-plugin-cypress --dev
```

## Usage

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:

```json
{
"plugins": [
"cypress"
]
}
```

You can add rules - see [Rules](./README.md#rules) for a list of the available rules:

```json
{
"rules": {
"cypress/no-assigning-return-values": "error",
"cypress/no-unnecessary-waiting": "error",
"cypress/assertion-before-screenshot": "warn",
"cypress/no-force": "warn",
"cypress/no-async-tests": "error",
"cypress/no-async-before": "error",
"cypress/no-pause": "error",
"cypress/no-debug": "error"
}
}
```

You can allow certain globals provided by Cypress:

```json
{
"env": {
"cypress/globals": true
}
}
```

## Recommended configuration

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.

```json
{
"extends": [
"plugin:cypress/recommended"
]
}
```

## Rules

See the [Rules](./README.md#rules) list in the main [README](./README.md) document.

## Mocha and Chai

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`.

## Mocha `.only` and `.skip`

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`:

```sh
npm install --save-dev eslint-plugin-mocha
```

In your `.eslintrc.json`:

```json
{
"plugins": [
"cypress",
"mocha"
],
"rules": {
"mocha/no-exclusive-tests": "warn",
"mocha/no-skipped-tests": "warn"
}
}
```

Or you can simply use the `cypress/recommended` and `mocha/recommended` configurations together, for example:

```json
{
"extends": [
"plugin:cypress/recommended",
"plugin:mocha/recommended"
]
}
```

## Chai and `no-unused-expressions`

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).

```sh
npm install --save-dev eslint-plugin-chai-friendly
```

In your `.eslintrc.json`:

```json
{
"plugins": [
"cypress",
"chai-friendly"
],
"rules": {
"no-unused-expressions": 0,
"chai-friendly/no-unused-expressions": 2
}
}
```

Or you can simply add its `recommended` config:

```json
{
"extends": ["plugin:chai-friendly/recommended"]
}
```
143 changes: 2 additions & 141 deletions FLAT-CONFIG.md
View file
Original file line number Diff line number Diff line change
@@ -1,144 +1,5 @@
# Cypress ESLint Plugin - Flat Config

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.
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.

Usage with ESLint `9.x` is described.

## Introduction

[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.

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`.

The following information details installation and usage examples for `eslint-plugin-cypress` together with related plugins in an ESLint flat config environment.

## Installation

Use a minimum ESLint `9.x`.

```shell
npm install eslint eslint-plugin-cypress --save-dev
```

or

```shell
yarn add eslint eslint-plugin-cypress --dev
```

## Usage examples

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:

```shell
import pluginCypress from 'eslint-plugin-cypress/flat'
```

There are two specific flat configurations available:

| Configuration | Content |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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. |
| `configs.recommended` | enables [recommended Rules](README.md#rules). It includes also `configs.global` (see above) |

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.

### Cypress

All rules from `eslint-plugin-cypress` are available through `eslint-plugin-cypress/flat`.
- [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`

```js
import pluginCypress from 'eslint-plugin-cypress/flat'
export default [
{
plugins: {
cypress: pluginCypress
},
rules: {
'cypress/unsafe-to-chain-command': 'error'
}
}
]
```

### Cypress recommended

The `eslint-plugin-cypress` [recommended rules](README.md#rules) `configs.recommended` are activated, except for
- [cypress/no-unnecessary-waiting](https://github.com/cypress-io/eslint-plugin-cypress/blob/master/docs/rules/no-unnecessary-waiting.md) set to `off`

```js
import pluginCypress from 'eslint-plugin-cypress/flat'
export default [
pluginCypress.configs.recommended,
{
rules: {
'cypress/no-unnecessary-waiting': 'off'
}
}
]
```

### Cypress globals

The `configs.globals` are activated.

```js
import pluginCypress from 'eslint-plugin-cypress/flat'
export default [
pluginCypress.configs.globals
]
```

### Cypress and Mocha recommended

[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`.

The settings for individual `mocha` rules from the `configs.flat.recommended` option are changed.
- [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`
- [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`

```shell
npm install eslint-plugin-mocha@^10.4.3 --save-dev
```

```js
import pluginMocha from 'eslint-plugin-mocha'
import pluginCypress from 'eslint-plugin-cypress/flat'
export default [
pluginMocha.configs.flat.recommended,
pluginCypress.configs.recommended,
{
rules: {
'mocha/no-exclusive-tests': 'error',
'mocha/no-skipped-tests': 'error',
'mocha/no-mocha-arrows': 'off',
'cypress/no-unnecessary-waiting': 'off'
}
}
]
```

### Cypress and Chai recommended

[eslint-plugin-chai-friendly](https://www.npmjs.com/package/eslint-plugin-chai-friendly) is combined with the Cypress plugin `eslint-plugin-cypress`.

The recommended rules for both plugins are used: `pluginCypress.configs.recommended` and `pluginChaiFriendly.configs.recommendedFlat`:

```shell
npm install eslint-plugin-chai-friendly@^1.0.1 --save-dev
```

```js
import pluginCypress from 'eslint-plugin-cypress/flat'
import pluginChaiFriendly from 'eslint-plugin-chai-friendly'
export default [
pluginCypress.configs.recommended,
pluginChaiFriendly.configs.recommendedFlat,
{
rules: {
'cypress/no-unnecessary-waiting': 'off',
},
}
]
```
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.
Loading

0 comments on commit ee9980a

Please sign in to comment.