eslint-plugin-playwright 0.7.0 → 0.9.0

package/README.md

@@ -98,3 +98,175 @@ Example of **correct** code for this rule:
 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');
+```

package/lib/index.js

@@ -1,4 +1,11 @@
 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");
 
 module.exports = {
   configs: {
@@ -11,6 +18,12 @@ module.exports = {
         "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",
       },
     },
     "jest-playwright": {
@@ -49,5 +62,11 @@ module.exports = {
   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,
   },
 };

package/lib/rules/missing-playwright-await.js

@@ -58,6 +58,7 @@ const playwrightTestMatchers = [
   "toHaveCSS",
   "toHaveId",
   "toHaveJSProperty",
+  "toBeOK",
   "toHaveText",
   "toHaveTitle",
   "toHaveURL",

package/lib/rules/no-element-handle.js

@@ -0,0 +1,47 @@
+const { isObject, isCalleeProperty } = require('../utils/ast');
+
+function getRange(node) {
+  const start = node.parent && node.parent.type === 'AwaitExpression' 
+    ? node.parent.range[0]
+    : node.callee.object.range[0];
+
+  return [start, node.callee.property.range[1]];
+}
+
+module.exports = {
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (isObject(node, 'page') && (isCalleeProperty(node, '$') || isCalleeProperty(node, '$$'))) {
+          context.report({
+            messageId: 'noElementHandle',
+            suggest: [
+              {
+                messageId: isCalleeProperty(node, '$')
+                  ? 'replaceElementHandleWithLocator'
+                  : 'replaceElementHandlesWithLocator',
+                fix: (fixer) => fixer.replaceTextRange(getRange(node), 'page.locator'),
+              },
+            ],
+            node,
+          });
+        }
+      },
+    };
+  },
+  meta: {
+    docs: {
+      category: 'Possible Errors',
+      description: 'The use of ElementHandle is discouraged, use Locator instead',
+      recommended: true,
+      url: 'https://github.com/playwright-community/eslint-plugin-playwright#no-element-handle',
+    },
+    hasSuggestions: true,
+    messages: {
+      noElementHandle: 'Unexpected use of element handles.',
+      replaceElementHandleWithLocator: 'Replace `page.$` with `page.locator`',
+      replaceElementHandlesWithLocator: 'Replace `page.$$` with `page.locator`',
+    },
+    type: 'suggestion',
+  },
+};

package/lib/rules/no-eval.js

@@ -0,0 +1,27 @@
+const { isObject, isCalleeProperty } = require('../utils/ast');
+
+module.exports = {
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (isObject(node, 'page') && (isCalleeProperty(node, '$eval') || isCalleeProperty(node, '$$eval'))) {
+          context.report({ messageId: isCalleeProperty(node, '$eval') ? 'noEval' : 'noEvalAll', node });
+        }
+      },
+    };
+  },
+  meta: {
+    docs: {
+      category: 'Possible Errors',
+      description:
+        'The use of `page.$eval` and `page.$$eval` are discouraged, use `locator.evaluate` or `locator.evaluateAll` instead',
+      recommended: true,
+      url: 'https://github.com/playwright-community/eslint-plugin-playwright#no-eval',
+    },
+    messages: {
+      noEval: 'Unexpected use of page.$eval().',
+      noEvalAll: 'Unexpected use of page.$$eval().',
+    },
+    type: 'problem',
+  },
+};

package/lib/rules/no-focused-test.js

@@ -0,0 +1,49 @@
+const { isTestIdentifier, hasAnnotation } = require('../utils/ast');
+
+function isTestGroup(node) {
+  const testGroups = new Set(['describe', 'parallel', 'serial']);
+
+  return (
+    node.object &&
+    node.object.type === 'MemberExpression' &&
+    node.object.property.type === 'Identifier' &&
+    testGroups.has(node.object.property.name)
+  );
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+  create(context) {
+    return {
+      MemberExpression(node) {
+        if ((isTestIdentifier(node) || isTestGroup(node)) && hasAnnotation(node, 'only')) {
+          context.report({
+            messageId: 'noFocusedTest',
+            suggest: [
+              {
+                messageId: 'removeFocusedTestAnnotation',
+                // - 1 to remove the `.only` annotation with dot notation
+                fix: (fixer) => fixer.removeRange([node.property.range[0] - 1, node.property.range[1]]),
+              },
+            ],
+            node,
+          });
+        }
+      },
+    };
+  },
+  meta: {
+    docs: {
+      category: 'Possible Errors',
+      description: 'Prevent usage of `.only()` focus test annotation',
+      recommended: true,
+      url: 'https://github.com/playwright-community/eslint-plugin-playwright#no-focused-test',
+    },
+    hasSuggestions: true,
+    messages: {
+      noFocusedTest: 'Unexpected use of .only() annotation.',
+      removeFocusedTestAnnotation: 'Remove .only() annotation',
+    },
+    type: 'problem',
+  },
+};

package/lib/rules/no-force-option.js

@@ -0,0 +1,52 @@
+function isForceOptionEnabled({ parent }) {
+  return (
+    parent &&
+    parent.arguments &&
+    parent.arguments.length &&
+    parent.arguments.some(
+      (argument) =>
+        argument.type === 'ObjectExpression' &&
+        argument.properties.some(({ key, value }) => key && key.name === 'force' && value && value.value === true)
+    )
+  );
+}
+
+// https://playwright.dev/docs/api/class-locator
+const methodsWithForceOption = new Set([
+  'check',
+  'uncheck',
+  'click',
+  'dblclick',
+  'dragTo',
+  'fill',
+  'hover',
+  'selectOption',
+  'selectText',
+  'setChecked',
+  'tap',
+]);
+
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+  create(context) {
+    return {
+      MemberExpression(node) {
+        if (node.property && methodsWithForceOption.has(node.property.name) && isForceOptionEnabled(node)) {
+          context.report({ messageId: 'noForceOption', node });
+        }
+      },
+    };
+  },
+  meta: {
+    docs: {
+      category: 'Best Practices',
+      description: 'Prevent usage of `{ force: true }` option.',
+      recommended: true,
+      url: 'https://github.com/playwright-community/eslint-plugin-playwright#no-force-option',
+    },
+    messages: {
+      noForceOption: 'Unexpected use of { force: true } option.',
+    },
+    type: 'suggestion',
+  },
+};

package/lib/rules/no-page-pause.js

@@ -1,8 +1,10 @@
+const { isObject, isCalleeProperty } = require('../utils/ast');
+
 module.exports = {
   create(context) {
     return {
-      MemberExpression(node) {
-        if (node.object.name === "page" && node.property.name === "pause") {
+      CallExpression(node) {
+        if (isObject(node, 'page') && isCalleeProperty(node, 'pause')) {
           context.report({ messageId: "noPagePause", node });
         }
       },

package/lib/rules/no-skipped-test.js

@@ -0,0 +1,66 @@
+const {
+  isTestIdentifier,
+  isObjectProperty,
+  hasAnnotation,
+  isStringLiteral,
+  isBooleanLiteral,
+  isBinaryExpression,
+} = require('../utils/ast');
+
+/**
+ * This function returns needed range to remove skip annotation.
+ *
+ * To cover the standalone cases:
+ * 1. test.skip() => when there's no arguments
+ * 2. test.skip(browserName === 'firefox', 'Working on it') => when there's first argument is a binary expression and the second argument is a string literal
+ * 3. test.skip(true, 'Working on it') => when there's first argument is a boolean literal and the second argument is a string literal
+ *
+ * So, if it's standalone skip then we need to remove the whole line
+ *
+ * Otherwise we need to remove the range of `.skip` annotation - 1 (dot notation).
+ */
+function getSkipRange(node) {
+  const [first, second] = node.parent.arguments;
+
+  const isStandaloneSkip =
+    !node.parent.arguments.length ||
+    ((isBinaryExpression(first) || isBooleanLiteral(first)) && isStringLiteral(second));
+
+  return isStandaloneSkip ? node.parent.parent.range : [node.property.range[0] - 1, node.property.range[1]];
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+  create(context) {
+    return {
+      MemberExpression(node) {
+        if ((isTestIdentifier(node) || isObjectProperty(node, 'describe')) && hasAnnotation(node, 'skip')) {
+          context.report({
+            messageId: 'noSkippedTest',
+            suggest: [
+              {
+                messageId: 'removeSkippedTestAnnotation',
+                fix: (fixer) => fixer.removeRange(getSkipRange(node)),
+              },
+            ],
+            node,
+          });
+        }
+      },
+    };
+  },
+  meta: {
+    docs: {
+      category: 'Best Practices',
+      description: 'Prevent usage of the `.skip()` skip test annotation.',
+      recommended: true,
+      url: 'https://github.com/playwright-community/eslint-plugin-playwright#no-skipped-test',
+    },
+    hasSuggestions: true,
+    messages: {
+      noSkippedTest: 'Unexpected use of the `.skip()` annotation.',
+      removeSkippedTestAnnotation: 'Remove the `.skip()` annotation.',
+    },
+    type: 'suggestion',
+  },
+};

package/lib/rules/no-wait-for-timeout.js

@@ -0,0 +1,40 @@
+const { isObject, isCalleeProperty } = require('../utils/ast');
+
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (isObject(node, 'page') && isCalleeProperty(node, 'waitForTimeout')) {
+          context.report({
+            messageId: 'noWaitForTimeout',
+            suggest: [
+              {
+                messageId: 'removeWaitForTimeout',
+                fix: (fixer) =>
+                  fixer.remove(
+                    node.parent && node.parent.type !== 'AwaitExpression' ? node.parent : node.parent.parent
+                  ),
+              },
+            ],
+            node,
+          });
+        }
+      },
+    };
+  },
+  meta: {
+    docs: {
+      category: 'Best Practices',
+      description: 'Prevent usage of page.waitForTimeout()',
+      recommended: true,
+      url: 'https://github.com/playwright-community/eslint-plugin-playwright#no-wait-for-timeout',
+    },
+    hasSuggestions: true,
+    messages: {
+      noWaitForTimeout: 'Unexpected use of page.waitForTimeout().',
+      removeWaitForTimeout: 'Remove the page.waitForTimeout() method.',
+    },
+    type: 'suggestion',
+  },
+};

package/lib/utils/ast.js

@@ -0,0 +1,61 @@
+function isObject({ callee }, name) {
+  return (
+    callee &&
+    callee.type === 'MemberExpression' &&
+    callee.object.type === 'Identifier' &&
+    callee.object.name === name
+  );
+}
+
+function isCalleeProperty({ callee }, name) {
+  return (
+    callee &&
+    callee.property &&
+    callee.property.type === 'Identifier' &&
+    callee.property.name === name
+  );
+}
+
+function isTestIdentifier(node) {
+  return node.object && node.object.type === 'Identifier' && node.object.name === 'test';
+}
+
+function hasAnnotation(node, annotation) {
+  return (
+    node.property &&
+    node.property.type === 'Identifier' &&
+    node.property.name === annotation
+  );
+}
+
+function isObjectProperty({ object }, name) {
+  return (
+    object &&
+    object.type === 'MemberExpression' &&
+    object.property.type === 'Identifier' &&
+    object.property.name === name
+  );
+}
+
+function isStringLiteral(node) {
+  return node && node.type === 'Literal' && typeof node.value === 'string';
+}
+
+function isBooleanLiteral(node) {
+  return node && node.type === 'Literal' && typeof node.value === 'boolean';
+}
+
+function isBinaryExpression(node) {
+  return node && node.type === 'BinaryExpression';
+}
+
+module.exports = {
+  isObject,
+  isCalleeProperty,
+  isTestIdentifier,
+  hasAnnotation,
+  isObjectProperty,
+  isStringLiteral,
+  isBooleanLiteral,
+  isBinaryExpression,
+};

package/lib/utils/rule-tester.js

@@ -0,0 +1,34 @@
+const { RuleTester } = require('eslint');
+
+/**
+ *
+ * @param {string} name - The name of the rule
+ * @param {string} rule - Path to the rule to test
+ * @param {Object} tests - The tests to run
+ * @param {string[]} tests.valid - Valid tests
+ * @param {string[]} tests.invalid - Invalid tests
+ *
+ * @example
+ * const rule = require('../lib/rules/missing-playwright-await');
+ *
+ * runRuleTester('missing-playwright-await', rule, {
+ *   valid: ['await expect(page.locator('checkbox')).toBeChecked()'],
+ *   invalid: ['expect(page.locator('checkbox')).toBeChecked()'],
+ * });
+ */
+function runRuleTester(name, rule, tests) {
+  const config = {
+    parserOptions: {
+      ecmaVersion: 2018,
+    },
+  };
+
+  return new RuleTester(config).run(name, rule, tests);
+}
+
+const wrapInTest = (input) => `test('test', async () => { ${input} })`;
+
+module.exports = {
+  runRuleTester,
+  wrapInTest,
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "eslint-plugin-playwright",
   "description": "ESLint plugin for Playwright testing.",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "main": "lib/index.js",
   "repository": "https://github.com/playwright-community/eslint-plugin-playwright",
   "author": "Max Schmitt <max@schmitt.mx>",