Docs: describe all RuleTester options (fixes #4810)

docs/developer-guide/working-with-rules.md

@@ -434,6 +434,26 @@ invalid: [
 
 In this case, the message is specific to the variable being used and the AST node type is `Identifier`.
 
+You can also check that the rule returns the correct line and column numbers for the message by adding `line` and `column` properties as needed (both are optional, but highly recommend):
+
+```js
+invalid: [
+    {
+        code: "function doSomething() { var f; if (true) { var build = true; } f = build; }",
+        errors: [
+            {
+                message: "build used outside of binding context.",
+                type: "Identifier",
+                line: 1,
+                column: 68
+            }
+        ]
+    }
+]
+```
+
+The test fails if the line or column reported by the rule doesn't match the options specified in the test.
+
 Similar to the valid cases, you can also specify `options` to be passed to the rule:
 
 ```js
@@ -460,11 +480,90 @@ invalid: [
 ]
 ```
 
-### Specifying Parser Options
+### Specifying Globals
 
-Some tests require that a certain parser configuration must be used. This can be specified in test specifications via the `parserOptions` setting.
+If your rule relies on globals to be specified, you can provide global variable declarations by using the `globals` property. For example:
+
+```js
+valid: [
+    {
+        code: "for (x of a) doSomething();",
+        globals: { window: true }
+    }
+]
+```
 
-For example, to set `ecmaVersion` to 6 (in order to use constructs like `for ... of`):
+The same works on invalid tests:
+
+```js
+invalid: [
+    {
+        code: "'single quotes'",
+        globals: { window: true },
+        errors: ["Strings must use doublequote."]
+    }
+]
+```
+
+### Specifying Settings
+
+If your rule relies on `context.settings` to be specified, you can provide those settings by using the `settings` property. For example:
+
+```js
+valid: [
+    {
+        code: "for (x of a) doSomething();",
+        settings: { message: "hi" }
+    }
+]
+```
+
+The same works on invalid tests:
+
+```js
+invalid: [
+    {
+        code: "'single quotes'",
+        settings: { message: "hi" },
+        errors: ["Strings must use doublequote."]
+    }
+]
+```
+
+You can then access `context.settings.message` inside of the rule.
+
+### Specifying Filename
+
+If your rule relies on `context.getFilename()` to be specified, you can provide the filename by using the `filename` property. For example:
+
+```js
+valid: [
+    {
+        code: "for (x of a) doSomething();",
+        filename: "foo/bar.js"
+    }
+]
+```
+
+The same works on invalid tests:
+
+```js
+invalid: [
+    {
+        code: "'single quotes'",
+        filename: "foo/bar.js",
+        errors: ["Strings must use doublequote."]
+    }
+]
+```
+
+You can then access `context.getFilename()` inside of the rule.
+
+### Specifying Parser and Parser Options
+
+Some tests require that a certain parser configuration must be used. This can be specified in test specifications via the `parser` and `parserOptions` properties. While the following examples show usage in `valid` tests, you can use the same options in `invalid` tests as well.
+
+For example, to set `ecmaVersion` to 6 (in order to use constructs like `for-of`):
 
 ```js
 valid: [
@@ -497,11 +596,18 @@ valid: [
 ]
 ```
 
-The options available and the expected syntax for `parserOptions` is the same as those used in [configuration](../user-guide/configuring#specifying-parser-options).
+To use a different parser:
 
-### Write Several Tests
+```js
+valid: [
+    {
+        code: "var foo = <div>{bar}</div>",
+        parser: "my-custom-parser"
+    }
+]
+```
 
-Provide as many unit tests as possible. Your pull request will never be turned down for having too many tests submitted with it!
+The options available and the expected syntax for `parserOptions` is the same as those used in [configuration](../user-guide/configuring#specifying-parser-options).
 
 ## Performance Testing