From f89c776ac4a09149f3cd350fce5ef92b8d21a51d Mon Sep 17 00:00:00 2001 From: dalaoshu Date: Wed, 4 Sep 2024 20:29:57 +0800 Subject: [PATCH] chore(linter/vitest): improve docs for vitest rules (#5428) --- .../src/rules/vitest/no_conditional_tests.rs | 10 +++++++++- .../src/rules/vitest/no_import_node_test.rs | 13 ++++++++++--- crates/oxc_linter/src/rules/vitest/prefer_each.rs | 7 +++++++ .../src/rules/vitest/prefer_to_be_falsy.rs | 15 ++++++++++++--- .../src/rules/vitest/prefer_to_be_object.rs | 5 ++++- .../src/rules/vitest/prefer_to_be_truthy.rs | 15 ++++++++++++--- ...local_test_context_for_concurrent_snapshots.rs | 15 ++++++++++++--- 7 files changed, 66 insertions(+), 14 deletions(-) diff --git a/crates/oxc_linter/src/rules/vitest/no_conditional_tests.rs b/crates/oxc_linter/src/rules/vitest/no_conditional_tests.rs index fa51c4362510c..17be91c8848be 100644 --- a/crates/oxc_linter/src/rules/vitest/no_conditional_tests.rs +++ b/crates/oxc_linter/src/rules/vitest/no_conditional_tests.rs @@ -23,7 +23,15 @@ pub struct NoConditionalTests; declare_oxc_lint!( /// ### What it does - /// The rule disallows the use of conditional statements within test cases to ensure that tests are deterministic and clearly readable. + /// + /// The rule disallows the use of conditional statements within test cases to + /// ensure that tests are deterministic and clearly readable. + /// + /// ### Why is this bad? + /// + /// Conditional statements in test cases can make tests unpredictable and + /// harder to understand. Tests should be consistent and straightforward to + /// ensure reliable results and maintainability. /// /// ### Examples /// diff --git a/crates/oxc_linter/src/rules/vitest/no_import_node_test.rs b/crates/oxc_linter/src/rules/vitest/no_import_node_test.rs index 87c032c5d8965..c9a9a8ae45ae4 100644 --- a/crates/oxc_linter/src/rules/vitest/no_import_node_test.rs +++ b/crates/oxc_linter/src/rules/vitest/no_import_node_test.rs @@ -16,12 +16,19 @@ pub struct NoImportNodeTest; declare_oxc_lint!( /// ### What it does /// - /// This rule warns when `node:test` is imported (usually accidentally). With `--fix`, it will replace the import with `vitest`. + /// This rule warns when `node:test` is imported (usually accidentally). + /// With `--fix`, it will replace the import with `vitest`. + /// + /// ### Why is this bad? + /// + /// Using `node:test` instead of `vitest` can lead to inconsistent test results + /// and missing features. `vitest` should be used for all testing to ensure + /// compatibility and access to its full functionality. /// /// ### Examples /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // invalid /// import { test } from 'node:test' /// import { expect } from 'vitest' /// @@ -30,8 +37,8 @@ declare_oxc_lint!( /// }) /// ``` /// + /// Examples of **correct** code for this rule: /// ```javascript - /// // valid /// import { test, expect } from 'vitest' /// /// test('foo', () => { diff --git a/crates/oxc_linter/src/rules/vitest/prefer_each.rs b/crates/oxc_linter/src/rules/vitest/prefer_each.rs index 014884d43d4f1..290fbce9b46fa 100644 --- a/crates/oxc_linter/src/rules/vitest/prefer_each.rs +++ b/crates/oxc_linter/src/rules/vitest/prefer_each.rs @@ -38,8 +38,15 @@ pub struct PreferEach; declare_oxc_lint!( /// ### What it does + /// /// This rule enforces using `each` rather than manual loops. /// + /// ### Why is this bad? + /// + /// Manual loops for tests can be less readable and more error-prone. Using + /// `each` provides a clearer and more concise way to run parameterized tests, + /// improving readability and maintainability. + /// /// ### Examples /// /// Examples of **incorrect** code for this rule: diff --git a/crates/oxc_linter/src/rules/vitest/prefer_to_be_falsy.rs b/crates/oxc_linter/src/rules/vitest/prefer_to_be_falsy.rs index edd060a8da797..cabcf794a9533 100644 --- a/crates/oxc_linter/src/rules/vitest/prefer_to_be_falsy.rs +++ b/crates/oxc_linter/src/rules/vitest/prefer_to_be_falsy.rs @@ -12,16 +12,25 @@ pub struct PreferToBeFalsy; declare_oxc_lint!( /// ### What it does /// - /// This rule warns when `toBe(false)` is used with `expect` or `expectTypeOf`. With `--fix`, it will be replaced with `toBeFalsy()`. + /// This rule warns when `toBe(false)` is used with `expect` or `expectTypeOf`. + /// With `--fix`, it will be replaced with `toBeFalsy()`. + /// + /// ### Why is this bad? + /// + /// Using `toBe(false)` is less expressive and may not account for other falsy + /// values like `0`, `null`, or `undefined`. `toBeFalsy()` provides a more + /// comprehensive check for any falsy value, improving the robustness of the tests. /// /// ### Examples /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // bad /// expect(foo).toBe(false) /// expectTypeOf(foo).toBe(false) + /// ``` /// - /// // good + /// Examples of **correct** code for this rule: + /// ```javascript /// expect(foo).toBeFalsy() /// expectTypeOf(foo).toBeFalsy() /// ``` diff --git a/crates/oxc_linter/src/rules/vitest/prefer_to_be_object.rs b/crates/oxc_linter/src/rules/vitest/prefer_to_be_object.rs index 7550ce70a70ca..5d0b6acad00bc 100644 --- a/crates/oxc_linter/src/rules/vitest/prefer_to_be_object.rs +++ b/crates/oxc_linter/src/rules/vitest/prefer_to_be_object.rs @@ -42,7 +42,10 @@ declare_oxc_lint!( /// /// ### Why is this bad? /// - /// Using other methods such as `toBeInstanceOf(Object)` or `instanceof Object` can be less clear and potentially misleading. Enforcing the use of `toBeObject()` provides more explicit and readable code, making your intentions clear and improving the overall maintainability and readability of your tests. + /// Using other methods such as `toBeInstanceOf(Object)` or `instanceof Object` can + /// be less clear and potentially misleading. Enforcing the use of `toBeObject()` + /// provides more explicit and readable code, making your intentions clear and + /// improving the overall maintainability and readability of your tests. /// /// ### Examples /// diff --git a/crates/oxc_linter/src/rules/vitest/prefer_to_be_truthy.rs b/crates/oxc_linter/src/rules/vitest/prefer_to_be_truthy.rs index 9997e8a5d41c9..836f8160817e2 100644 --- a/crates/oxc_linter/src/rules/vitest/prefer_to_be_truthy.rs +++ b/crates/oxc_linter/src/rules/vitest/prefer_to_be_truthy.rs @@ -12,16 +12,25 @@ pub struct PreferToBeTruthy; declare_oxc_lint!( /// ### What it does /// - /// This rule warns when `toBe(true)` is used with `expect` or `expectTypeOf`. With `--fix`, it will be replaced with `toBeTruthy()`. + /// This rule warns when `toBe(true)` is used with `expect` or `expectTypeOf`. + /// With `--fix`, it will be replaced with `toBeTruthy()`. + /// + /// ### Why is this bad? + /// + /// Using `toBe(true)` is less flexible and may not account for other truthy + /// values like non-empty strings or objects. `toBeTruthy()` checks for any + /// truthy value, which makes the tests more comprehensive and robust. /// /// ### Examples /// + /// Examples of **incorrect** code for this rule: /// ```javascript - /// // bad /// expect(foo).toBe(true) /// expectTypeOf(foo).toBe(true) + /// ``` /// - /// // good + /// Examples of **correct** code for this rule: + /// ```javascript /// expect(foo).toBeTruthy() /// expectTypeOf(foo).toBeTruthy() /// ``` diff --git a/crates/oxc_linter/src/rules/vitest/require_local_test_context_for_concurrent_snapshots.rs b/crates/oxc_linter/src/rules/vitest/require_local_test_context_for_concurrent_snapshots.rs index 067f2ad7dd62b..4247b8d546a76 100644 --- a/crates/oxc_linter/src/rules/vitest/require_local_test_context_for_concurrent_snapshots.rs +++ b/crates/oxc_linter/src/rules/vitest/require_local_test_context_for_concurrent_snapshots.rs @@ -50,12 +50,21 @@ pub struct RequireLocalTestContextForConcurrentSnapshots; declare_oxc_lint!( /// ### What it does - /// The rule is intended to ensure that concurrent snapshot tests are executed within a properly configured local test context. + /// + /// The rule is intended to ensure that concurrent snapshot tests are executed + /// within a properly configured local test context. + /// + /// ### Why is this bad? + /// + /// Running snapshot tests concurrently without a proper context can lead to + /// unreliable or inconsistent snapshots. Ensuring that concurrent tests are + /// correctly configured with the appropriate context helps maintain accurate + /// and stable snapshots, avoiding potential conflicts or failures. /// /// ### Examples /// /// Examples of **incorrect** code for this rule: - /// ```js + /// ```javascript /// test.concurrent('myLogic', () => { /// expect(true).toMatchSnapshot(); /// }) @@ -69,7 +78,7 @@ declare_oxc_lint!( /// ``` /// /// Examples of **correct** code for this rule: - /// ```js + /// ```javascript /// test.concurrent('myLogic', ({ expect }) => { /// expect(true).toMatchSnapshot(); /// })