docs: automate docs with eslint-doc-generator

cypress-io · Nov 28, 2022 · 7953242 · 7953242
1 parent 874c51f
commit 7953242
Show file tree

Hide file tree

Showing 17 changed files with 17,991 additions and 649 deletions.
diff --git a/.eslintrc.json b/.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)" }]
+  }
 }
diff --git a/README.md b/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
 ```
@@ -63,6 +65,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.
@@ -110,21 +114,24 @@ For more, see the [ESLint rules](https://eslint.org/docs/user-guide/configuring/
 
 ## Rules
 
-These rules enforce some of the [best practices recommended for using Cypress](https://on.cypress.io/best-practices).
+<!-- begin auto-generated rules list -->
 
-Rules with a check mark (✅) are enabled by default while using the `plugin:cypress/recommended` config.
+💼 Configurations enabled in.\
+✅ Set in the `recommended` configuration.
 
-**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).
+| 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 `data-*` attribute selectors                                                            |    |
+
+<!-- end auto-generated rules list -->
 
-|     | 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                  |
-|     | [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 |
+**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).
 
 ## Chai and `no-unused-expressions`
 
@@ -160,13 +167,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>
diff --git a/docs/rules/assertion-before-screenshot.md b/docs/rules/assertion-before-screenshot.md
@@ -1,3 +1,7 @@
+# Require asserting on the page state before taking a screenshot, so the screenshot is consistent (`cypress/assertion-before-screenshot`)
+
+<!-- end auto-generated rule header -->
+
 ## Assertion Before Screenshot
 
 If you take screenshots without assertions then you may get different screenshots depending on timing.

diff --git a/docs/rules/no-assigning-return-values.md b/docs/rules/no-assigning-return-values.md
@@ -1,3 +1,9 @@
+# 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 -->
+
 ## No Assigning Return Values
 
 See [the Cypress Best Practices guide](https://on.cypress.io/best-practices#Assigning-Return-Values).
diff --git a/docs/rules/no-async-tests.md b/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.
 

diff --git a/docs/rules/no-force.md b/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.

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

diff --git a/docs/rules/no-unnecessary-waiting.md b/docs/rules/no-unnecessary-waiting.md
@@ -1,3 +1,8 @@
+# Disallow waiting for arbitrary time periods (`cypress/no-unnecessary-waiting`)
+
+💼 This rule is enabled in the ✅ `recommended` config.
+
+<!-- end auto-generated rule header -->
 ## No Assigning Return Values
 
 See [the Cypress Best Practices guide](https://on.cypress.io/best-practices#Unnecessary-Waiting).
diff --git a/docs/rules/require-data-selectors.md b/docs/rules/require-data-selectors.md
@@ -1,4 +1,9 @@
+# Require `data-*` attribute selectors (`cypress/require-data-selectors`)
+
+<!-- end auto-generated rule header -->
+
 ## Only allow `data-*` attribute selectors (require-data-selectors)
+
 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 +13,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 +23,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]')

diff --git a/lib/rules/assertion-before-screenshot.js b/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,
     },

diff --git a/lib/rules/no-assigning-return-values.js b/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',

diff --git a/lib/rules/no-async-tests.js b/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,
     },

diff --git a/lib/rules/no-pause.js b/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,
     },

diff --git a/lib/rules/no-unnecessary-waiting.js b/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',

diff --git a/lib/rules/require-data-selectors.js b/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 `data-*` attribute selectors',
       category: 'Possible Errors',
       recommended: false,
       url: 'https://docs.cypress.io/guides/references/best-practices.html#Selecting-Elements',