From 4299024dd8feee74df450d473588546f89a57b09 Mon Sep 17 00:00:00 2001 From: Bryan Mishkin <698306+bmish@users.noreply.github.com> Date: Mon, 7 Nov 2022 20:13:31 -0500 Subject: [PATCH] docs: automate docs with eslint-doc-generator (#275) --- .github/workflows/validate.yml | 4 ++ README.md | 43 +++++++++--------- build/generate-readme-table.js | 55 ----------------------- docs/rules/prefer-checked.md | 8 +++- docs/rules/prefer-empty.md | 8 +++- docs/rules/prefer-enabled-disabled.md | 8 +++- docs/rules/prefer-focus.md | 8 +++- docs/rules/prefer-in-document.md | 8 +++- docs/rules/prefer-required.md | 8 +++- docs/rules/prefer-to-have-attribute.md | 8 +++- docs/rules/prefer-to-have-class.md | 8 +++- docs/rules/prefer-to-have-style.md | 8 +++- docs/rules/prefer-to-have-text-content.md | 8 +++- docs/rules/prefer-to-have-value.md | 8 +++- package.json | 6 ++- 15 files changed, 106 insertions(+), 90 deletions(-) delete mode 100644 build/generate-readme-table.js diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index dc05a2c..9991d22 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -47,6 +47,10 @@ jobs: if: ${{ matrix.eslint == 8 }} run: npm run validate + - name: ▢️ Ensure docs are up-to-date + if: ${{ matrix.eslint == 8 && matrix.node == 16 }} + run: npm run lint:generate-readme-table + - name: ⬆️ Upload coverage report uses: codecov/codecov-action@v3 diff --git a/README.md b/README.md index 72e16f2..f66f450 100644 --- a/README.md +++ b/README.md @@ -92,27 +92,27 @@ module.exports = { ## Supported Rules -πŸ‘ indicates that a rule is recommended for all users. - -πŸ”§ indicates that a rule is fixable. - - - -| Name | πŸ‘ | πŸ”§ | Description | -| ---------------------------------------------------------------------------------------------------------------------------------------------- | --- | --- | --------------------------------------------------------------------- | -| [prefer-checked](https://github.com/testing-library/eslint-plugin-jest-dom/blob/main/docs/rules/prefer-checked.md) | πŸ‘ | πŸ”§ | prefer toBeChecked over checking attributes | -| [prefer-empty](https://github.com/testing-library/eslint-plugin-jest-dom/blob/main/docs/rules/prefer-empty.md) | πŸ‘ | πŸ”§ | Prefer toBeEmpty over checking innerHTML | -| [prefer-enabled-disabled](https://github.com/testing-library/eslint-plugin-jest-dom/blob/main/docs/rules/prefer-enabled-disabled.md) | πŸ‘ | πŸ”§ | prefer toBeDisabled or toBeEnabled over checking attributes | -| [prefer-focus](https://github.com/testing-library/eslint-plugin-jest-dom/blob/main/docs/rules/prefer-focus.md) | πŸ‘ | πŸ”§ | prefer toHaveFocus over checking document.activeElement | -| [prefer-in-document](https://github.com/testing-library/eslint-plugin-jest-dom/blob/main/docs/rules/prefer-in-document.md) | πŸ‘ | πŸ”§ | Prefer .toBeInTheDocument() for asserting the existence of a DOM node | -| [prefer-required](https://github.com/testing-library/eslint-plugin-jest-dom/blob/main/docs/rules/prefer-required.md) | πŸ‘ | πŸ”§ | prefer toBeRequired over checking properties | -| [prefer-to-have-attribute](https://github.com/testing-library/eslint-plugin-jest-dom/blob/main/docs/rules/prefer-to-have-attribute.md) | πŸ‘ | πŸ”§ | prefer toHaveAttribute over checking getAttribute/hasAttribute | -| [prefer-to-have-class](https://github.com/testing-library/eslint-plugin-jest-dom/blob/main/docs/rules/prefer-to-have-class.md) | πŸ‘ | πŸ”§ | prefer toHaveClass over checking element className | -| [prefer-to-have-style](https://github.com/testing-library/eslint-plugin-jest-dom/blob/main/docs/rules/prefer-to-have-style.md) | πŸ‘ | πŸ”§ | prefer toHaveStyle over checking element style | -| [prefer-to-have-text-content](https://github.com/testing-library/eslint-plugin-jest-dom/blob/main/docs/rules/prefer-to-have-text-content.md) | πŸ‘ | πŸ”§ | Prefer toHaveTextContent over checking element.textContent | -| [prefer-to-have-value](https://github.com/testing-library/eslint-plugin-jest-dom/blob/main/docs/rules/prefer-to-have-value.md) | πŸ‘ | πŸ”§ | prefer toHaveValue over checking element.value | - - + + +πŸ’Ό Configurations enabled in.\ +βœ… Set in the `recommended` configuration.\ +πŸ”§ Automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/user-guide/command-line-interface#--fix). + +| NameΒ Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β Β  | Description | πŸ’Ό | πŸ”§ | +| :----------------------------------------------------------------------- | :-------------------------------------------------------------------- | :- | :- | +| [prefer-checked](docs/rules/prefer-checked.md) | prefer toBeChecked over checking attributes | βœ… | πŸ”§ | +| [prefer-empty](docs/rules/prefer-empty.md) | Prefer toBeEmpty over checking innerHTML | βœ… | πŸ”§ | +| [prefer-enabled-disabled](docs/rules/prefer-enabled-disabled.md) | prefer toBeDisabled or toBeEnabled over checking attributes | βœ… | πŸ”§ | +| [prefer-focus](docs/rules/prefer-focus.md) | prefer toHaveFocus over checking document.activeElement | βœ… | πŸ”§ | +| [prefer-in-document](docs/rules/prefer-in-document.md) | Prefer .toBeInTheDocument() for asserting the existence of a DOM node | βœ… | πŸ”§ | +| [prefer-required](docs/rules/prefer-required.md) | prefer toBeRequired over checking properties | βœ… | πŸ”§ | +| [prefer-to-have-attribute](docs/rules/prefer-to-have-attribute.md) | prefer toHaveAttribute over checking getAttribute/hasAttribute | βœ… | πŸ”§ | +| [prefer-to-have-class](docs/rules/prefer-to-have-class.md) | prefer toHaveClass over checking element className | βœ… | πŸ”§ | +| [prefer-to-have-style](docs/rules/prefer-to-have-style.md) | prefer toHaveStyle over checking element style | βœ… | πŸ”§ | +| [prefer-to-have-text-content](docs/rules/prefer-to-have-text-content.md) | Prefer toHaveTextContent over checking element.textContent | βœ… | πŸ”§ | +| [prefer-to-have-value](docs/rules/prefer-to-have-value.md) | prefer toHaveValue over checking element.value | βœ… | πŸ”§ | + + ## Issues @@ -196,7 +196,6 @@ MIT [coc]: https://github.com/testing-library/eslint-plugin-jest-dom/blob/main/other/CODE_OF_CONDUCT.md [emojis]: https://github.com/all-contributors/all-contributors#emoji-key [all-contributors]: https://github.com/all-contributors/all-contributors -[all-contributors-badge]: https://img.shields.io/github/all-contributors/testing-library/eslint-plugin-jest-dom?color=orange&style=flat-square [bugs]: https://github.com/testing-library/eslint-plugin-jest-dom/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+sort%3Acreated-desc+label%3Abug [requests]: https://github.com/testing-library/eslint-plugin-jest-dom/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3Aenhancement [good-first-issue]: https://github.com/testing-library/eslint-plugin-jest-dom/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc+label%3Aenhancement+label%3A%22good+first+issue%22 diff --git a/build/generate-readme-table.js b/build/generate-readme-table.js deleted file mode 100644 index 38e741d..0000000 --- a/build/generate-readme-table.js +++ /dev/null @@ -1,55 +0,0 @@ -const fs = require("fs"); -const path = require("path"); -const rules = require("..").rules; - -const README_LOCATION = path.resolve(__dirname, "..", "README.md"); -const BEGIN_TABLE_MARKER = "\n"; -const END_TABLE_MARKER = "\n"; - -const expectedTableLines = Object.keys(rules) - .sort() - .reduce( - (lines, ruleId) => { - const rule = rules[ruleId]; - - lines.push( - [ - `[${ruleId}](https://github.com/testing-library/eslint-plugin-jest-dom/blob/main/docs/rules/${ruleId}.md)`, - rule.meta.docs.recommended ? "πŸ‘" : "", - rule.meta.fixable ? "πŸ”§" : "", - rule.meta.docs.description, - ].join(" | ") - ); - - return lines; - }, - ["Name | πŸ‘ | πŸ”§ | Description", "----- | ----- | ----- | -----"] - ) - .join("\n"); - -const readmeContents = fs.readFileSync(README_LOCATION, "utf8"); - -if (!readmeContents.includes(BEGIN_TABLE_MARKER)) { - throw new Error( - `Could not find '${BEGIN_TABLE_MARKER}' marker in README.md.` - ); -} - -if (!readmeContents.includes(END_TABLE_MARKER)) { - throw new Error(`Could not find '${END_TABLE_MARKER}' marker in README.md.`); -} - -const linesStartIndex = - readmeContents.indexOf(BEGIN_TABLE_MARKER) + BEGIN_TABLE_MARKER.length; -const linesEndIndex = readmeContents.indexOf(END_TABLE_MARKER); - -const updatedReadmeContents = - readmeContents.slice(0, linesStartIndex) + - expectedTableLines + - readmeContents.slice(linesEndIndex); - -if (module.parent) { - module.exports = updatedReadmeContents; -} else { - fs.writeFileSync(README_LOCATION, updatedReadmeContents); -} diff --git a/docs/rules/prefer-checked.md b/docs/rules/prefer-checked.md index c2a4fc0..295e82a 100644 --- a/docs/rules/prefer-checked.md +++ b/docs/rules/prefer-checked.md @@ -1,4 +1,10 @@ -# prefer toBeChecked() or not.toBeChecked() over toHaveProperty('checked', true|false) (prefer-enabled-checked) +# Prefer toBeChecked over checking attributes (`jest-dom/prefer-checked`) + +πŸ’Ό This rule is enabled in the βœ… `recommended` config. + +πŸ”§ This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + ## Rule Details diff --git a/docs/rules/prefer-empty.md b/docs/rules/prefer-empty.md index 8be8f15..a9e3614 100644 --- a/docs/rules/prefer-empty.md +++ b/docs/rules/prefer-empty.md @@ -1,4 +1,10 @@ -# Prefer toBeEmptyDOMElement over checking innerHTML / firstChild (prefer-empty) +# Prefer toBeEmpty over checking innerHTML (`jest-dom/prefer-empty`) + +πŸ’Ό This rule is enabled in the βœ… `recommended` config. + +πŸ”§ This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + This rule ensures people will use toBeEmptyDOMElement() rather than checking dom nodes/properties. It is primarily aimed at consistently using jest-dom for diff --git a/docs/rules/prefer-enabled-disabled.md b/docs/rules/prefer-enabled-disabled.md index 7a34e38..34ea28d 100644 --- a/docs/rules/prefer-enabled-disabled.md +++ b/docs/rules/prefer-enabled-disabled.md @@ -1,4 +1,10 @@ -# prefer toBeDisabled() or toBeEnabled() over toHaveProperty('disabled', true|false) (prefer-enabled-disabled) +# Prefer toBeDisabled or toBeEnabled over checking attributes (`jest-dom/prefer-enabled-disabled`) + +πŸ’Ό This rule is enabled in the βœ… `recommended` config. + +πŸ”§ This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + ## Rule Details diff --git a/docs/rules/prefer-focus.md b/docs/rules/prefer-focus.md index a7e8dda..7d9e938 100644 --- a/docs/rules/prefer-focus.md +++ b/docs/rules/prefer-focus.md @@ -1,4 +1,10 @@ -# prefer-focus +# Prefer toHaveFocus over checking document.activeElement (`jest-dom/prefer-focus`) + +πŸ’Ό This rule is enabled in the βœ… `recommended` config. + +πŸ”§ This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + prefer toHaveFocus over checking document.activeElement (prefer-focus) diff --git a/docs/rules/prefer-in-document.md b/docs/rules/prefer-in-document.md index e9a6347..a66848d 100644 --- a/docs/rules/prefer-in-document.md +++ b/docs/rules/prefer-in-document.md @@ -1,4 +1,10 @@ -# Prefer .toBeInTheDocument in favor of .toHaveLength(1) (prefer-in-document) +# Prefer .toBeInTheDocument() for asserting the existence of a DOM node (`jest-dom/prefer-in-document`) + +πŸ’Ό This rule is enabled in the βœ… `recommended` config. + +πŸ”§ This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + ## Rule Details diff --git a/docs/rules/prefer-required.md b/docs/rules/prefer-required.md index 0d20e9f..54c6617 100644 --- a/docs/rules/prefer-required.md +++ b/docs/rules/prefer-required.md @@ -1,4 +1,10 @@ -# prefer toBeRequired() or not.toBeRequired() over toHaveProperty('required', true|false) (prefer-required) +# Prefer toBeRequired over checking properties (`jest-dom/prefer-required`) + +πŸ’Ό This rule is enabled in the βœ… `recommended` config. + +πŸ”§ This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + ## Rule Details diff --git a/docs/rules/prefer-to-have-attribute.md b/docs/rules/prefer-to-have-attribute.md index ed887a3..c290ceb 100644 --- a/docs/rules/prefer-to-have-attribute.md +++ b/docs/rules/prefer-to-have-attribute.md @@ -1,4 +1,10 @@ -# prefer toHaveAttribute over checking getAttribute/hasAttribute (prefer-to-have-attribute) +# Prefer toHaveAttribute over checking getAttribute/hasAttribute (`jest-dom/prefer-to-have-attribute`) + +πŸ’Ό This rule is enabled in the βœ… `recommended` config. + +πŸ”§ This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + This rule is an autofixable rule that reports usages of `getAttribute` or `hasAttribute` in expect statements in preference of using the jest-dom diff --git a/docs/rules/prefer-to-have-class.md b/docs/rules/prefer-to-have-class.md index 5978794..f4f2937 100644 --- a/docs/rules/prefer-to-have-class.md +++ b/docs/rules/prefer-to-have-class.md @@ -1,4 +1,10 @@ -# prefer toHaveClass over checking element.class (prefer-to-have-class) +# Prefer toHaveClass over checking element className (`jest-dom/prefer-to-have-class`) + +πŸ’Ό This rule is enabled in the βœ… `recommended` config. + +πŸ”§ This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + This rule is an autofixable rule that reports usages of checking element className or classList in expect statements in preference of using the jest-dom `toHaveClass` matcher. diff --git a/docs/rules/prefer-to-have-style.md b/docs/rules/prefer-to-have-style.md index 118030e..bf61d9e 100644 --- a/docs/rules/prefer-to-have-style.md +++ b/docs/rules/prefer-to-have-style.md @@ -1,4 +1,10 @@ -# prefer toHaveStyle over checking element.style (prefer-to-have-style) +# Prefer toHaveStyle over checking element style (`jest-dom/prefer-to-have-style`) + +πŸ’Ό This rule is enabled in the βœ… `recommended` config. + +πŸ”§ This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + This rule is an autofixable rule that reports usages of checking element.style in expect statements in preference of using the jest-dom `toHaveStyle` matcher. diff --git a/docs/rules/prefer-to-have-text-content.md b/docs/rules/prefer-to-have-text-content.md index f10c6b2..a960908 100644 --- a/docs/rules/prefer-to-have-text-content.md +++ b/docs/rules/prefer-to-have-text-content.md @@ -1,4 +1,10 @@ -# Prefer toHaveTextContent over checking element.textContent (prefer-to-have-text-content) +# Prefer toHaveTextContent over checking element.textContent (`jest-dom/prefer-to-have-text-content`) + +πŸ’Ό This rule is enabled in the βœ… `recommended` config. + +πŸ”§ This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + Please describe the origin of the rule here. diff --git a/docs/rules/prefer-to-have-value.md b/docs/rules/prefer-to-have-value.md index 35a6074..544b2f5 100644 --- a/docs/rules/prefer-to-have-value.md +++ b/docs/rules/prefer-to-have-value.md @@ -1,4 +1,10 @@ -# prefer toHaveAttribute over checking getAttribute/hasAttribute (prefer-to-have-attribute) +# Prefer toHaveValue over checking element.value (`jest-dom/prefer-to-have-value`) + +πŸ’Ό This rule is enabled in the βœ… `recommended` config. + +πŸ”§ This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix). + + This rule is an autofixable rule that encourages the use of toHaveValue over checking the value attribute. diff --git a/package.json b/package.json index 9f87765..1fd6f3b 100644 --- a/package.json +++ b/package.json @@ -30,9 +30,10 @@ ], "scripts": { "build": "kcd-scripts build", - "pregenerate-readme-table": "yarn build", - "generate-readme-table": "node build/generate-readme-table.js", + "pregenerate-readme-table": "npm run build", + "generate-readme-table": "eslint-doc-generator --ignore-config all", "lint": "kcd-scripts lint", + "lint:generate-readme-table": "npm run generate-readme-table -- --check", "setup": "npm install && npm run validate -s", "test": "kcd-scripts test", "test:coverage": "npm test -- --coverage", @@ -47,6 +48,7 @@ "devDependencies": { "@typescript-eslint/parser": "^5.9.1", "eslint": "^8.7.0", + "eslint-doc-generator": "^0.19.0", "eslint-remote-tester": "^3.0.0", "eslint-remote-tester-repositories": "^0.0.7", "kcd-scripts": "^12.0.0",