Add docs about tests (#2243)

Co-authored-by: Sindre Sorhus <[email protected]>

Author: fisker

.github/contributing.md

@@ -11,3 +11,7 @@ First open an issue with your proposal. When the rule is accepted, see the [docs
 ## I want to implement a rule from an open issue
 
 See the [docs on creating and submitting a new rule](../docs/new-rule.md).
+
+## How to write tests
+
+See the [docs on writing tests](../docs/write-tests.md).

docs/new-rule.md

@@ -12,14 +12,14 @@ Use the [`astexplorer` site](https://astexplorer.net) with the `espree` parser a
 
 ## Steps
 
-- Run `$ npm run create-rule` to create files for the new rule.
-- Open “test/{RULE_ID}.mjs” and write some tests before implementing the rule.
+- Run `npm run create-rule` to create files for the new rule.
+- Open “test/{RULE_ID}.mjs” and [write some tests](./write-tests.md) before implementing the rule.
 - Open “rules/{RULE_ID}.js” and implement the rule logic.
 - Add the correct [`meta.type`](https://eslint.org/docs/developer-guide/working-with-rules#rule-basics) to the rule.
 - Open “docs/rules/{RULE_ID}.js” and write some documentation.
 - Double check `configs/recommended.js` and `readme.md`, make sure the new rule is correctly added.
-- Run `$ npm test` to ensure the tests pass.
-- Run `$ npm run integration` to run the rules against real projects to ensure your rule does not fail on real-world code.
+- Run `npm test` to ensure the tests pass.
+- Run `npm run integration` to run the rules against real projects to ensure your rule does not fail on real-world code.
 - Open a pull request with a title in exactly the format `` Add `rule-name` rule ``, for example, `` Add `no-unused-properties` rule ``.
 - The pull request description should include the issue it fixes, for example, `Fixes #123`.
-- Run `$ npm run run-rules-on-codebase` to run the rules against codebase to ensure code in the repository are following your rule, _you can ignore this step until your PR is reviewed_.
+- Run `npm run run-rules-on-codebase` to run the rules against codebase to ensure code in the repository are following your rule, _you can ignore this step until your PR is reviewed_.

docs/write-tests.md

@@ -0,0 +1,178 @@
+# Writing tests
+
+Tests are in the `/test` directory.
+
+A rule test file should look like this:
+
+```js
+import {getTester} from './utils/test.mjs';
+
+const {test} = getTester(import.meta);
+
+test.snapshot({
+	valid: [
+		// Valid test cases goes here
+	],
+	invalid: [
+		// Valid test cases goes here
+	]，
+});
+```
+
+## `test.snapshot()`
+
+This runs [`SnapshotRuleTester`](../test/utils/snapshot-rule-tester.mjs), which auto-generates the snapshot for test results, including error messages, error locations, autofix result, and suggestions. All you have to do is check the snapshot and make sure the results are expected before committing.
+
+It's recommended to use this approach as it simplifies test writing.
+
+```js
+import {getTester} from './utils/test.mjs';
+
+const {test} = getTester(import.meta);
+
+test.snapshot({
+	valid: [
+		'valid.code',
+	],
+	invalid: [
+		'invalid.code',
+	]，
+});
+```
+
+## Focus on one rule
+
+We use [`AVA`](https://github.com/avajs/ava) to run tests. To focus on a specific rule test, you can:
+
+```console
+npx ava test/rule-name.mjs
+```
+
+To update snapshots, run the command above with [`--update-snapshots` or `-u`](https://github.com/avajs/ava/blob/main/docs/05-command-line.md#cli).
+
+```console
+npx ava test/rule-name.mjs -u
+```
+
+## Focus on one test case
+
+To focus on a single test case, you can:
+
+```js
+test.snapshot({
+	valid: [],
+	invalid: [
+		// Tagged template with `test.only`
+		test.only`code`,
+
+		// Wrap code with `test.only`
+		test.only('code'),
+
+		// Wrap test case with `test.only`
+		test.only({
+			code: 'code',
+			options: [{checkFoo: true}],
+		}),
+
+		// Use `only: true`
+		{
+			code: 'code',
+			options: [{checkFoo: true}],
+			only: true,
+		},
+	],
+})
+```
+
+**Please remove `test.only` and `only: true` before committing.**
+
+## `test()`
+
+This runs [`eslint-ava-rule-tester`](https://github.com/jfmengels/eslint-ava-rule-tester):
+
+```js
+import {getTester} from './utils/test.mjs';
+
+const {test} = getTester(import.meta);
+
+test({
+	valid: [
+		'valid.code',
+	],
+	invalid: [
+		{
+			code: 'invalid.code',
+			errors: [{ message: 'invalid.code is not allowed', column: 1, line: 1 }],
+			output: 'fixed.code',
+		}
+	]，
+});
+```
+
+## `test.babel()`
+
+Same as `test()`, but uses [`@babel/eslint-parser`](https://www.npmjs.com/package/@babel/eslint-parser) as parser.
+
+## `test.typescript()`
+
+Same as `test()`, but uses [`@typescript-eslint/parser`](https://www.npmjs.com/package/@typescript-eslint/parser) as parser.
+
+## `test.vue()`
+
+Same as `test()`, but uses [`vue-eslint-parser`](https://www.npmjs.com/package/vue-eslint-parser) as parser.
+
+## `testerOptions`
+
+`test` and `test.*()` accepts `testerOptions`, which lets you specify common `parseOptions` to all test cases.
+
+```js
+test.snapshot({
+	testerOptions: {
+		parserOptions: {
+			ecmaFeatures: {
+				jsx: true,
+			},
+		},
+	},
+	valid: [],
+	invalid: [],
+})
+```
+
+## `parsers`
+
+[`utils/test.mjs`](../test/utils/test.mjs) also exposes a `parsers` object, which can be used in `testerOptions` or `parser` for a single test case.
+
+```js
+import {getTester, parsers} from './utils/test.mjs';
+
+const {test} = getTester(import.meta);
+
+test.snapshot({
+	testerOptions: {
+		parser: parsers.babel,
+	},
+	valid: [],
+	invalid: [],
+})
+```
+
+```js
+import {getTester, parsers} from './utils/test.mjs';
+
+const {test} = getTester(import.meta);
+
+test.snapshot({
+	valid: [],
+	invalid: [
+		{
+			code: 'invalid.code.parse.by.babel',
+			parser: parsers.babel,
+		},
+	],
+})
+```
+
+Why use `parser: parsers.babel` instead of `parser: '@babel/eslint-parser'`?
+
+Using `parsers.babel` will make the `parserOptions` merge with useful default options. See [`parser.mjs`](../test/utils/parsers.mjs) for details.