From da5fec1857ae6ce841e2c4138626cbbfbdc4108b Mon Sep 17 00:00:00 2001 From: Gareth Jones Date: Sun, 12 Jul 2020 21:36:58 +1200 Subject: [PATCH] docs: improve rule descriptions --- README.md | 14 +++++------ docs/rules/no-alias-methods.md | 2 +- docs/rules/no-export.md | 2 +- docs/rules/no-standalone-expect.md | 2 +- docs/rules/prefer-called-with.md | 2 +- docs/rules/prefer-hooks-on-top.md | 32 ++++++++++++------------ docs/rules/require-top-level-describe.md | 2 +- docs/rules/valid-title.md | 2 +- src/rules/no-export.ts | 2 +- src/rules/no-mocks-import.ts | 4 +-- src/rules/no-standalone-expect.ts | 2 +- src/rules/prefer-called-with.ts | 2 +- src/rules/prefer-hooks-on-top.ts | 2 +- src/rules/prefer-strict-equal.ts | 2 +- src/rules/require-top-level-describe.ts | 2 +- 15 files changed, 37 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index c708a4254..5223b0cd6 100644 --- a/README.md +++ b/README.md @@ -139,7 +139,7 @@ installations requiring long-term consistency. | [no-deprecated-functions](docs/rules/no-deprecated-functions.md) | Disallow use of deprecated functions | | ![fixable][] | | [no-disabled-tests](docs/rules/no-disabled-tests.md) | Disallow disabled tests | ![recommended][] | | | [no-duplicate-hooks](docs/rules/no-duplicate-hooks.md) | Disallow duplicate setup and teardown hooks | | | -| [no-export](docs/rules/no-export.md) | Prevent exporting from test files | ![recommended][] | | +| [no-export](docs/rules/no-export.md) | Disallow using `exports` in files containing tests | ![recommended][] | | | [no-focused-tests](docs/rules/no-focused-tests.md) | Disallow focused tests | ![recommended][] | ![fixable][] | | [no-hooks](docs/rules/no-hooks.md) | Disallow setup and teardown hooks | | | | [no-identical-title](docs/rules/no-identical-title.md) | Disallow identical titles | ![recommended][] | | @@ -147,24 +147,24 @@ installations requiring long-term consistency. | [no-jasmine-globals](docs/rules/no-jasmine-globals.md) | Disallow Jasmine globals | ![recommended][] | ![fixable][] | | [no-jest-import](docs/rules/no-jest-import.md) | Disallow importing Jest | ![recommended][] | | | [no-large-snapshots](docs/rules/no-large-snapshots.md) | disallow large snapshots | | | -| [no-mocks-import](docs/rules/no-mocks-import.md) | Disallow manually importing from **mocks** | ![recommended][] | | +| [no-mocks-import](docs/rules/no-mocks-import.md) | Disallow manually importing from `__mocks__` | ![recommended][] | | | [no-restricted-matchers](docs/rules/no-restricted-matchers.md) | Disallow specific matchers & modifiers | | | -| [no-standalone-expect](docs/rules/no-standalone-expect.md) | Prevents expects that are outside of an it or test block. | ![recommended][] | | +| [no-standalone-expect](docs/rules/no-standalone-expect.md) | Disallow using `expect` outside of `it` or `test` blocks | ![recommended][] | | | [no-test-callback](docs/rules/no-test-callback.md) | Avoid using a callback in asynchronous tests | ![recommended][] | ![suggest][] | | [no-test-prefixes](docs/rules/no-test-prefixes.md) | Use `.only` and `.skip` over `f` and `x` | ![recommended][] | ![fixable][] | | [no-test-return-statement](docs/rules/no-test-return-statement.md) | Disallow explicitly returning from tests | | | -| [prefer-called-with](docs/rules/prefer-called-with.md) | Suggest using `toBeCalledWith()` OR `toHaveBeenCalledWith()` | | | +| [prefer-called-with](docs/rules/prefer-called-with.md) | Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()` | | | | [prefer-expect-assertions](docs/rules/prefer-expect-assertions.md) | Suggest using `expect.assertions()` OR `expect.hasAssertions()` | | ![suggest][] | -| [prefer-hooks-on-top](docs/rules/prefer-hooks-on-top.md) | Suggest to have all hooks at top level | | | +| [prefer-hooks-on-top](docs/rules/prefer-hooks-on-top.md) | Suggest having hooks before any test cases | | | | [prefer-spy-on](docs/rules/prefer-spy-on.md) | Suggest using `jest.spyOn()` | | ![fixable][] | -| [prefer-strict-equal](docs/rules/prefer-strict-equal.md) | Suggest using toStrictEqual() | | ![suggest][] | +| [prefer-strict-equal](docs/rules/prefer-strict-equal.md) | Suggest using `toStrictEqual()` | | ![suggest][] | | [prefer-to-be-null](docs/rules/prefer-to-be-null.md) | Suggest using `toBeNull()` | ![style][] | ![fixable][] | | [prefer-to-be-undefined](docs/rules/prefer-to-be-undefined.md) | Suggest using `toBeUndefined()` | ![style][] | ![fixable][] | | [prefer-to-contain](docs/rules/prefer-to-contain.md) | Suggest using `toContain()` | ![style][] | ![fixable][] | | [prefer-to-have-length](docs/rules/prefer-to-have-length.md) | Suggest using `toHaveLength()` | ![style][] | ![fixable][] | | [prefer-todo](docs/rules/prefer-todo.md) | Suggest using `test.todo` | | ![fixable][] | | [require-to-throw-message](docs/rules/require-to-throw-message.md) | Require a message for `toThrow()` | | | -| [require-top-level-describe](docs/rules/require-top-level-describe.md) | Prevents test cases and hooks to be outside of a describe block | | | +| [require-top-level-describe](docs/rules/require-top-level-describe.md) | Require test cases and hooks to be inside a `describe` block | | | | [valid-describe](docs/rules/valid-describe.md) | Enforce valid `describe()` callback | ![recommended][] | | | [valid-expect](docs/rules/valid-expect.md) | Enforce valid `expect()` usage | ![recommended][] | | | [valid-expect-in-promise](docs/rules/valid-expect-in-promise.md) | Enforce having return statement when testing with promises | ![recommended][] | | diff --git a/docs/rules/no-alias-methods.md b/docs/rules/no-alias-methods.md index 91c5bf8e3..7f373d5fe 100644 --- a/docs/rules/no-alias-methods.md +++ b/docs/rules/no-alias-methods.md @@ -1,4 +1,4 @@ -# Don't use alias methods (`no-alias-methods`) +# Disallow alias methods (`no-alias-methods`) Several Jest methods have alias names, such as `toThrow` having the alias of `toThrowError`. This rule ensures that only the canonical name as used in the diff --git a/docs/rules/no-export.md b/docs/rules/no-export.md index 1f64c5db8..adab78f5f 100644 --- a/docs/rules/no-export.md +++ b/docs/rules/no-export.md @@ -1,4 +1,4 @@ -# Prevent exporting from test files (`no-export`) +# Disallow using `exports` in files containing tests (`no-export`) Prevents exports from test files. If a file has at least 1 test in it, then this rule will prevent exports. diff --git a/docs/rules/no-standalone-expect.md b/docs/rules/no-standalone-expect.md index eff440a60..ccfbac804 100644 --- a/docs/rules/no-standalone-expect.md +++ b/docs/rules/no-standalone-expect.md @@ -1,4 +1,4 @@ -# No standalone expect in a describe block (`no-standalone-expect`) +# Disallow using `expect` outside of `it` or `test` blocks (`no-standalone-expect`) Prevents `expect` statements outside of a `test` or `it` block. An `expect` within a helper function (but outside of a `test` or `it` block) will not diff --git a/docs/rules/prefer-called-with.md b/docs/rules/prefer-called-with.md index a62035109..09bf7360c 100644 --- a/docs/rules/prefer-called-with.md +++ b/docs/rules/prefer-called-with.md @@ -1,4 +1,4 @@ -# Suggest using `toBeCalledWith` OR `toHaveBeenCalledWith` (`prefer-called-with`) +# Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()` (`prefer-called-with`) The `toBeCalled()` matcher is used to assert that a mock function has been called one or more times, without checking the arguments passed. The assertion diff --git a/docs/rules/prefer-hooks-on-top.md b/docs/rules/prefer-hooks-on-top.md index e9c05cdda..47b9e7514 100644 --- a/docs/rules/prefer-hooks-on-top.md +++ b/docs/rules/prefer-hooks-on-top.md @@ -1,4 +1,4 @@ -# Suggest to have all hooks at top-level before tests (`prefer-hooks-on-top`) +# Suggest having hooks before any test cases (`prefer-hooks-on-top`) All hooks should be defined before the start of the tests @@ -9,37 +9,37 @@ Examples of **incorrect** code for this rule ```js /* eslint jest/prefer-hooks-on-top: "error" */ -describe("foo" () => { +describe('foo', () => { beforeEach(() => { //some hook code }); - test("bar" () => { + test('bar', () => { some_fn(); }); beforeAll(() => { //some hook code }); - test("bar" () => { + test('bar', () => { some_fn(); }); }); // Nested describe scenario -describe("foo" () => { +describe('foo', () => { beforeAll(() => { //some hook code }); - test("bar" () => { + test('bar', () => { some_fn(); }); - describe("inner_foo" () => { + describe('inner_foo', () => { beforeEach(() => { //some hook code }); - test("inner bar" () => { + test('inner bar', () => { some_fn(); }); - test("inner bar" () => { + test('inner bar', () => { some_fn(); }); beforeAll(() => { @@ -48,7 +48,7 @@ describe("foo" () => { afterAll(() => { //some hook code }); - test("inner bar" () => { + test('inner bar', () => { some_fn(); }); }); @@ -60,7 +60,7 @@ Examples of **correct** code for this rule ```js /* eslint jest/prefer-hooks-on-top: "error" */ -describe("foo" () => { +describe('foo', () => { beforeEach(() => { //some hook code }); @@ -71,24 +71,24 @@ describe("foo" () => { afterEach(() => { //some hook code }); - test("bar" () => { + test('bar', () => { some_fn(); }); }); // Nested describe scenario -describe("foo" () => { +describe('foo', () => { beforeEach(() => { //some hook code }); - test("bar" () => { + test('bar', () => { some_fn(); }); - describe("inner_foo" () => { + describe('inner_foo', () => { beforeEach(() => { //some hook code }); - test("inner bar" () => { + test('inner bar', () => { some_fn(); }); }); diff --git a/docs/rules/require-top-level-describe.md b/docs/rules/require-top-level-describe.md index 69c0ffa21..a7b3a27dd 100644 --- a/docs/rules/require-top-level-describe.md +++ b/docs/rules/require-top-level-describe.md @@ -1,4 +1,4 @@ -# Require top-level describe block (`require-top-level-describe`) +# Require test cases and hooks to be inside a `describe` block (`require-top-level-describe`) Jest allows you to organise your test files the way you want it. However, the more your codebase grows, the more it becomes hard to navigate in your test diff --git a/docs/rules/valid-title.md b/docs/rules/valid-title.md index bb3ab76e8..1059e7c7f 100644 --- a/docs/rules/valid-title.md +++ b/docs/rules/valid-title.md @@ -1,4 +1,4 @@ -# describe/test titles should be valid (`valid-title`) +# Enforce valid titles (`valid-title`) Checks that the title of Jest blocks are valid by ensuring that titles are: diff --git a/src/rules/no-export.ts b/src/rules/no-export.ts index 5edb4be4e..7547c4bc3 100644 --- a/src/rules/no-export.ts +++ b/src/rules/no-export.ts @@ -9,7 +9,7 @@ export default createRule({ meta: { docs: { category: 'Best Practices', - description: 'Prevent exporting from test files', + description: 'Disallow using `exports` in files containing tests', recommended: 'error', }, messages: { diff --git a/src/rules/no-mocks-import.ts b/src/rules/no-mocks-import.ts index 53d973448..40d2856c6 100644 --- a/src/rules/no-mocks-import.ts +++ b/src/rules/no-mocks-import.ts @@ -16,11 +16,11 @@ export default createRule({ type: 'problem', docs: { category: 'Best Practices', - description: 'Disallow manually importing from __mocks__ ', + description: 'Disallow manually importing from `__mocks__`', recommended: 'error', }, messages: { - noManualImport: `Mocks should not be manually imported from a ${mocksDirName} directory. Instead use jest.mock and import from the original module path.`, + noManualImport: `Mocks should not be manually imported from a ${mocksDirName} directory. Instead use \`jest.mock\` and import from the original module path.`, }, schema: [], }, diff --git a/src/rules/no-standalone-expect.ts b/src/rules/no-standalone-expect.ts index 98fc79d66..bfe273465 100644 --- a/src/rules/no-standalone-expect.ts +++ b/src/rules/no-standalone-expect.ts @@ -65,7 +65,7 @@ export default createRule< meta: { docs: { category: 'Best Practices', - description: 'Prevents expects that are outside of an it or test block.', + description: 'Disallow using `expect` outside of `it` or `test` blocks', recommended: 'error', }, messages: { diff --git a/src/rules/prefer-called-with.ts b/src/rules/prefer-called-with.ts index f907cba40..70e207f6e 100644 --- a/src/rules/prefer-called-with.ts +++ b/src/rules/prefer-called-with.ts @@ -6,7 +6,7 @@ export default createRule({ docs: { category: 'Best Practices', description: - 'Suggest using `toBeCalledWith()` OR `toHaveBeenCalledWith()`', + 'Suggest using `toBeCalledWith()` or `toHaveBeenCalledWith()`', recommended: false, }, messages: { diff --git a/src/rules/prefer-hooks-on-top.ts b/src/rules/prefer-hooks-on-top.ts index f1507bb49..5d1e0ae61 100644 --- a/src/rules/prefer-hooks-on-top.ts +++ b/src/rules/prefer-hooks-on-top.ts @@ -5,7 +5,7 @@ export default createRule({ meta: { docs: { category: 'Best Practices', - description: 'Suggest to have all hooks at top level', + description: 'Suggest having hooks before any test cases', recommended: false, }, messages: { diff --git a/src/rules/prefer-strict-equal.ts b/src/rules/prefer-strict-equal.ts index a9e41ef9a..559cd990b 100644 --- a/src/rules/prefer-strict-equal.ts +++ b/src/rules/prefer-strict-equal.ts @@ -11,7 +11,7 @@ export default createRule({ meta: { docs: { category: 'Best Practices', - description: 'Suggest using toStrictEqual()', + description: 'Suggest using `toStrictEqual()`', recommended: false, suggestion: true, }, diff --git a/src/rules/require-top-level-describe.ts b/src/rules/require-top-level-describe.ts index dfee7f276..339fd81d1 100644 --- a/src/rules/require-top-level-describe.ts +++ b/src/rules/require-top-level-describe.ts @@ -7,7 +7,7 @@ export default createRule({ docs: { category: 'Best Practices', description: - 'Prevents test cases and hooks to be outside of a describe block', + 'Require test cases and hooks to be inside a `describe` block', recommended: false, }, messages: {