eslint-plugin-playwright 0.10.0 → 0.11.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 Max Schmitt
+Copyright (c) 2022 Max Schmitt
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -3,25 +3,27 @@
 [![Test](https://github.com/playwright-community/eslint-plugin-playwright/actions/workflows/test.yml/badge.svg)](https://github.com/playwright-community/eslint-plugin-playwright/actions/workflows/test.yml)
 [![NPM](https://img.shields.io/npm/v/eslint-plugin-playwright)](https://www.npmjs.com/package/eslint-plugin-playwright)
 
-> ESLint plugin for your [Playwright](https://github.com/microsoft/playwright) testing needs.
+> ESLint plugin for your [Playwright](https://github.com/microsoft/playwright)
+> testing needs.
 
 ## Installation
 
 Yarn
 
-```sh
+```bash
 yarn add -D eslint-plugin-playwright
 ```
 
 NPM
 
-```sh
+```bash
 npm install -D eslint-plugin-playwright
 ```
 
 ## Usage
 
-This plugin bundles two configurations to work with both `@playwright/test` or `jest-playwright`.
+This plugin bundles two configurations to work with both `@playwright/test` or
+`jest-playwright`.
 
 ### With [Playwright test runner](https://playwright.dev/docs/test-intro)
 
@@ -39,360 +41,29 @@ This plugin bundles two configurations to work with both `@playwright/test` or `
 }
 ```
 
-## Rules
-
-### `missing-playwright-await` 🔧
-
-Identify false positives when async Playwright APIs are not properly awaited.
-
-#### Example
-
-Example of **incorrect** code for this rule:
-
-```js
-expect(page).toMatchText('text');
-
-test.step('clicks the button', async () => {
-  await page.click('button');
-});
-```
-
-Example of **correct** code for this rule:
-
-```js
-await expect(page).toMatchText('text');
-
-await test.step('clicks the button', async () => {
-  await page.click('button');
-});
-```
-
-#### Options
-
-The rule accepts a non-required option which can be used to specify custom matchers which this rule should also warn about. This is useful when creating your own async `expect` matchers.
-
-```json
-{
-  "playwright/missing-playwright-await": [
-    "error",
-    { "customMatchers": ["toBeCustomThing"] }
-  ]
-}
-```
-
-### `no-page-pause`
-
-Prevent usage of `page.pause()`.
-
-#### Example
-
-Example of **incorrect** code for this rule:
-
-```js
-await page.click('button');
-await page.pause();
-```
-
-Example of **correct** code for this rule:
-
-```js
-await page.click('button');
-```
-
-### `no-element-handle`
-
-Disallow the creation of element handles with `page.$` or `page.$$`.
-
-Examples of **incorrect** code for this rule:
-
-```js
-// Element Handle
-const buttonHandle = await page.$('button');
-await buttonHandle.click();
-
-// Element Handles
-const linkHandles = await page.$$('a');
-```
-
-Example of **correct** code for this rule:
-
-```js
-const buttonLocator = page.locator('button');
-await buttonLocator.click();
-```
-
-### `no-eval`
-
-Disallow usage of `page.$eval` and `page.$$eval`.
-
-Examples of **incorrect** code for this rule:
-
-```js
-const searchValue = await page.$eval('#search', (el) => el.value);
-
-const divCounts = await page.$$eval(
-  'div',
-  (divs, min) => divs.length >= min,
-  10
-);
-
-await page.$eval('#search', (el) => el.value);
-
-await page.$$eval('#search', (el) => el.value);
-```
-
-Example of **correct** code for this rule:
-
-```js
-await page.locator('button').evaluate((node) => node.innerText);
-
-await page.locator('div').evaluateAll((divs, min) => divs.length >= min, 10);
-```
-
-### `no-focused-test`
-
-Disallow usage of `.only()` annotation
-
-Examples of **incorrect** code for this rule:
-
-```js
-test.only('focus this test', async ({ page }) => {});
-
-test.describe.only('focus two tests', () => {
-  test('one', async ({ page }) => {});
-  test('two', async ({ page }) => {});
-});
-
-test.describe.parallel.only('focus two tests in parallel mode', () => {
-  test('one', async ({ page }) => {});
-  test('two', async ({ page }) => {});
-});
-
-test.describe.serial.only('focus two tests in serial mode', () => {
-  test('one', async ({ page }) => {});
-  test('two', async ({ page }) => {});
-});
-```
-
-Examples of **correct** code for this rule:
-
-```js
-test('this test', async ({ page }) => {});
-
-test.describe('two tests', () => {
-  test('one', async ({ page }) => {});
-  test('two', async ({ page }) => {});
-});
-
-test.describe.parallel('two tests in parallel mode', () => {
-  test('one', async ({ page }) => {});
-  test('two', async ({ page }) => {});
-});
-
-test.describe.serial('two tests in serial mode', () => {
-  test('one', async ({ page }) => {});
-  test('two', async ({ page }) => {});
-});
-```
-
-### `no-wait-for-timeout`
-
-Disallow usage of `page.waitForTimeout()`.
-
-Example of **incorrect** code for this rule:
-
-```js
-await page.waitForTimeout(5000);
-```
-
-Examples of **correct** code for this rule:
-
-```js
-// Use signals such as network events, selectors becoming visible and others instead.
-await page.waitForLoadState();
-
-await page.waitForUrl('/home');
-
-await page.waitForFunction(() => window.innerWidth < 100);
-```
-
-### `no-skipped-test`
-
-Disallow usage of the `.skip()` annotation.
-
-Examples of **incorrect** code for this rule:
-
-```js
-test.skip('skip this test', async ({ page }) => {});
-
-test.describe.skip('skip two tests', () => {
-  test('one', async ({ page }) => {});
-  test('two', async ({ page }) => {});
-});
-
-test.describe('skip test inside describe', () => {
-  test.skip();
-});
-
-test.describe('skip test conditionally', async ({ browserName }) => {
-  test.skip(browserName === 'firefox', 'Working on it');
-});
-```
-
-Examples of **correct** code for this rule:
-
-```js
-test('this test', async ({ page }) => {});
-
-test.describe('two tests', () => {
-  test('one', async ({ page }) => {});
-  test('two', async ({ page }) => {});
-});
-```
-
-### `no-force-option`
-
-Disallow usage of the `{ force: true }` option.
-
-Examples of **incorrect** code for this rule:
-
-```js
-await page.locator('button').click({ force: true });
-
-await page.locator('check').check({ force: true });
-
-await page.locator('input').fill('something', { force: true });
-```
-
-Examples of **correct** code for this rule:
-
-```js
-await page.locator('button').click();
-
-await page.locator('check').check();
-
-await page.locator('input').fill('something');
-```
-
-### `max-nested-describe`
-
-Enforces a maximum depth to nested `.describe()` calls. Useful for improving readability and parallelization of tests.
-
-Uses a default max depth option of `{ "max": 5 }`.
-
-Examples of **incorrect** code for this rule (using defaults):
-
-```js
-test.describe('level 1', () => {
-  test.describe('level 2', () => {
-    test.describe('level 3', () => {
-      test.describe('level 4', () => {
-        test.describe('level 5', () => {
-          test.describe('level 6', () => {
-            test('this test', async ({ page }) => {});
-            test('that test', async ({ page }) => {});
-          });
-        });
-      });
-    });
-  });
-});
-```
-
-Examples of **correct** code for this rule (using defaults):
-
-```js
-test.describe('first level', () => {
-  test.describe('second level', () => {
-    test('this test', async ({ page }) => {});
-    test('that test', async ({ page }) => {});
-  });
-});
-```
-
-#### Options
-
-The rule accepts a non-required option to override the default maximum nested describe depth (5).
-
-```json
-{
-  "playwright/max-nested-describe": ["error", { "max": 3 }]
-}
-```
-
-### `no-conditional-in-test`
-
-Disallow conditional statements such as `if`, `switch`, and ternary expressions within tests.
-
-Examples of **incorrect** code for this rule:
-
-```js
-test('foo', async ({ page }) => {
-  if (someCondition) {
-    bar();
-  }
-});
-
-test('bar', async ({ page }) => {
-  switch (mode) {
-    case 'single':
-      generateOne();
-      break;
-    case 'double':
-      generateTwo();
-      break;
-    case 'multiple':
-      generateMany();
-      break;
-  }
-
-  await expect(page.locator('.my-image').count()).toBeGreaterThan(0);
-});
-
-test('baz', async ({ page }) => {
-  const hotkey =
-    process.platform === 'linux' ? ['Control', 'Alt', 'f'] : ['Alt', 'f'];
-  await Promise.all(hotkey.map((x) => page.keyboard.down(x)));
-
-  expect(actionIsPerformed()).toBe(true);
-});
-```
-
-Examples of **correct** code for this rule:
-
-```js
-test.describe('my tests', () => {
-  if (someCondition) {
-    test('foo', async ({ page }) => {
-      bar();
-    });
-  }
-});
-
-beforeEach(() => {
-  switch (mode) {
-    case 'single':
-      generateOne();
-      break;
-    case 'double':
-      generateTwo();
-      break;
-    case 'multiple':
-      generateMany();
-      break;
-  }
-});
-
-test('bar', async ({ page }) => {
-  await expect(page.locator('.my-image').count()).toBeGreaterThan(0);
-});
-
-const hotkey =
-  process.platform === 'linux' ? ['Control', 'Alt', 'f'] : ['Alt', 'f'];
-
-test('baz', async ({ page }) => {
-  await Promise.all(hotkey.map((x) => page.keyboard.down(x)));
-
-  expect(actionIsPerformed()).toBe(true);
-});
-```
+## List of Supported Rules
+
+✔: Enabled in the recommended configuration.\
+🔧: Some problems reported by this rule are automatically fixable by the [`--fix`](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix)
+command line option.\
+💡: Some problems reported by this rule are manually fixable by editor
+[suggestions](https://eslint.org/docs/latest/developer-guide/working-with-rules#providing-suggestions).
+
+|  ✔  | 🔧  | 💡  | Rule                                                                                                                                              | Description                                                       |
+| :-: | :-: | :-: | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+|  ✔  |     |     | [max-nested-describe](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/max-nested-describe.md)               | Enforces a maximum depth to nested describe calls                 |
+|  ✔  | 🔧  |     | [missing-playwright-await](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/missing-playwright-await.md)     | Enforce Playwright APIs to be awaited                             |
+|  ✔  |     |     | [no-conditional-in-test](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/no-conditional-in-test.md)         | Disallow conditional logic in tests                               |
+|  ✔  |     | 💡  | [no-element-handle](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/no-element-handle.md)                   | Disallow usage of element handles                                 |
+|  ✔  |     |     | [no-eval](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/no-eval.md)                                       | Disallow usage of `page.$eval` and `page.$$eval`                  |
+|  ✔  |     | 💡  | [no-focused-test](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/no-focused-test.md)                       | Disallow usage of `.only` annotation                              |
+|  ✔  |     |     | [no-force-option](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/no-force-option.md)                       | Disallow usage of the `{ force: true }` option                    |
+|  ✔  |     |     | [no-page-pause](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/no-page-pause.md)                           | Disallow using `page.pause`                                       |
+|     |     |     | [no-restricted-matchers](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/no-restricted-matchers.md)         | Disallow specific matchers & modifiers                            |
+|  ✔  |     | 💡  | [no-skipped-test](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/no-skipped-test.md)                       | Disallow usage of the `.skip` annotation                          |
+|  ✔  | 🔧  |     | [no-useless-not](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/no-useless-not.md)                         | Disallow usage of `not` matchers when a specific matcher exists   |
+|  ✔  |     | 💡  | [no-wait-for-timeout](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/no-wait-for-timeout.md)               | Disallow usage of `page.waitForTimeout`                           |
+|     | 🔧  |     | [prefer-lowercase-title](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/prefer-lowercase-title.md)         | Enforce lowercase test names                                      |
+|     | 🔧  |     | [prefer-to-have-length](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/prefer-to-have-length.md)           | Suggest using `toHaveLength()`                                    |
+|     |     |     | [require-top-level-describe](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/require-top-level-describe.md) | Require test cases and hooks to be inside a `test.describe` block |
+|  ✔  |     |     | [valid-expect](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/valid-expect.md)                             | Enforce valid `expect()` usage                                    |

package/lib/index.js

@@ -1,78 +1,92 @@
-const missingPlaywrightAwait = require('./rules/missing-playwright-await');
-const noPagePause = require('./rules/no-page-pause');
-const noElementHandle = require('./rules/no-element-handle');
-const noEval = require('./rules/no-eval');
-const noFocusedTest = require('./rules/no-focused-test');
-const noSkippedTest = require('./rules/no-skipped-test');
-const noWaitForTimeout = require('./rules/no-wait-for-timeout');
-const noForceOption = require('./rules/no-force-option');
-const maxNestedDescribe = require('./rules/max-nested-describe');
-const noConditionalInTest = require('./rules/no-conditional-in-test');
-
+"use strict";
+const missing_playwright_await_1 = require("./rules/missing-playwright-await");
+const no_page_pause_1 = require("./rules/no-page-pause");
+const no_element_handle_1 = require("./rules/no-element-handle");
+const no_eval_1 = require("./rules/no-eval");
+const no_focused_test_1 = require("./rules/no-focused-test");
+const no_skipped_test_1 = require("./rules/no-skipped-test");
+const no_wait_for_timeout_1 = require("./rules/no-wait-for-timeout");
+const no_force_option_1 = require("./rules/no-force-option");
+const max_nested_describe_1 = require("./rules/max-nested-describe");
+const no_conditional_in_test_1 = require("./rules/no-conditional-in-test");
+const no_restricted_matchers_1 = require("./rules/no-restricted-matchers");
+const no_useless_not_1 = require("./rules/no-useless-not");
+const prefer_lowercase_title_1 = require("./rules/prefer-lowercase-title");
+const prefer_to_have_length_1 = require("./rules/prefer-to-have-length");
+const require_top_level_describe_1 = require("./rules/require-top-level-describe");
+const valid_expect_1 = require("./rules/valid-expect");
 module.exports = {
-  configs: {
-    'playwright-test': {
-      plugins: ['playwright'],
-      env: {
-        'shared-node-browser': true,
-      },
-      rules: {
-        'no-empty-pattern': 'off',
-        'playwright/missing-playwright-await': 'error',
-        'playwright/no-page-pause': 'warn',
-        'playwright/no-element-handle': 'warn',
-        'playwright/no-eval': 'warn',
-        'playwright/no-focused-test': 'error',
-        'playwright/no-skipped-test': 'warn',
-        'playwright/no-wait-for-timeout': 'warn',
-        'playwright/no-force-option': 'warn',
-        'playwright/max-nested-describe': 'warn',
-        'playwright/no-conditional-in-test': 'warn',
-      },
+    configs: {
+        'playwright-test': {
+            plugins: ['playwright'],
+            env: {
+                'shared-node-browser': true,
+            },
+            rules: {
+                'no-empty-pattern': 'off',
+                'playwright/missing-playwright-await': 'error',
+                'playwright/no-page-pause': 'warn',
+                'playwright/no-element-handle': 'warn',
+                'playwright/no-eval': 'warn',
+                'playwright/no-focused-test': 'error',
+                'playwright/no-skipped-test': 'warn',
+                'playwright/no-wait-for-timeout': 'warn',
+                'playwright/no-force-option': 'warn',
+                'playwright/max-nested-describe': 'warn',
+                'playwright/no-conditional-in-test': 'warn',
+                'playwright/no-useless-not': 'warn',
+                'playwright/valid-expect': 'error',
+            },
+        },
+        'jest-playwright': {
+            plugins: ['jest', 'playwright'],
+            env: {
+                'shared-node-browser': true,
+                jest: true,
+            },
+            rules: {
+                'playwright/missing-playwright-await': 'error',
+                'playwright/no-page-pause': 'warn',
+                'jest/no-standalone-expect': [
+                    'error',
+                    {
+                        additionalTestBlockFunctions: [
+                            'test.jestPlaywrightDebug',
+                            'it.jestPlaywrightDebug',
+                            'test.jestPlaywrightSkip',
+                            'it.jestPlaywrightSkip',
+                            'test.jestPlaywrightConfig',
+                            'it.jestPlaywrightConfig',
+                        ],
+                    },
+                ],
+            },
+            globals: {
+                browserName: true,
+                deviceName: true,
+                browser: true,
+                context: true,
+                page: true,
+                jestPlaywright: true,
+            },
+        },
     },
-    'jest-playwright': {
-      plugins: ['jest', 'playwright'],
-      env: {
-        'shared-node-browser': true,
-        jest: true,
-      },
-      rules: {
-        'playwright/missing-playwright-await': 'error',
-        'playwright/no-page-pause': 'warn',
-        'jest/no-standalone-expect': [
-          'error',
-          {
-            additionalTestBlockFunctions: [
-              'test.jestPlaywrightDebug',
-              'it.jestPlaywrightDebug',
-              'test.jestPlaywrightSkip',
-              'it.jestPlaywrightSkip',
-              'test.jestPlaywrightConfig',
-              'it.jestPlaywrightConfig',
-            ],
-          },
-        ],
-      },
-      globals: {
-        browserName: true,
-        deviceName: true,
-        browser: true,
-        context: true,
-        page: true,
-        jestPlaywright: true,
-      },
+    rules: {
+        'missing-playwright-await': missing_playwright_await_1.default,
+        'no-page-pause': no_page_pause_1.default,
+        'no-element-handle': no_element_handle_1.default,
+        'no-eval': no_eval_1.default,
+        'no-focused-test': no_focused_test_1.default,
+        'no-skipped-test': no_skipped_test_1.default,
+        'no-wait-for-timeout': no_wait_for_timeout_1.default,
+        'no-force-option': no_force_option_1.default,
+        'max-nested-describe': max_nested_describe_1.default,
+        'no-conditional-in-test': no_conditional_in_test_1.default,
+        'no-useless-not': no_useless_not_1.default,
+        'no-restricted-matchers': no_restricted_matchers_1.default,
+        'prefer-lowercase-title': prefer_lowercase_title_1.default,
+        'prefer-to-have-length': prefer_to_have_length_1.default,
+        'require-top-level-describe': require_top_level_describe_1.default,
+        'valid-expect': valid_expect_1.default,
     },
-  },
-  rules: {
-    'missing-playwright-await': missingPlaywrightAwait,
-    'no-page-pause': noPagePause,
-    'no-element-handle': noElementHandle,
-    'no-eval': noEval,
-    'no-focused-test': noFocusedTest,
-    'no-skipped-test': noSkippedTest,
-    'no-wait-for-timeout': noWaitForTimeout,
-    'no-force-option': noForceOption,
-    'max-nested-describe': maxNestedDescribe,
-    'no-conditional-in-test': noConditionalInTest,
-  },
 };