feat: add basic rule for no-get-by-for-absent-elements

Author: thomaslombart

docs/rules/no-get-by-for-absent-elements.md

@@ -0,0 +1,81 @@
+# Disallow the use of `expect(getBy*)` (prefer-expect-query-by)
+
+The (DOM) Testing Library allows to query DOM elements using different types of queries such as `getBy*` and `queryBy*`. Using `getBy*` throws an error in case the element is not found. This is useful when:
+
+- using method like `waitForElement`, which are `async` functions that will wait for the element to be found until a certain timeout, after that the test will fail.
+- using `getBy` queries as an assert itself, so if the element is not found the error thrown will work as the check itself within the test.
+
+However, when trying to assert if an element is not present or disappearance, we can't use `getBy*` as the test will fail immediately. Instead it is recommended to use `queryBy*`, which does not throw and therefore we can assert that e.g. `expect(queryByText("Foo")).not.toBeInTheDocument()`.
+
+> The same applies for the `getAll*` and `queryAll*` queries too.
+
+## Rule details
+
+This rule gives a notification whenever `expect` is used with one of the query functions that throw an error if the element is not found.
+
+Examples of **incorrect** code for this rule:
+
+```js
+test('some test', () => {
+  const { getByText, getAllByText } = render(<App />);
+  expect(getByText('Foo')).toBeInTheDocument();
+  expect(getAllByText('Foo')[0]).toBeInTheDocument();
+  expect(getByText('Foo')).not.toBeInTheDocument();
+  expect(getAllByText('Foo')[0]).not.toBeInTheDocument();
+});
+```
+
+```js
+test('some test', async () => {
+  const utils = render(<App />);
+  await wait(() => {
+    expect(utils.getByText('Foo')).toBeInTheDocument();
+  });
+  await wait(() => {
+    expect(utils.getAllByText('Foo')).toBeInTheDocument();
+  });
+  await wait(() => {
+    expect(utils.getByText('Foo')).not.toBeInTheDocument();
+  });
+  await wait(() => {
+    expect(utils.getAllByText('Foo')).not.toBeInTheDocument();
+  });
+});
+```
+
+Examples of **correct** code for this rule:
+
+```js
+test('some test', () => {
+  const { queryByText, queryAllByText } = render(<App />);
+  expect(queryByText('Foo')).toBeInTheDocument();
+  expect(queryAllByText('Foo')[0]).toBeInTheDocument();
+  expect(queryByText('Foo')).not.toBeInTheDocument();
+  expect(queryAllByText('Foo')[0]).not.toBeInTheDocument();
+});
+```
+
+```js
+test('some test', async () => {
+  const utils = render(<App />);
+  await wait(() => {
+    expect(utils.queryByText('Foo')).toBeInTheDocument();
+  });
+  await wait(() => {
+    expect(utils.queryAllByText('Foo')).toBeInTheDocument();
+  });
+  await wait(() => {
+    expect(utils.queryByText('Foo')).not.toBeInTheDocument();
+  });
+  await wait(() => {
+    expect(utils.queryAllByText('Foo')).not.toBeInTheDocument();
+  });
+});
+```
+
+## Further Reading
+
+- [Asserting elements are not present](https://testing-library.com/docs/guide-disappearance#asserting-elements-are-not-present)
+- [Waiting for disappearance](https://testing-library.com/docs/guide-disappearance#waiting-for-disappearance)
+- [jest-dom note about using `getBy` within assertions](https://testing-library.com/docs/ecosystem-jest-dom)
+- [Testing Library queries cheatsheet](https://testing-library.com/docs/dom-testing-library/cheatsheet#queries)

lib/index.js

@@ -7,6 +7,7 @@ const rules = {
   'no-await-sync-query': require('./rules/no-await-sync-query'),
   'no-debug': require('./rules/no-debug'),
   'no-dom-import': require('./rules/no-dom-import'),
+  'no-get-by-for-absent-elements': require('./rules/no-get-by-for-absent-elements'),
   'prefer-expect-query-by': require('./rules/prefer-expect-query-by'),
   'prefer-explicit-assert': require('./rules/prefer-explicit-assert'),
 };

lib/rules/no-get-by-for-absent-elements.js

@@ -0,0 +1,65 @@
+'use strict';
+
+const { getDocsUrl } = require('../utils');
+
+const falsyMatchers = ['toBeNull', 'toBeFalsy', 'toBeUndefined'];
+
+module.exports = {
+  meta: {
+    docs: {
+      category: 'Best Practices',
+      description:
+        'Disallow using getBy* queries in expect calls when elements may not be present',
+      recommended: 'error',
+      url: getDocsUrl('no-get-by-for-absent-elements'),
+    },
+    messages: {
+      expectQueryBy:
+        'Use `expect(getBy*)` only when elements are present, otherwise use `expect(queryBy*)`.',
+    },
+    schema: [],
+    type: 'suggestion',
+    fixable: null,
+  },
+
+  create: context => ({
+    [`CallExpression > Identifier[name=/getBy|getAllBy/]`](node) {
+      const expectCallNode = findClosestExpectStatement(node);
+
+      if (expectCallNode) {
+        const expectStatement = expectCallNode.parent;
+        const matcher = expectStatement.property.name;
+
+        if (matcher === 'not') {
+          const negatedMatcher = expectStatement.parent.property.name;
+
+          if (!falsyMatchers.includes(negatedMatcher)) {
+            return context.report({
+              node,
+              messageId: 'expectQueryBy',
+            });
+          }
+        }
+
+        if (falsyMatchers.includes(matcher)) {
+          return context.report({
+            node,
+            messageId: 'expectQueryBy',
+          });
+        }
+      }
+    },
+  }),
+};
+
+function findClosestExpectStatement(node) {
+  if (!node.parent) {
+    return false;
+  }
+
+  if (node.type === 'CallExpression' && node.callee.name === 'expect') {
+    return node;
+  } else {
+    return findClosestExpectStatement(node.parent);
+  }
+}

tests/lib/rules/no-get-by-for-absent-elements.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const RuleTester = require('eslint').RuleTester;
+const rule = require('../../../lib/rules/no-get-by-for-absent-elements');
+const { ALL_QUERIES_METHODS } = require('../../../lib/utils');
+
+const ruleTester = new RuleTester({
+  parserOptions: { ecmaVersion: 2015, sourceType: 'module' },
+});
+
+const queryByVariants = ALL_QUERIES_METHODS.reduce(
+  (variants, method) => [
+    ...variants,
+    ...[`query${method}`, `queryAll${method}`],
+  ],
+  []
+);
+const getByVariants = ALL_QUERIES_METHODS.reduce(
+  (variants, method) => [...variants, ...[`get${method}`, `getAll${method}`]],
+  []
+);
+
+ruleTester.run('prefer-expect-query-by', rule, {
+  valid: queryByVariants.reduce(
+    (validRules, queryName) => [
+      ...validRules,
+      { code: `expect(${queryName}('Hello')).toBeInTheDocument()` },
+      { code: `expect(${queryName}('Hello')).toBe("foo")` },
+      { code: `expect(${queryName}('Hello')).toBeTruthy()` },
+    ],
+    []
+  ),
+  invalid: getByVariants.reduce(
+    (invalidRules, queryName) => [
+      ...invalidRules,
+      {
+        code: `expect(${queryName}('Hello')).not.toBeInTheDocument()`,
+        errors: [{ messageId: 'expectQueryBy' }],
+      },
+      {
+        code: `expect(${queryName}('Hello')).toBeNull()`,
+        errors: [{ messageId: 'expectQueryBy' }],
+      },
+      {
+        code: `expect(${queryName}('Hello')).not.toBeTruthy()`,
+        errors: [{ messageId: 'expectQueryBy' }],
+      },
+      {
+        code: `expect(${queryName}('Hello')).toBeUndefined()`,
+        errors: [{ messageId: 'expectQueryBy' }],
+      },
+      {
+        code: `expect(${queryName}('Hello')).toBeFalsy()`,
+        errors: [{ messageId: 'expectQueryBy' }],
+      },
+    ],
+    []
+  ),
+});