feat!: FlatRuleTester -> RuleTester (#17922)

* feat!: FlatRuleTester -> RuleTester

refs #13481

* Update docs/src/use/migrate-to-9.0.0.md

Co-authored-by: Milos Djermanovic <[email protected]>

* Update docs/src/use/migrate-to-9.0.0.md

Co-authored-by: Milos Djermanovic <[email protected]>

* Update docs/src/use/migrate-to-9.0.0.md

Co-authored-by: Milos Djermanovic <[email protected]>

---------

Co-authored-by: Milos Djermanovic <[email protected]>

Author: nzakas

docs/src/integrate/nodejs-api.md

@@ -789,9 +789,13 @@ ruleTester.run("my-rule", rule, {
 The `RuleTester` constructor accepts an optional object argument, which can be used to specify defaults for your test cases. For example, if all of your test cases use ES2015, you can set it as a default:
 
 ```js
-const ruleTester = new RuleTester({ parserOptions: { ecmaVersion: 2015 } });
+const ruleTester = new RuleTester({ languageOptions: { ecmaVersion: 2015 } });
 ```
 
+::: tip
+If you don't specify any options to the `RuleTester` constructor, then it uses the ESLint defaults (`languageOptions: { ecmaVersion: "latest", sourceType: "module" }`).
+:::
+
 The `RuleTester#run()` method is used to run the tests. It should be passed the following arguments:
 
 * The name of the rule (string)
@@ -822,12 +826,12 @@ In addition to the properties above, invalid test cases can also have the follow
     If a string is provided as an error instead of an object, the string is used to assert the `message` of the error.
 * `output` (string, required if the rule fixes code): Asserts the output that will be produced when using this rule for a single pass of autofixing (e.g. with the `--fix` command line flag). If this is `null`, asserts that none of the reported problems suggest autofixes.
 
-Any additional properties of a test case will be passed directly to the linter as config options. For example, a test case can have a `parserOptions` property to configure parser behavior:
+Any additional properties of a test case will be passed directly to the linter as config options. For example, a test case can have a `languageOptions` property to configure parser behavior:
 
 ```js
 {
     code: "let foo;",
-    parserOptions: { ecmaVersion: 2015 }
+    languageOptions: { ecmaVersion: 2015 }
 }
 ```
 
@@ -907,7 +911,7 @@ ruleTester.run("my-rule-for-no-foo", rule, {
 
     If `RuleTester.itOnly` has been set to a function value, `RuleTester` will call `RuleTester.itOnly` instead of `RuleTester.it` to run cases with `only: true`. If `RuleTester.itOnly` is not set but `RuleTester.it` has an `only` function property, `RuleTester` will fall back to `RuleTester.it.only`.
 
-2. Otherwise, if `describe` and `it` are present as globals, `RuleTester` will use `global.describe` and `global.it` to run tests and `global.it.only` to run cases with `only: true`. This allows `RuleTester` to work when using frameworks like [Mocha](https://mochajs.org/) without any additional configuration.
+2. Otherwise, if `describe` and `it` are present as globals, `RuleTester` will use `globalThis.describe` and `globalThis.it` to run tests and `globalThis.it.only` to run cases with `only: true`. This allows `RuleTester` to work when using frameworks like [Mocha](https://mochajs.org/) without any additional configuration.
 3. Otherwise, `RuleTester#run` will simply execute all of the tests in sequence, and will throw an error if one of them fails. This means you can simply execute a test file that calls `RuleTester.run` using `Node.js`, without needing a testing framework.
 
 `RuleTester#run` calls the `describe` function with two arguments: a string describing the rule, and a callback function. The callback calls the `it` function with a string describing the test case, and a test function. The test function will return successfully if the test passes, and throw an error if the test fails. The signature for `only` is the same as `it`. `RuleTester` calls either `it` or `only` for every case even when some cases have `only: true`, and the test framework is responsible for implementing test case exclusivity. (Note that this is the standard behavior for test suites when using frameworks like [Mocha](https://mochajs.org/); this information is only relevant if you plan to customize `RuleTester.describe`, `RuleTester.it`, or `RuleTester.itOnly`.)

docs/src/use/migrate-to-9.0.0.md

@@ -28,6 +28,7 @@ The lists below are ordered roughly by the number of users each change is expect
 * [Removed `sourceCode.getComments()`](#removed-sourcecode-getcomments)
 * [Function-style rules are no longer supported](#drop-function-style-rules)
 * [`meta.schema` is required for rules with options](#meta-schema-required)
+* [`FlatRuleTester` is now `RuleTester`](#flat-rule-tester)
 
 ### Breaking changes for integration developers
 
@@ -158,6 +159,56 @@ The [eslint-plugin/require-meta-schema](https://github.com/eslint-community/esli
 
 **Related Issues(s):** [#14709](https://github.com/eslint/eslint/issues/14709)
 
+## <a name="flat-rule-tester"></a> `FlatRuleTester` is now `RuleTester`
+
+As announced in our [blog post](/blog/2023/10/flat-config-rollout-plans/), the temporary `FlatRuleTester` class has been renamed to `RuleTester`, while the `RuleTester` class from v8.x has been removed. Additionally, the `FlatRuleTester` export from `eslint/use-at-your-own-risk` has been removed.
+
+**To address:** Update your rule tests to use the new `RuleTester`. To do so, here are some of the common changes you'll need to make:
+
+* **Be aware of new defaults for `ecmaVersion` and `sourceType`.** By default, `RuleTester` uses the flat config default of `ecmaVersion: "latest"` and `sourceType: "module"`. This may cause some tests to break if they were expecting the old default of `ecmaVersion: 5` and `sourceType: "script"`. If you'd like to use the old default, you'll need to manually specify that in your `RuleTester` like this:
+
+    ```js
+    // use eslintrc defaults
+    const ruleTester = new RuleTester({
+        languageOptions: {
+            ecmaVersion: 5,
+            sourceType: "script"
+        }
+    });
+    ```
+
+* **Change `parserOptions` to `languageOptions`.** If you're setting `ecmaVersion` or `sourceType` on your tests, move those from `parserOptions` to `languageOptions`, like this:
+
+    ```js
+    ruleTester.run("my-rule", myRule, {
+        valid: [
+            {
+                code: "foo",
+                parserOptions: {
+                    ecmaVersion: 6
+                }
+            }
+        ]
+    });
+
+    // becomes
+
+    ruleTester.run("my-rule", myRule, {
+        valid: [
+            {
+                code: "foo",
+                languageOptions: {
+                    ecmaVersion: 6
+                }
+            }
+        ]
+    });
+    ```
+
+* **Translate other config keys.** Keys such as `env` and `parser` that used to run on the eslintrc config system must be translated into the flat config system. Please refer to the [Configuration Migration Guide](configure/migration-guide) for details on translating other keys you may be using.
+
+**Related Issues(s):** [#13481](https://github.com/eslint/eslint/issues/13481)
+
 ## <a name="flat-eslint"></a> `FlatESLint` is now `ESLint`
 
 As announced in our [blog post](/blog/2023/10/flat-config-rollout-plans/), the temporary `FlatESLint` class has been renamed to `ESLint`, while the `ESLint` class from v8.x has been renamed to `LegacyESLint`.

lib/api.js

@@ -11,7 +11,7 @@
 
 const { ESLint } = require("./eslint/eslint");
 const { Linter } = require("./linter");
-const { FlatRuleTester } = require("./rule-tester");
+const { RuleTester } = require("./rule-tester");
 const { SourceCode } = require("./source-code");
 
 //-----------------------------------------------------------------------------
@@ -21,6 +21,6 @@ const { SourceCode } = require("./source-code");
 module.exports = {
     Linter,
     ESLint,
-    RuleTester: FlatRuleTester,
+    RuleTester,
     SourceCode
 };