Automate docs with eslint-doc-generator

.eslintrc.json

@@ -1,8 +1,13 @@
 {
   "plugins": [
-    "@cypress/dev"
+    "@cypress/dev",
+    "eslint-plugin"
   ],
   "extends": [
-    "plugin:@cypress/dev/general"
-  ]
+    "plugin:@cypress/dev/general",
+    "plugin:eslint-plugin/recommended"
+  ],
+  "rules": {
+    "eslint-plugin/require-meta-docs-description": ["error", { "pattern": "^(Enforce|Require|Disallow)" }]
+  }
 }

README.md

@@ -9,7 +9,9 @@ Note: If you installed ESLint globally then you must also install `eslint-plugin
 ```sh
 npm install eslint-plugin-cypress --save-dev
 ```
+
 or
+
 ```sh
 yarn add eslint-plugin-cypress --dev
 ```
@@ -51,7 +53,17 @@ You can allow certain globals provided by Cypress:
 }
 ```
 
-## Recommended configuration
+## Configurations
+
+<!-- begin auto-generated configs list -->
+
+|    | Name          |
+| :- | :------------ |
+| ✅  | `recommended` |
+
+<!-- end auto-generated configs list -->
+
+### Recommended configuration
 
 Use the recommended configuration and you can forego configuring _plugins_, _rules_, and _env_ individually. See below for which rules are included.
 
@@ -63,6 +75,8 @@ Use the recommended configuration and you can forego configuring _plugins_, _rul
 }
 ```
 
+These rules enforce some of the [best practices recommended for using Cypress](https://on.cypress.io/best-practices).
+
 ## Disable rules
 
 You can disable specific rules per file, for a portion of a file, or for a single line.
@@ -112,20 +126,25 @@ For more, see the [ESLint rules](https://eslint.org/docs/user-guide/configuring/
 
 These rules enforce some of the [best practices recommended for using Cypress](https://on.cypress.io/best-practices).
 
-Rules with a check mark (✅) are enabled by default while using the `plugin:cypress/recommended` config.
-
 **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).
 
-|     | Rule ID                                                                    | Description                                                     |
-| :-- | :------------------------------------------------------------------------- | :-------------------------------------------------------------- |
-| ✅  | [no-assigning-return-values](./docs/rules/no-assigning-return-values.md)   | Prevent assigning return values of cy calls                     |
-| ✅  | [no-unnecessary-waiting](./docs/rules/no-unnecessary-waiting.md)           | Prevent waiting for arbitrary time periods                      |
-| ✅  | [no-async-tests](./docs/rules/no-async-tests.md)                           | Prevent using async/await in Cypress test case                  |
-| ✅  | [unsafe-to-chain-command](./docs/rules/unsafe-to-chain-command.md)         | Prevent chaining from unsafe to chain commands                  |
-|     | [no-force](./docs/rules/no-force.md)                                       | Disallow using `force: true` with action commands               |
-|     | [assertion-before-screenshot](./docs/rules/assertion-before-screenshot.md) | Ensure screenshots are preceded by an assertion                 |
-|     | [require-data-selectors](./docs/rules/require-data-selectors.md)           | Only allow data-\* attribute selectors (require-data-selectors) |
-|     | [no-pause](./docs/rules/no-pause.md)           | Disallow `cy.pause()` parent command |
+<!-- begin auto-generated rules list -->
+
+💼 Configurations enabled in.\
+✅ Set in the `recommended` configuration.
+
+| Name                                                                     | Description                                                                                                     | 💼 |
+| :----------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------- | :- |
+| [assertion-before-screenshot](docs/rules/assertion-before-screenshot.md) | Require asserting on the page state before taking a screenshot, so the screenshot is consistent                 |    |
+| [no-assigning-return-values](docs/rules/no-assigning-return-values.md)   | Disallow assigning return values of cy calls                                                                    | ✅  |
+| [no-async-tests](docs/rules/no-async-tests.md)                           | Disallow using async/await in Cypress test cases                                                                | ✅  |
+| [no-force](docs/rules/no-force.md)                                       | Disallow using of 'force: true' option for click and type calls                                                 |    |
+| [no-pause](docs/rules/no-pause.md)                                       | Disallow using of `cy.pause` calls                                                                              |    |
+| [no-unnecessary-waiting](docs/rules/no-unnecessary-waiting.md)           | Disallow waiting for arbitrary time periods                                                                     | ✅  |
+| [require-data-selectors](docs/rules/require-data-selectors.md)           | Require using `data-*` attributes to provide context to your selectors and insulate them from CSS or JS changes |    |
+| [unsafe-to-chain-command](docs/rules/unsafe-to-chain-command.md)         | Require actions to be in the end of chains, not in the middle                                                   | ✅  |
+
+<!-- end auto-generated rules list -->
 
 ## Chai and `no-unused-expressions`
 
@@ -161,13 +180,14 @@ Or you can simply add its `recommended` config:
 ## Contribution Guide
 
 To add a new rule:
-  * Fork and clone this repository
-  * Generate a new rule (a [yeoman generator](https://github.com/eslint/generator-eslint) is available)
-  * Run `yarn start` or `npm start`
-  * Write test scenarios then implement logic
-  * Describe the rule in the generated `docs` file
-  * Make sure all tests are passing
-  * Add the rule to this README
-  * Create a PR
-
-Use the following commit message conventions: https://github.com/semantic-release/semantic-release#commit-message-format
+
+* Fork and clone this repository
+* Generate a new rule (a [yeoman generator](https://github.com/eslint/generator-eslint) is available)
+* Run `yarn start` or `npm start`
+* Write test scenarios then implement logic
+* Describe the rule in the generated `docs` file
+* Make sure all tests are passing
+* Run `npm run update:eslint-docs` to update the README rules list and rule doc header
+* Create a PR
+
+Use the following commit message conventions: <https://github.com/semantic-release/semantic-release#commit-message-format>

docs/rules/assertion-before-screenshot.md

@@ -1,4 +1,6 @@
-## Assertion Before Screenshot
+# Require asserting on the page state before taking a screenshot, so the screenshot is consistent (`cypress/assertion-before-screenshot`)
+
+<!-- end auto-generated rule header -->
 
 If you take screenshots without assertions then you may get different screenshots depending on timing.
 

docs/rules/no-assigning-return-values.md

@@ -1,3 +1,7 @@
-## No Assigning Return Values
+# Disallow assigning return values of cy calls (`cypress/no-assigning-return-values`)
+
+💼 This rule is enabled in the ✅ `recommended` config.
+
+<!-- end auto-generated rule header -->
 
 See [the Cypress Best Practices guide](https://on.cypress.io/best-practices#Assigning-Return-Values).

docs/rules/no-async-tests.md

@@ -1,4 +1,8 @@
-# Prevent using async/await in Cypress test cases (no-async-tests)
+# Disallow using async/await in Cypress test cases (`cypress/no-async-tests`)
+
+💼 This rule is enabled in the ✅ `recommended` config.
+
+<!-- end auto-generated rule header -->
 
 Cypress tests [that return a promise will error](https://docs.cypress.io/guides/references/error-messages.html#Cypress-detected-that-you-returned-a-promise-from-a-command-while-also-invoking-one-or-more-cy-commands-in-that-promise) and cannot run successfully. An `async` function returns a promise under the hood, so a test using an `async` function will also error.
 

docs/rules/no-force.md

@@ -1,4 +1,6 @@
-# disallow using of 'force: true' option (no-force)
+# Disallow using of 'force: true' option for click and type calls (`cypress/no-force`)
+
+<!-- end auto-generated rule header -->
 
 Using `force: true` on inputs appears to be confusing rather than helpful.
 It usually silences the actual problem instead of providing a way to overcome it.

docs/rules/no-pause.md

@@ -1,4 +1,6 @@
-## Do not use `cy.pause` command
+# Disallow using of `cy.pause` calls (`cypress/no-pause`)
+
+<!-- end auto-generated rule header -->
 
 It is recommended to remove [cy.pause](https://on.cypress.io/pause) command before committing the specs to avoid other developers getting unexpected results.
 

docs/rules/no-unnecessary-waiting.md

@@ -1,3 +1,7 @@
-## No Unnecessary Waiting
+# Disallow waiting for arbitrary time periods (`cypress/no-unnecessary-waiting`)
+
+💼 This rule is enabled in the ✅ `recommended` config.
+
+<!-- end auto-generated rule header -->
 
 See [the Cypress Best Practices guide](https://on.cypress.io/best-practices#Unnecessary-Waiting).

docs/rules/require-data-selectors.md

@@ -1,4 +1,7 @@
-## Only allow `data-*` attribute selectors (require-data-selectors)
+# Require using `data-*` attributes to provide context to your selectors and insulate them from CSS or JS changes (`cypress/require-data-selectors`)
+
+<!-- end auto-generated rule header -->
+
 only allow `cy.get` to allow selectors that target `data-*` attributes
 
 See [the Cypress Best Practices guide](https://docs.cypress.io/guides/references/best-practices.html#Selecting-Elements).
@@ -8,6 +11,7 @@ See [the Cypress Best Practices guide](https://docs.cypress.io/guides/references
 ### Rule Details
 
 examples of **incorrect** code with `require-data-selectors`:
+
 ```js
 cy.get(".a")
 cy.get('[daedta-cy=submit]').click()
@@ -17,6 +21,7 @@ cy.get(".btn-.large").click()
 ```
 
 examples of **correct** code with `require-data-selectors`:
+
 ```js
 cy.get('[data-cy=submit]').click()
 cy.get('[data-QA=submit]')

docs/rules/unsafe-to-chain-command.md

@@ -1,3 +1,17 @@
-## Unsafe to chain command
+# Require actions to be in the end of chains, not in the middle (`cypress/unsafe-to-chain-command`)
+
+💼 This rule is enabled in the ✅ `recommended` config.
+
+<!-- end auto-generated rule header -->
 
 See [retry-ability guide](https://docs.cypress.io/guides/core-concepts/retry-ability#Actions-should-be-at-the-end-of-chains-not-the-middle).
+
+## Options
+
+<!-- begin auto-generated rule options list -->
+
+| Name      | Description                                                 | Type  | Default |
+| :-------- | :---------------------------------------------------------- | :---- | :------ |
+| `methods` | An additional list of methods to check for unsafe chaining. | Array | `[]`    |
+
+<!-- end auto-generated rule options list -->

lib/rules/assertion-before-screenshot.js

@@ -17,7 +17,7 @@ const assertionCommands = [
 module.exports = {
   meta: {
     docs: {
-      description: 'Assert on the page state before taking a screenshot, so the screenshot is consistent',
+      description: 'Require asserting on the page state before taking a screenshot, so the screenshot is consistent',
       category: 'Possible Errors',
       recommended: false,
     },

lib/rules/no-assigning-return-values.js

@@ -18,7 +18,7 @@ function get (obj, propertyString = '') {
 module.exports = {
   meta: {
     docs: {
-      description: 'Prevent assigning return values of cy calls',
+      description: 'Disallow assigning return values of cy calls',
       category: 'Possible Errors',
       recommended: true,
       url: 'https://on.cypress.io/best-practices#Assigning-Return-Values',

lib/rules/no-async-tests.js

@@ -3,7 +3,7 @@
 module.exports = {
   meta: {
     docs: {
-      description: 'Prevent using async/await in Cypress test cases',
+      description: 'Disallow using async/await in Cypress test cases',
       category: 'Possible Errors',
       recommended: true,
     },

lib/rules/no-pause.js

@@ -7,7 +7,7 @@
 module.exports = {
   meta: {
     docs: {
-      description: 'Disallow using of \'cy.pause\' calls',
+      description: 'Disallow using of `cy.pause` calls',
       category: 'Possible Errors',
       recommended: false,
     },

lib/rules/no-unnecessary-waiting.js

@@ -3,7 +3,7 @@
 module.exports = {
   meta: {
     docs: {
-      description: 'Prevent waiting for arbitrary time periods',
+      description: 'Disallow waiting for arbitrary time periods',
       category: 'Possible Errors',
       recommended: true,
       url: 'https://on.cypress.io/best-practices#Unnecessary-Waiting',

lib/rules/require-data-selectors.js

@@ -3,7 +3,7 @@
 module.exports = {
   meta: {
     docs: {
-      description: 'Use data-* attributes to provide context to your selectors and insulate them from CSS or JS changes https://docs.cypress.io/guides/references/best-practices.html#Selecting-Elements',
+      description: 'Require using `data-*` attributes to provide context to your selectors and insulate them from CSS or JS changes',
       category: 'Possible Errors',
       recommended: false,
       url: 'https://docs.cypress.io/guides/references/best-practices.html#Selecting-Elements',

lib/rules/unsafe-to-chain-command.js

@@ -3,7 +3,7 @@
 const { basename } = require('path')
 
 const NAME = basename(__dirname)
-const DESCRIPTION = 'Actions should be in the end of chains, not in the middle'
+const DESCRIPTION = 'Require actions to be in the end of chains, not in the middle'
 
 /**
  * Commands listed in the documentation with text: 'It is unsafe to chain further commands that rely on the subject after xxx.'
@@ -70,7 +70,8 @@ const getDefaultOptions = (context) => {
 module.exports = {
   meta: {
     docs: {
-      description: DESCRIPTION,
+      // TODO: false positive violation fixed in future version of eslint-plugin-eslint-plugin
+      description: DESCRIPTION, // eslint-disable-line eslint-plugin/require-meta-docs-description
       category: 'Possible Errors',
       recommended: true,
       url: 'https://docs.cypress.io/guides/core-concepts/retry-ability#Actions-should-be-at-the-end-of-chains-not-the-middle',