eslint-plugin-playwright 1.2.0 → 1.3.1

package/dist/index.js

@@ -35,7 +35,7 @@ function getRawValue(node) {
   return node.type === "Literal" ? node.raw : void 0;
 }
 function isIdentifier(node, name) {
-  return node.type === "Identifier" && (typeof name === "string" ? node.name === name : name.test(node.name));
+  return node.type === "Identifier" && (!name || (typeof name === "string" ? node.name === name : name.test(node.name)));
 }
 function isLiteral(node, type, value) {
   return node.type === "Literal" && (value === void 0 ? typeof node.value === type : node.value === value);
@@ -48,8 +48,8 @@ function isStringLiteral(node, value) {
 function isBooleanLiteral(node, value) {
   return isLiteral(node, "boolean", value);
 }
-function isStringNode(node) {
-  return node && (isStringLiteral(node) || isTemplateLiteral(node));
+function isStringNode(node, value) {
+  return node && (isStringLiteral(node, value) || isTemplateLiteral(node, value));
 }
 function isPropertyAccessor(node, name) {
   return getStringValue(node.property) === name;
@@ -91,7 +91,12 @@ function findParent(node, type) {
 function isTestCall(context, node, modifiers) {
   return isTestIdentifier(context, node.callee) && !isDescribeCall(node) && (node.callee.type !== "MemberExpression" || !modifiers || modifiers?.includes(getStringValue(node.callee.property))) && node.arguments.length === 2 && isFunction(node.arguments[1]);
 }
-var testHooks = /* @__PURE__ */ new Set(["afterAll", "afterEach", "beforeAll", "beforeEach"]);
+var testHooks = /* @__PURE__ */ new Set([
+  "afterAll",
+  "afterEach",
+  "beforeAll",
+  "beforeEach"
+]);
 function isTestHook(context, node) {
   return node.callee.type === "MemberExpression" && isTestIdentifier(context, node.callee.object) && testHooks.has(getStringValue(node.callee.property));
 }
@@ -130,6 +135,7 @@ function isPageMethod(node, name) {
 function isFunction(node) {
   return node.type === "ArrowFunctionExpression" || node.type === "FunctionExpression";
 }
+var equalityMatchers = /* @__PURE__ */ new Set(["toBe", "toEqual", "toStrictEqual"]);
 
 // src/rules/expect-expect.ts
 function isAssertionCall(context, node, assertFunctionNames) {
@@ -865,6 +871,178 @@ var no_get_by_title_default = {
   }
 };
 
+// src/utils/parseFnCall.ts
+var VALID_CHAINS = /* @__PURE__ */ new Set([
+  // Hooks
+  "afterAll",
+  "afterEach",
+  "beforeAll",
+  "beforeEach",
+  "test.afterAll",
+  "test.afterEach",
+  "test.beforeAll",
+  "test.beforeEach",
+  // Describe
+  "describe",
+  "describe.only",
+  "describe.skip",
+  "describe.fixme",
+  "describe.configure",
+  "test.describe",
+  "test.describe.only",
+  "test.describe.skip",
+  "test.describe.fixme",
+  "test.describe.configure",
+  // Test
+  "test",
+  "test.fail",
+  "text.fixme",
+  "test.only",
+  "test.skip",
+  "test.slow",
+  "test.step",
+  "test.use"
+]);
+var joinChains = (a, b) => a && b ? [...a, ...b] : null;
+var isSupportedAccessor = (node, value) => isIdentifier(node, value) || isStringNode(node, value);
+function getNodeChain(node) {
+  if (isSupportedAccessor(node)) {
+    return [node];
+  }
+  switch (node.type) {
+    case "TaggedTemplateExpression":
+      return getNodeChain(node.tag);
+    case "MemberExpression":
+      return joinChains(getNodeChain(node.object), getNodeChain(node.property));
+    case "CallExpression":
+      return getNodeChain(node.callee);
+  }
+  return null;
+}
+var resolvePossibleAliasedGlobal = (context, global) => {
+  const globalAliases = context.settings.playwright?.globalAliases ?? {};
+  const alias = Object.entries(globalAliases).find(
+    ([, aliases]) => aliases.includes(global)
+  );
+  return alias?.[0] ?? null;
+};
+var resolveToPlaywrightFn = (context, accessor) => {
+  const ident = getStringValue(accessor);
+  return {
+    local: ident,
+    original: resolvePossibleAliasedGlobal(context, ident),
+    type: "global"
+  };
+};
+function determinePlaywrightFnType(name) {
+  if (name === "expect")
+    return "expect";
+  if (name === "describe")
+    return "describe";
+  if (name === "test")
+    return "test";
+  if (testHooks.has(name))
+    return "hook";
+  return "unknown";
+}
+function parseFnCall(context, node) {
+  const chain = getNodeChain(node);
+  if (!chain?.length) {
+    return null;
+  }
+  const [first, ...rest] = chain;
+  const resolved = resolveToPlaywrightFn(context, first);
+  if (!resolved)
+    return null;
+  let name = resolved.original ?? resolved.local;
+  const links = [name, ...rest.map((link) => getStringValue(link))];
+  if (name !== "expect" && !VALID_CHAINS.has(links.join("."))) {
+    return null;
+  }
+  if (name === "test" && links.length > 1) {
+    const nextLinkName = links[1];
+    const nextLinkType = determinePlaywrightFnType(nextLinkName);
+    if (nextLinkType !== "unknown") {
+      name = nextLinkName;
+    }
+  }
+  const parsedFnCall = {
+    head: { ...resolved, node: first },
+    // every member node must have a member expression as their parent
+    // in order to be part of the call chain we're parsing
+    members: rest,
+    name
+  };
+  const type = determinePlaywrightFnType(name);
+  if (type === "expect") {
+    return {
+      ...parsedFnCall,
+      args: [],
+      matcher: rest[rest.length - 1],
+      modifiers: rest.slice(0, rest.length - 1),
+      type
+    };
+  }
+  if (chain.slice(0, chain.length - 1).some((n) => getParent(n)?.type !== "MemberExpression")) {
+    return null;
+  }
+  const parent = getParent(node);
+  if (parent?.type === "CallExpression" || parent?.type === "MemberExpression") {
+    return null;
+  }
+  return { ...parsedFnCall, type };
+}
+var isTypeOfFnCall = (context, node, types) => {
+  const call = parseFnCall(context, node);
+  return call !== null && types.includes(call.type);
+};
+
+// src/rules/no-hooks.ts
+var no_hooks_default = {
+  create(context) {
+    const options = {
+      allow: [],
+      ...context.options?.[0] ?? {}
+    };
+    return {
+      CallExpression(node) {
+        const call = parseFnCall(context, node);
+        if (call?.type === "hook" && !options.allow.includes(call.name)) {
+          context.report({
+            data: { hookName: call.name },
+            messageId: "unexpectedHook",
+            node
+          });
+        }
+      }
+    };
+  },
+  meta: {
+    docs: {
+      category: "Best Practices",
+      description: "Disallow setup and teardown hooks",
+      recommended: false,
+      url: "https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/no-hooks.md"
+    },
+    messages: {
+      unexpectedHook: "Unexpected '{{ hookName }}' hook"
+    },
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          allow: {
+            contains: ["beforeAll", "beforeEach", "afterAll", "afterEach"],
+            type: "array"
+          }
+        },
+        type: "object"
+      }
+    ],
+    type: "suggestion"
+  }
+};
+
 // src/rules/no-nested-step.ts
 function isStepCall(node) {
   const inner = node.type === "CallExpression" ? node.callee : node;
@@ -1237,7 +1415,7 @@ var getBlockType = (statement) => {
   const func = getParent(statement);
   if (!func) {
     throw new Error(
-      `Unexpected BlockStatement. No parent defined. - please file a github issue at https://github.com/jest-community/eslint-plugin-jest`
+      `Unexpected BlockStatement. No parent defined. - please file a github issue at https://github.com/playwright-community/eslint-plugin-playwright`
     );
   }
   if (func.type === "FunctionDeclaration") {
@@ -1245,7 +1423,7 @@ var getBlockType = (statement) => {
   }
   if (isFunction(func) && func.parent) {
     const expr = func.parent;
-    if (expr.type === "VariableDeclarator") {
+    if (expr.type === "VariableDeclarator" || expr.type === "MethodDefinition") {
       return "function";
     }
     if (expr.type === "CallExpression" && isDescribeCall(expr)) {
@@ -1294,6 +1472,9 @@ var no_standalone_expect_default = {
         if (isTestCall(context, node)) {
           callStack.push("test");
         }
+        if (isTestHook(context, node)) {
+          callStack.push("hook");
+        }
         if (node.callee.type === "TaggedTemplateExpression") {
           callStack.push("template");
         }
@@ -1311,7 +1492,7 @@ var no_standalone_expect_default = {
       category: "Best Practices",
       description: "Disallow using `expect` outside of `test` blocks",
       recommended: false,
-      url: "https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/prefer-to-contain.md"
+      url: "https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/no-standalone-expect.md"
     },
     fixable: "code",
     messages: {
@@ -1643,6 +1824,167 @@ var no_wait_for_timeout_default = {
   }
 };
 
+// src/rules/prefer-comparison-matcher.ts
+var isString = (node) => {
+  return isStringLiteral(node) || node.type === "TemplateLiteral";
+};
+var isComparingToString = (expression) => {
+  return isString(expression.left) || isString(expression.right);
+};
+var invertedOperators = {
+  "<": ">=",
+  "<=": ">",
+  ">": "<=",
+  ">=": "<"
+};
+var operatorMatcher = {
+  "<": "toBeLessThan",
+  "<=": "toBeLessThanOrEqual",
+  ">": "toBeGreaterThan",
+  ">=": "toBeGreaterThanOrEqual"
+};
+var determineMatcher = (operator, negated) => {
+  const op = negated ? invertedOperators[operator] : operator;
+  return operatorMatcher[op] ?? null;
+};
+var prefer_comparison_matcher_default = {
+  create(context) {
+    return {
+      CallExpression(node) {
+        const expectCall = parseExpectCall(context, node);
+        if (!expectCall || expectCall.args.length === 0)
+          return;
+        const { args, matcher } = expectCall;
+        const [comparison] = node.arguments;
+        const expectCallEnd = node.range[1];
+        const [matcherArg] = args;
+        if (comparison?.type !== "BinaryExpression" || isComparingToString(comparison) || !equalityMatchers.has(getStringValue(matcher)) || !isBooleanLiteral(matcherArg)) {
+          return;
+        }
+        const hasNot = expectCall.modifiers.some(
+          (node2) => getStringValue(node2) === "not"
+        );
+        const preferredMatcher = determineMatcher(
+          comparison.operator,
+          getRawValue(matcherArg) === hasNot.toString()
+        );
+        if (!preferredMatcher) {
+          return;
+        }
+        context.report({
+          data: { preferredMatcher },
+          fix(fixer) {
+            const [modifier] = expectCall.modifiers;
+            const modifierText = modifier && getStringValue(modifier) !== "not" ? `.${getStringValue(modifier)}` : "";
+            return [
+              // Replace the comparison argument with the left-hand side of the comparison
+              fixer.replaceText(
+                comparison,
+                context.sourceCode.getText(comparison.left)
+              ),
+              // Replace the current matcher & modifier with the preferred matcher
+              fixer.replaceTextRange(
+                [expectCallEnd, getParent(matcher).range[1]],
+                `${modifierText}.${preferredMatcher}`
+              ),
+              // Replace the matcher argument with the right-hand side of the comparison
+              fixer.replaceText(
+                matcherArg,
+                context.sourceCode.getText(comparison.right)
+              )
+            ];
+          },
+          messageId: "useToBeComparison",
+          node: matcher
+        });
+      }
+    };
+  },
+  meta: {
+    docs: {
+      category: "Best Practices",
+      description: "Suggest using the built-in comparison matchers",
+      recommended: false
+    },
+    fixable: "code",
+    messages: {
+      useToBeComparison: "Prefer using `{{ preferredMatcher }}` instead"
+    },
+    type: "suggestion"
+  }
+};
+
+// src/rules/prefer-equality-matcher.ts
+var prefer_equality_matcher_default = {
+  create(context) {
+    return {
+      CallExpression(node) {
+        const expectCall = parseExpectCall(context, node);
+        if (!expectCall || expectCall.args.length === 0)
+          return;
+        const { args, matcher } = expectCall;
+        const [comparison] = node.arguments;
+        const expectCallEnd = node.range[1];
+        const [matcherArg] = args;
+        if (comparison?.type !== "BinaryExpression" || comparison.operator !== "===" && comparison.operator !== "!==" || !equalityMatchers.has(getStringValue(matcher)) || !isBooleanLiteral(matcherArg)) {
+          return;
+        }
+        const matcherValue = getRawValue(matcherArg) === "true";
+        const [modifier] = expectCall.modifiers;
+        const hasNot = expectCall.modifiers.some(
+          (node2) => getStringValue(node2) === "not"
+        );
+        const addNotModifier = (comparison.operator === "!==" ? !matcherValue : matcherValue) === hasNot;
+        context.report({
+          messageId: "useEqualityMatcher",
+          node: matcher,
+          suggest: [...equalityMatchers.keys()].map((equalityMatcher) => ({
+            data: { matcher: equalityMatcher },
+            fix(fixer) {
+              let modifierText = modifier && getStringValue(modifier) !== "not" ? `.${getStringValue(modifier)}` : "";
+              if (addNotModifier) {
+                modifierText += `.not`;
+              }
+              return [
+                // replace the comparison argument with the left-hand side of the comparison
+                fixer.replaceText(
+                  comparison,
+                  context.sourceCode.getText(comparison.left)
+                ),
+                // replace the current matcher & modifier with the preferred matcher
+                fixer.replaceTextRange(
+                  [expectCallEnd, getParent(matcher).range[1]],
+                  `${modifierText}.${equalityMatcher}`
+                ),
+                // replace the matcher argument with the right-hand side of the comparison
+                fixer.replaceText(
+                  matcherArg,
+                  context.sourceCode.getText(comparison.right)
+                )
+              ];
+            },
+            messageId: "suggestEqualityMatcher"
+          }))
+        });
+      }
+    };
+  },
+  meta: {
+    docs: {
+      category: "Best Practices",
+      description: "Suggest using the built-in equality matchers",
+      recommended: false,
+      url: "https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/prefer-equality-matcher.md"
+    },
+    hasSuggestions: true,
+    messages: {
+      suggestEqualityMatcher: "Use `{{ matcher }}`",
+      useEqualityMatcher: "Prefer using one of the equality matchers instead"
+    },
+    type: "suggestion"
+  }
+};
+
 // src/rules/prefer-hooks-in-order.ts
 var HooksOrder = ["beforeAll", "beforeEach", "afterEach", "afterAll"];
 var prefer_hooks_in_order_default = {
@@ -1921,9 +2263,8 @@ var prefer_to_be_default = {
             notModifier
           );
         }
-        const argumentMatchers = ["toBe", "toEqual", "toStrictEqual"];
         const firstArg = expectCall.args[0];
-        if (!argumentMatchers.includes(expectCall.matcherName) || !firstArg) {
+        if (!equalityMatchers.has(expectCall.matcherName) || !firstArg) {
           return;
         }
         if (firstArg.type === "Literal" && firstArg.value === null) {
@@ -1963,7 +2304,6 @@ var prefer_to_be_default = {
 };
 
 // src/rules/prefer-to-contain.ts
-var matchers = /* @__PURE__ */ new Set(["toBe", "toEqual", "toStrictEqual"]);
 var isFixableIncludesCallExpression = (node) => node.type === "CallExpression" && node.callee.type === "MemberExpression" && isPropertyAccessor(node.callee, "includes") && node.arguments.length === 1 && node.arguments[0].type !== "SpreadElement";
 var prefer_to_contain_default = {
   create(context) {
@@ -1975,7 +2315,7 @@ var prefer_to_contain_default = {
         const { args, matcher, matcherName } = expectCall;
         const [includesCall] = node.arguments;
         const [matcherArg] = args;
-        if (!includesCall || matcherArg.type === "SpreadElement" || !matchers.has(matcherName) || !isBooleanLiteral(matcherArg) || !isFixableIncludesCallExpression(includesCall)) {
+        if (!includesCall || matcherArg.type === "SpreadElement" || !equalityMatchers.has(matcherName) || !isBooleanLiteral(matcherArg) || !isFixableIncludesCallExpression(includesCall)) {
           return;
         }
         const notModifier = expectCall.modifiers.find(
@@ -2033,13 +2373,12 @@ var prefer_to_contain_default = {
 };
 
 // src/rules/prefer-to-have-count.ts
-var matchers2 = /* @__PURE__ */ new Set(["toBe", "toEqual", "toStrictEqual"]);
 var prefer_to_have_count_default = {
   create(context) {
     return {
       CallExpression(node) {
         const expectCall = parseExpectCall(context, node);
-        if (!expectCall || !matchers2.has(expectCall.matcherName)) {
+        if (!expectCall || !equalityMatchers.has(expectCall.matcherName)) {
           return;
         }
         const [argument] = node.arguments;
@@ -2089,13 +2428,12 @@ var prefer_to_have_count_default = {
 };
 
 // src/rules/prefer-to-have-length.ts
-var lengthMatchers = /* @__PURE__ */ new Set(["toBe", "toEqual", "toStrictEqual"]);
 var prefer_to_have_length_default = {
   create(context) {
     return {
       CallExpression(node) {
         const expectCall = parseExpectCall(context, node);
-        if (!expectCall || !lengthMatchers.has(expectCall.matcherName)) {
+        if (!expectCall || !equalityMatchers.has(expectCall.matcherName)) {
           return;
         }
         const [argument] = node.arguments;
@@ -2290,6 +2628,86 @@ var prefer_web_first_assertions_default = {
   }
 };
 
+// src/rules/require-hook.ts
+var isNullOrUndefined = (node) => {
+  return node.type === "Literal" && node.value === null || isIdentifier(node, "undefined");
+};
+var shouldBeInHook = (context, node, allowedFunctionCalls = []) => {
+  switch (node.type) {
+    case "ExpressionStatement":
+      return shouldBeInHook(context, node.expression, allowedFunctionCalls);
+    case "CallExpression":
+      return !(parseFnCall(context, node) || allowedFunctionCalls.includes(getStringValue(node.callee)));
+    case "VariableDeclaration": {
+      if (node.kind === "const") {
+        return false;
+      }
+      return node.declarations.some(
+        ({ init }) => init != null && !isNullOrUndefined(init)
+      );
+    }
+    default:
+      return false;
+  }
+};
+var require_hook_default = {
+  create(context) {
+    const options = {
+      allowedFunctionCalls: [],
+      ...context.options?.[0] ?? {}
+    };
+    const checkBlockBody = (body) => {
+      for (const statement of body) {
+        if (shouldBeInHook(context, statement, options.allowedFunctionCalls)) {
+          context.report({
+            messageId: "useHook",
+            node: statement
+          });
+        }
+      }
+    };
+    return {
+      CallExpression(node) {
+        if (!isTypeOfFnCall(context, node, ["describe"]) || node.arguments.length < 2) {
+          return;
+        }
+        const [, testFn] = node.arguments;
+        if (!isFunction(testFn) || testFn.body.type !== "BlockStatement") {
+          return;
+        }
+        checkBlockBody(testFn.body.body);
+      },
+      Program(program) {
+        checkBlockBody(program.body);
+      }
+    };
+  },
+  meta: {
+    docs: {
+      category: "Best Practices",
+      description: "Require setup and teardown code to be within a hook",
+      recommended: false,
+      url: "https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/require-hook.md"
+    },
+    messages: {
+      useHook: "This should be done within a hook"
+    },
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          allowedFunctionCalls: {
+            items: { type: "string" },
+            type: "array"
+          }
+        },
+        type: "object"
+      }
+    ],
+    type: "suggestion"
+  }
+};
+
 // src/rules/require-soft-assertions.ts
 var require_soft_assertions_default = {
   create(context) {
@@ -2486,17 +2904,17 @@ var compileMatcherPattern = (matcherMaybeWithMessage) => {
   const [matcher, message] = Array.isArray(matcherMaybeWithMessage) ? matcherMaybeWithMessage : [matcherMaybeWithMessage];
   return [new RegExp(matcher, "u"), message];
 };
-var compileMatcherPatterns = (matchers3) => {
-  if (typeof matchers3 === "string" || Array.isArray(matchers3)) {
-    const compiledMatcher = compileMatcherPattern(matchers3);
+var compileMatcherPatterns = (matchers) => {
+  if (typeof matchers === "string" || Array.isArray(matchers)) {
+    const compiledMatcher = compileMatcherPattern(matchers);
     return {
       describe: compiledMatcher,
       test: compiledMatcher
     };
   }
   return {
-    describe: matchers3.describe ? compileMatcherPattern(matchers3.describe) : null,
-    test: matchers3.test ? compileMatcherPattern(matchers3.test) : null
+    describe: matchers.describe ? compileMatcherPattern(matchers.describe) : null,
+    test: matchers.test ? compileMatcherPattern(matchers.test) : null
   };
 };
 var MatcherAndMessageSchema = {
@@ -2700,6 +3118,7 @@ var index = {
     "no-focused-test": no_focused_test_default,
     "no-force-option": no_force_option_default,
     "no-get-by-title": no_get_by_title_default,
+    "no-hooks": no_hooks_default,
     "no-nested-step": no_nested_step_default,
     "no-networkidle": no_networkidle_default,
     "no-nth-methods": no_nth_methods_default,
@@ -2713,6 +3132,8 @@ var index = {
     "no-useless-not": no_useless_not_default,
     "no-wait-for-selector": no_wait_for_selector_default,
     "no-wait-for-timeout": no_wait_for_timeout_default,
+    "prefer-comparison-matcher": prefer_comparison_matcher_default,
+    "prefer-equality-matcher": prefer_equality_matcher_default,
     "prefer-hooks-in-order": prefer_hooks_in_order_default,
     "prefer-hooks-on-top": prefer_hooks_on_top_default,
     "prefer-lowercase-title": prefer_lowercase_title_default,
@@ -2722,6 +3143,7 @@ var index = {
     "prefer-to-have-count": prefer_to_have_count_default,
     "prefer-to-have-length": prefer_to_have_length_default,
     "prefer-web-first-assertions": prefer_web_first_assertions_default,
+    "require-hook": require_hook_default,
     "require-soft-assertions": require_soft_assertions_default,
     "require-top-level-describe": require_top_level_describe_default,
     "valid-expect": valid_expect_default,