Skip to content

Commit

Permalink
docs(no-standalone-expect): Improve documentation around best practices
Browse files Browse the repository at this point in the history
  • Loading branch information
mskelton committed Feb 28, 2024
1 parent 0b0baee commit 95fcfd8
Show file tree
Hide file tree
Showing 2 changed files with 12 additions and 20 deletions.
7 changes: 0 additions & 7 deletions docs/rules/no-conditional-expect.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,6 @@ Additionally, conditionals tend to make tests more brittle and complex, as they
increase the amount of mental thinking needed to understand what is actually
being tested.

While `expect.assertions` & `expect.hasAssertions` can help prevent tests from
silently being skipped, when combined with conditionals they typically result in
even more complexity being introduced.

The following patterns are warnings:

```js
Expand Down Expand Up @@ -103,9 +99,6 @@ test.describe('when the http request fails', () => {
As stated above, the problem with this is that if `makeRequest()` doesn't throw
the test will still pass as if the `expect` had been called.

While you can use `expect.assertions` & `expect.hasAssertions` for these
situations, they only work with `expect`.

A better way to handle this situation is to introduce a wrapper to handle the
catching, and otherwise return a specific "no error thrown" error if nothing is
thrown by the wrapped function:
Expand Down
25 changes: 12 additions & 13 deletions docs/rules/no-standalone-expect.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,18 @@ helper function (but outside of a `test` block) will not trigger this rule.

## Rule details

This rule aims to eliminate `expect` statements that will not be executed. An
`expect` inside of a `describe` block but outside of a `test` block or outside a
`test.describe` will not execute and therefore will trigger this rule. It is
viable, however, to have an `expect` in a helper function that is called from
within a `test` block so `expect` statements in a function will not trigger this
rule.

Statements like `expect.hasAssertions()` will NOT trigger this rule since these
calls will execute if they are not in a test block.
This rule aims to eliminate `expect` statements outside of `test` blocks to
encourage good testing practices. Using `expect` statements outside of `test`
blocks may partially work, but their intent is to be used within a test as doing
so makes it clear the purpose of each test.

Using `expect` in helper functions is allowed to support grouping several expect
statements into a helper function or page object method. Test hooks such as
`beforeEach` are also allowed to support use cases such as waiting for an
element on the page before each test is executed. While these uses cases are
supported, they should be used sparingly as moving too many `expect` statements
outside of the body of a `test` block can make it difficult to understand the
purpose and primary assertions being made by a given test.

Examples of **incorrect** code for this rule:

Expand Down Expand Up @@ -53,10 +56,6 @@ test.describe('a test', () => {
helper();
});
});

test.describe('a test', () => {
expect.hasAssertions(1);
});
```

_Note that this rule will not trigger if the helper function is never used even
Expand Down

0 comments on commit 95fcfd8

Please sign in to comment.