1 | # Cypress ESLint Plugin [![CircleCI](https://circleci.com/gh/cypress-io/eslint-plugin-cypress/tree/master.svg?style=svg)](https://circleci.com/gh/cypress-io/eslint-plugin-cypress/tree/master)
|
2 |
|
3 | An [ESLint](https://eslint.org) plugin for your [Cypress](https://cypress.io) tests.
|
4 |
|
5 | Note: If you installed ESLint globally then you must also install `eslint-plugin-cypress` globally.
|
6 |
|
7 | ## Installation
|
8 |
|
9 | ```sh
|
10 | npm install eslint-plugin-cypress --save-dev
|
11 | ```
|
12 |
|
13 | ## Usage
|
14 |
|
15 | Add an `.eslintrc.json` file to your `cypress` directory with the following:
|
16 |
|
17 | ```json
|
18 | {
|
19 | "plugins": [
|
20 | "cypress"
|
21 | ]
|
22 | }
|
23 | ```
|
24 |
|
25 | You can add rules:
|
26 |
|
27 | ```json
|
28 | {
|
29 | "rules": {
|
30 | "cypress/no-assigning-return-values": "error",
|
31 | "cypress/no-unnecessary-waiting": "error",
|
32 | "cypress/assertion-before-screenshot": "warn",
|
33 | "cypress/no-force": "warn"
|
34 | }
|
35 | }
|
36 | ```
|
37 |
|
38 | You can whitelist globals provided by Cypress:
|
39 |
|
40 | ```json
|
41 | {
|
42 | "env": {
|
43 | "cypress/globals": true
|
44 | }
|
45 | }
|
46 | ```
|
47 |
|
48 | ## Recommended configuration
|
49 |
|
50 | Use the recommended configuration and you can forego configuring _plugins_, _rules_, and _env_ individually. See below for which rules are included.
|
51 |
|
52 | ```json
|
53 | {
|
54 | "extends": [
|
55 | "plugin:cypress/recommended"
|
56 | ]
|
57 | }
|
58 | ```
|
59 |
|
60 | ## Rules
|
61 |
|
62 | These rules enforce some of the [best practices recommended for using Cypress](https://on.cypress.io/best-practices).
|
63 |
|
64 | Rules with a check mark (✅) are enabled by default while using the `plugin:cypress/recommended` config.
|
65 |
|
66 | **NOTE**: These rules currently require eslint 5.0 or greater. If you would like support added for eslint 4.x, please 👍 [this issue](https://github.com/cypress-io/eslint-plugin-cypress/issues/14).
|
67 |
|
68 | | | Rule ID | Description |
|
69 | | :-- | :------------------------------------------------------------------------- | :-------------------------------------------------------------- |
|
70 | | ✅ | [no-assigning-return-values](./docs/rules/no-assigning-return-values.md) | Prevent assigning return values of cy calls |
|
71 | | ✅ | [no-unnecessary-waiting](./docs/rules/no-unnecessary-waiting.md) | Prevent waiting for arbitrary time periods |
|
72 | | | [no-force](./docs/rules/no-force.md) | Disallow using `force: true` with action commands |
|
73 | | | [assertion-before-screenshot](./docs/rules/assertion-before-screenshot.md) | Ensure screenshots are preceded by an assertion |
|
74 | | | [require-data-selectors](./docs/rules/require-data-selectors.md) | Only allow data-\* attribute selectors (require-data-selectors) |
|
75 |
|
76 | ## Chai and `no-unused-expressions`
|
77 |
|
78 | 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).
|
79 |
|
80 | ```sh
|
81 | npm install --save-dev eslint-plugin-chai-friendly
|
82 | ```
|
83 |
|
84 | In your `.eslintrc.json`:
|
85 |
|
86 | ```json
|
87 | {
|
88 | "plugins": [
|
89 | "cypress",
|
90 | "chai-friendly"
|
91 | ],
|
92 | "rules": {
|
93 | "no-unused-expressions": 0,
|
94 | "chai-friendly/no-unused-expressions": 2
|
95 | }
|
96 | }
|
97 | ```
|
98 |
|
99 | ## Contribution Guide
|
100 |
|
101 | To add a new rule:
|
102 | * Fork and clone this repository
|
103 | * Generate a new rule (a [yeoman generator](https://github.com/eslint/generator-eslint) is available)
|
104 | * Run `yarn start` or `npm start`
|
105 | * Write test scenarios then implement logic
|
106 | * Describe the rule in the generated `docs` file
|
107 | * Make sure all tests are passing
|
108 | * Add the rule to this README
|
109 | * Create a PR
|
110 |
|
111 | Use the following commit message conventions: https://github.com/semantic-release/semantic-release#commit-message-format
|