docs(README): categorize rules

alecxe · Dec 15, 2016 · 42c0e87 · 42c0e87
1 parent 3927313
commit 42c0e87
Show file tree

Hide file tree

Showing 11 changed files with 55 additions and 14 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -6,7 +6,7 @@
 * Format Git commit messages according to [AngularJS conventions][cc]
 * The repository is [commitizen-friendly][], please use `git cz` to make it easy format the commit messages properly
 * When creating a new rule, please add it to [index.js][], document it (see
-  [docs][]) and update the [configuration table][]
+  [docs][]) and update the [Rules][] section in the `README`
 
 If in doubt, file an issue first.
 
@@ -16,4 +16,4 @@ Thanks!
 [commitizen-friendly]: https://github.com/commitizen/cz-cli
 [docs]: docs/rules
 [index.js]: index.js
-[configuration table]: README.md#configuration
+[rules]: README.md#rules
diff --git a/README.md b/README.md
@@ -35,9 +35,50 @@ The plugin would be of the most help if configured to run in your IDE of choice
       - protractor
     ```
 
-## Configuration
-
-This plugin ships with a default configuration for each rule:
+## Rules
+
+There are various types of rules implemented in the plugin. Here is a rough categorization.
+
+#### Correct Protractor API usage and Common Errors
+
+* [missing-perform][]: Enforce valid `browser.actions()` usage
+* [correct-chaining][]: Prohibit incorrect chaining of `element` and `element.all`
+* [no-array-finder-methods][]: Disallow using `ElementArrayFinder` methods on `ElementFinder`
+* [array-callback-return][]: Enforce `return` statements in callbacks of `ElementArrayFinder` methods
+* [no-get-inner-outer-html][]: Warn about using deprecated `getInnerHtml()` and `getOuterHtml()` methods
+* [no-promise-in-if][]: Warn if promise is checked for truthiness inside an `if` condition
+
+#### Locating Elements
+
+* [no-invalid-selectors][]: Prohibit creating invalid CSS selectors
+* [valid-locator-type][]: Ensure correct locator argument type for `element()`, `element.all()`, `$()` and `$$()`
+* [no-compound-classes][]: Do not allow compound class names in the `by.className()` locator
+* [no-angular-classes][]: Discourage using Angular CSS classes inside CSS selectors
+* [use-angular-locators][]: Recommend using built-in Angular-specific locators
+* [no-angular-attributes][]: Discourage using Angular attributes inside CSS selectors
+* [no-bootstrap-classes][]: Discourage using Bootstrap layout-oriented CSS classes inside CSS selectors
+* [use-simple-repeaters][]: Discourage using extended `ng-repeat` syntax in `by.repeater()` locators
+* [no-repetitive-locators][]: Discourage repeating locators
+* [no-repetitive-selectors][]: Discourage repeating parts of CSS selectors
+
+#### Style Guide Recommendations and Best Practices
+
+* [missing-wait-message][]: Missing wait timeout message in `browser.wait()`
+* [no-by-xpath][]: Discourage the use of `by.xpath()` locator
+* [no-get-in-it][]: Recommend against having `browser.get()` or `browser.driver.get()` inside `it()`
+* [no-execute-script][]: Recommend against executing scripts in specs and page objects
+* [no-expect-in-po][]: Recommend against making assertions inside Page Objects
+* [no-absolute-url][]: Recommend against navigating to absolute URLs inside `browser.get()` or `browser.driver.get()`
+* [use-first-last][]: Recommend using `first()` instead of `get(0)` and `last()` instead of `get(-1)`
+* [no-shadowing][]: Don't allow to shadow the built-in Protractor globals
+* [use-count-method][]: Recommend using `count()` instead of `then()` and `length`
+* [use-promise-all][]: Recommend using `protractor.promise.all()` to resolve multiple promises 
+* [by-css-shortcut][]: Recommend using `$` and `$$` shortcuts
+* [no-describe-selectors][]: Discourage nested selectors within describe blocks
+* [no-browser-pause][]: Discourage the use of `browser.pause()`
+* [no-browser-sleep][]: Discourage the use of `browser.sleep()`
+
+Here is a table with all the available rules sorted by the default error level:
 
 Rule                         | Default Error Level | Auto-fixable | Options
 ----                         | -------             | -----        | -----

diff --git a/docs/rules/missing-perform.md b/docs/rules/missing-perform.md
@@ -1,4 +1,4 @@
-# Enforce valid `browser.actions()` usage (missing-perform)
+# Enforce valid `browser.actions()` usage
 
 Ensure `perform()` is called on `browser.actions()` chain of actions.
 

diff --git a/docs/rules/missing-wait-message.md b/docs/rules/missing-wait-message.md
@@ -1,4 +1,4 @@
-# Missing wait timeout message in `browser.wait()` (missing-wait-message)
+# Missing wait timeout message in `browser.wait()`
 
 Ensure the timeout message is set when `browser.wait()` is called.
 

diff --git a/docs/rules/no-browser-pause.md b/docs/rules/no-browser-pause.md
@@ -1,4 +1,4 @@
-# Discourage the use of `browser.pause()` (no-browser-pause)
+# Discourage the use of `browser.pause()`
 
 Ensure `browser.pause()` is not used.
 

diff --git a/docs/rules/no-browser-sleep.md b/docs/rules/no-browser-sleep.md
@@ -1,4 +1,4 @@
-# Discourage the use of `browser.sleep()` (no-browser-sleep)
+# Discourage the use of `browser.sleep()`
 
 Ensure `browser.sleep()` is not used.
 

diff --git a/docs/rules/no-by-xpath.md b/docs/rules/no-by-xpath.md
@@ -1,4 +1,4 @@
-# Discourage the use of `by.xpath` locator (no-by-xpath)
+# Discourage the use of `by.xpath()` locator
 
 Ensure `by.xpath` locator is not used.
 

diff --git a/docs/rules/no-compound-classes.md b/docs/rules/no-compound-classes.md
@@ -1,4 +1,4 @@
-# Do not allow compound class names in the by.className locator
+# Do not allow compound class names in the `by.className()` locator
 
 Ensure that there are no compound class names (multiple space-delimited classes) used as a value for the `by.className` locator.
 

diff --git a/docs/rules/no-describe-selectors.md b/docs/rules/no-describe-selectors.md
@@ -1,4 +1,4 @@
-# Discourage nested selectors within describe blocks (no-describe-selectors)
+# Discourage nested selectors within describe blocks
 
 Ensure raw selectors are not used within `describe` blocks.
 

diff --git a/docs/rules/no-get-inner-outer-html.md b/docs/rules/no-get-inner-outer-html.md
@@ -1,4 +1,4 @@
-# Warn about using `getInnerHtml()` and `getOuterHtml()` methods
+# Warn about using deprecated `getInnerHtml()` and `getOuterHtml()` methods
 
 Selenium [has deprecated `getInnerHtml()` and `getOuterHtml()` methods in version 2.53](https://github.com/SeleniumHQ/selenium/blob/96ed95a97405fa267eea09c4008cda9e7703e84d/javascript/node/selenium-webdriver/CHANGES.md#change-summary).
 And, hence, Protractor itself _does not have these methods documented_ as a part of [public API](http://www.protractortest.org/#/api) anymore.

diff --git a/docs/rules/use-simple-repeaters.md b/docs/rules/use-simple-repeaters.md
@@ -1,4 +1,4 @@
-# Discourage using extended ng-repeat syntax in by.repeater() locators
+# Discourage using extended `ng-repeat` syntax in `by.repeater()` locators
 
 Warn about using [filters, ordering or tracking](https://docs.angularjs.org/api/ng/directive/ngRepeat) inside `by.repeater()` locators.
 Typically filters, ordering or tracking don't contribute to the usefulness and reliability of a locator.