eslint-plugin-playwright 0.17.0 → 0.19.0

package/README.md

@@ -101,7 +101,7 @@ under the `playwright` key. It supports the following settings:
   the presence of at least one assertion per test case. This allows such rules
   to recognise custom assertion functions as valid assertions. The global
   setting applies to all modules. The
-  [`expect-expect` rule accepts an option by the same name](./rules/expect-expect.md#additionalassertfunctionnames)
+  [`expect-expect` rule accepts an option by the same name](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/expect-expect.md#additionalassertfunctionnames)
   to enable per-module configuration (.e.g, for module-specific custom assert
   functions).
 
@@ -173,3 +173,4 @@ command line option.\
 |     |     |     | [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 |
 |     | 🔧  |     | [require-soft-assertions](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/require-soft-assertions.md)         | Require assertions to use `expect.soft()`                         |
 | ✔  |     |     | [valid-expect](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/valid-expect.md)                               | Enforce valid `expect()` usage                                    |
+| ✔  | 🔧  |     | [valid-title](https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/valid-title.md)                                 | Enforce valid titles                                              |

package/lib/index.js

@@ -28,6 +28,7 @@ const prefer_web_first_assertions_1 = require("./rules/prefer-web-first-assertio
 const require_soft_assertions_1 = require("./rules/require-soft-assertions");
 const require_top_level_describe_1 = require("./rules/require-top-level-describe");
 const valid_expect_1 = require("./rules/valid-expect");
+const valid_title_1 = require("./rules/valid-title");
 const index = {
     configs: {},
     rules: {
@@ -59,6 +60,7 @@ const index = {
         'require-soft-assertions': require_soft_assertions_1.default,
         'require-top-level-describe': require_top_level_describe_1.default,
         'valid-expect': valid_expect_1.default,
+        'valid-title': valid_title_1.default,
     },
 };
 const sharedConfig = {
@@ -81,6 +83,7 @@ const sharedConfig = {
         'playwright/no-wait-for-timeout': 'warn',
         'playwright/prefer-web-first-assertions': 'error',
         'playwright/valid-expect': 'error',
+        'playwright/valid-title': 'error',
     },
 };
 const legacyConfig = {

package/lib/rules/expect-expect.js

@@ -4,10 +4,11 @@ const ast_1 = require("../utils/ast");
 const misc_1 = require("../utils/misc");
 function isAssertionCall(node, additionalAssertFunctionNames) {
     return ((0, ast_1.isExpectCall)(node) ||
-        additionalAssertFunctionNames.find((name) => (0, ast_1.isIdentifier)(node.callee, name)));
+        additionalAssertFunctionNames.find((name) => (0, ast_1.dig)(node.callee, name)));
 }
 exports.default = {
     create(context) {
+        const sourceCode = context.sourceCode ?? context.getSourceCode();
         const unchecked = [];
         const additionalAssertFunctionNames = (0, misc_1.getAdditionalAssertFunctionNames)(context);
         function checkExpressions(nodes) {
@@ -21,11 +22,14 @@ exports.default = {
         }
         return {
             CallExpression(node) {
-                if ((0, ast_1.isTest)(node, ['fixme', 'only', 'skip'])) {
+                if ((0, ast_1.isTestCall)(node, ['fixme', 'only', 'skip'])) {
                     unchecked.push(node);
                 }
                 else if (isAssertionCall(node, additionalAssertFunctionNames)) {
-                    checkExpressions(context.getAncestors());
+                    const ancestors = sourceCode.getAncestors
+                        ? sourceCode.getAncestors(node)
+                        : context.getAncestors();
+                    checkExpressions(ancestors);
                 }
             },
             'Program:exit'() {

package/lib/rules/no-conditional-in-test.js

@@ -5,7 +5,7 @@ exports.default = {
     create(context) {
         function checkConditional(node) {
             const call = (0, ast_1.findParent)(node, 'CallExpression');
-            if (call && (0, ast_1.isTest)(call)) {
+            if (call && (0, ast_1.isTestCall)(call)) {
                 context.report({ messageId: 'conditionalInTest', node });
             }
         }

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

@@ -5,7 +5,7 @@ exports.default = {
     create(context) {
         return {
             CallExpression(node) {
-                if (((0, ast_1.isTest)(node) || (0, ast_1.isDescribeCall)(node)) &&
+                if (((0, ast_1.isTestCall)(node) || (0, ast_1.isDescribeCall)(node)) &&
                     node.callee.type === 'MemberExpression' &&
                     (0, ast_1.isPropertyAccessor)(node.callee, 'only')) {
                     const { callee } = node;

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

@@ -5,11 +5,18 @@ exports.default = {
     create(context) {
         return {
             CallExpression(node) {
+                const options = context.options[0] || {};
+                const allowConditional = !!options.allowConditional;
                 const { callee } = node;
                 if (((0, ast_1.isTestIdentifier)(callee) || (0, ast_1.isDescribeCall)(node)) &&
                     callee.type === 'MemberExpression' &&
                     (0, ast_1.isPropertyAccessor)(callee, 'skip')) {
-                    const isHook = (0, ast_1.isTest)(node) || (0, ast_1.isDescribeCall)(node);
+                    const isHook = (0, ast_1.isTestCall)(node) || (0, ast_1.isDescribeCall)(node);
+                    // If allowConditional is enabled and it's not a test/describe hook,
+                    // we ignore any `test.skip` calls that have no arguments.
+                    if (!isHook && allowConditional && node.arguments.length) {
+                        return;
+                    }
                     context.report({
                         messageId: 'noSkippedTest',
                         node: isHook ? callee.property : node,
@@ -43,6 +50,18 @@ exports.default = {
             noSkippedTest: 'Unexpected use of the `.skip()` annotation.',
             removeSkippedTestAnnotation: 'Remove the `.skip()` annotation.',
         },
+        schema: [
+            {
+                additionalProperties: false,
+                properties: {
+                    allowConditional: {
+                        default: false,
+                        type: 'boolean',
+                    },
+                },
+                type: 'object',
+            },
+        ],
         type: 'suggestion',
     },
 };

package/lib/rules/prefer-lowercase-title.js

@@ -1,9 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const ast_1 = require("../utils/ast");
-function isString(node) {
-    return node && ((0, ast_1.isStringLiteral)(node) || node.type === 'TemplateLiteral');
-}
 exports.default = {
     create(context) {
         const { allowedPrefixes, ignore, ignoreTopLevelDescribe } = {
@@ -17,7 +14,7 @@ exports.default = {
             CallExpression(node) {
                 const method = (0, ast_1.isDescribeCall)(node)
                     ? 'test.describe'
-                    : (0, ast_1.isTest)(node)
+                    : (0, ast_1.isTestCall)(node)
                         ? 'test'
                         : null;
                 if (method === 'test.describe') {
@@ -30,7 +27,7 @@ exports.default = {
                     return;
                 }
                 const [title] = node.arguments;
-                if (!isString(title)) {
+                if (!(0, ast_1.isStringNode)(title)) {
                     return;
                 }
                 const description = (0, ast_1.getStringValue)(title);

package/lib/rules/prefer-to-contain.js

@@ -28,7 +28,7 @@ exports.default = {
                 const notModifier = expectCall.modifiers.find((node) => (0, ast_1.getStringValue)(node) === 'not');
                 context.report({
                     fix(fixer) {
-                        const sourceCode = context.getSourceCode();
+                        const sourceCode = context.sourceCode ?? context.getSourceCode();
                         // We need to negate the expectation if the current expected
                         // value is itself negated by the "not" modifier
                         const addNotModifier = matcherArg.type === 'Literal' &&

package/lib/rules/require-top-level-describe.js

@@ -26,7 +26,7 @@ exports.default = {
                     }
                 }
                 else if (!describeCount) {
-                    if ((0, ast_1.isTest)(node)) {
+                    if ((0, ast_1.isTestCall)(node)) {
                         context.report({ messageId: 'unexpectedTest', node: node.callee });
                     }
                     else if ((0, ast_1.isTestHook)(node)) {

package/lib/rules/valid-title.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const ast_1 = require("../utils/ast");
+const doesBinaryExpressionContainStringNode = (binaryExp) => {
+    if ((0, ast_1.isStringNode)(binaryExp.right)) {
+        return true;
+    }
+    if (binaryExp.left.type === 'BinaryExpression') {
+        return doesBinaryExpressionContainStringNode(binaryExp.left);
+    }
+    return (0, ast_1.isStringNode)(binaryExp.left);
+};
+const quoteStringValue = (node) => node.type === 'TemplateLiteral'
+    ? `\`${node.quasis[0].value.raw}\``
+    : node.raw ?? '';
+const compileMatcherPattern = (matcherMaybeWithMessage) => {
+    const [matcher, message] = Array.isArray(matcherMaybeWithMessage)
+        ? matcherMaybeWithMessage
+        : [matcherMaybeWithMessage];
+    return [new RegExp(matcher, 'u'), message];
+};
+const compileMatcherPatterns = (matchers) => {
+    if (typeof matchers === 'string' || Array.isArray(matchers)) {
+        const compiledMatcher = compileMatcherPattern(matchers);
+        return {
+            describe: compiledMatcher,
+            test: compiledMatcher,
+        };
+    }
+    return {
+        describe: matchers.describe
+            ? compileMatcherPattern(matchers.describe)
+            : null,
+        test: matchers.test ? compileMatcherPattern(matchers.test) : null,
+    };
+};
+const MatcherAndMessageSchema = {
+    additionalItems: false,
+    items: { type: 'string' },
+    maxItems: 2,
+    minItems: 1,
+    type: 'array',
+};
+exports.default = {
+    create(context) {
+        const opts = context.options?.[0] ?? {};
+        const { disallowedWords = [], ignoreSpaces = false, ignoreTypeOfDescribeName = false, ignoreTypeOfTestName = false, mustMatch, mustNotMatch, } = opts;
+        const disallowedWordsRegexp = new RegExp(`\\b(${disallowedWords.join('|')})\\b`, 'iu');
+        const mustNotMatchPatterns = compileMatcherPatterns(mustNotMatch ?? {});
+        const mustMatchPatterns = compileMatcherPatterns(mustMatch ?? {});
+        return {
+            CallExpression(node) {
+                const isDescribe = (0, ast_1.isDescribeCall)(node);
+                const isTest = (0, ast_1.isTestCall)(node);
+                if (!isDescribe && !isTest) {
+                    return;
+                }
+                const [argument] = node.arguments;
+                if (!argument) {
+                    return;
+                }
+                if (!(0, ast_1.isStringNode)(argument)) {
+                    if (argument.type === 'BinaryExpression' &&
+                        doesBinaryExpressionContainStringNode(argument)) {
+                        return;
+                    }
+                    if (!((isDescribe && ignoreTypeOfDescribeName) ||
+                        (isTest && ignoreTypeOfTestName)) &&
+                        argument.type !== 'TemplateLiteral') {
+                        context.report({
+                            loc: argument.loc,
+                            messageId: 'titleMustBeString',
+                        });
+                    }
+                    return;
+                }
+                const title = (0, ast_1.getStringValue)(argument);
+                const functionName = isDescribe ? 'describe' : 'test';
+                if (!title) {
+                    context.report({
+                        data: { functionName },
+                        messageId: 'emptyTitle',
+                        node,
+                    });
+                    return;
+                }
+                if (disallowedWords.length > 0) {
+                    const disallowedMatch = disallowedWordsRegexp.exec(title);
+                    if (disallowedMatch) {
+                        context.report({
+                            data: { word: disallowedMatch[1] },
+                            messageId: 'disallowedWord',
+                            node: argument,
+                        });
+                        return;
+                    }
+                }
+                if (ignoreSpaces === false && title.trim().length !== title.length) {
+                    context.report({
+                        fix: (fixer) => [
+                            fixer.replaceTextRange(argument.range, quoteStringValue(argument)
+                                .replace(/^([`'"]) +?/u, '$1')
+                                .replace(/ +?([`'"])$/u, '$1')),
+                        ],
+                        messageId: 'accidentalSpace',
+                        node: argument,
+                    });
+                }
+                const [firstWord] = title.split(' ');
+                if (firstWord.toLowerCase() === functionName) {
+                    context.report({
+                        fix: (fixer) => [
+                            fixer.replaceTextRange(argument.range, quoteStringValue(argument).replace(/^([`'"]).+? /u, '$1')),
+                        ],
+                        messageId: 'duplicatePrefix',
+                        node: argument,
+                    });
+                }
+                const [mustNotMatchPattern, mustNotMatchMessage] = mustNotMatchPatterns[functionName] ?? [];
+                if (mustNotMatchPattern && mustNotMatchPattern.test(title)) {
+                    context.report({
+                        data: {
+                            functionName,
+                            message: mustNotMatchMessage ?? '',
+                            pattern: String(mustNotMatchPattern),
+                        },
+                        messageId: mustNotMatchMessage
+                            ? 'mustNotMatchCustom'
+                            : 'mustNotMatch',
+                        node: argument,
+                    });
+                    return;
+                }
+                const [mustMatchPattern, mustMatchMessage] = mustMatchPatterns[functionName] ?? [];
+                if (mustMatchPattern && !mustMatchPattern.test(title)) {
+                    context.report({
+                        data: {
+                            functionName,
+                            message: mustMatchMessage ?? '',
+                            pattern: String(mustMatchPattern),
+                        },
+                        messageId: mustMatchMessage ? 'mustMatchCustom' : 'mustMatch',
+                        node: argument,
+                    });
+                    return;
+                }
+            },
+        };
+    },
+    meta: {
+        docs: {
+            category: 'Best Practices',
+            description: 'Enforce valid titles',
+            recommended: true,
+            url: 'https://github.com/playwright-community/eslint-plugin-playwright/tree/main/docs/rules/valid-title.md',
+        },
+        fixable: 'code',
+        messages: {
+            accidentalSpace: 'should not have leading or trailing spaces',
+            disallowedWord: '"{{ word }}" is not allowed in test titles',
+            duplicatePrefix: 'should not have duplicate prefix',
+            emptyTitle: '{{ functionName }} should not have an empty title',
+            mustMatch: '{{ functionName }} should match {{ pattern }}',
+            mustMatchCustom: '{{ message }}',
+            mustNotMatch: '{{ functionName }} should not match {{ pattern }}',
+            mustNotMatchCustom: '{{ message }}',
+            titleMustBeString: 'Title must be a string',
+        },
+        schema: [
+            {
+                additionalProperties: false,
+                patternProperties: {
+                    [/^must(?:Not)?Match$/u.source]: {
+                        oneOf: [
+                            { type: 'string' },
+                            MatcherAndMessageSchema,
+                            {
+                                additionalProperties: {
+                                    oneOf: [{ type: 'string' }, MatcherAndMessageSchema],
+                                },
+                                propertyNames: { enum: ['describe', 'test'] },
+                                type: 'object',
+                            },
+                        ],
+                    },
+                },
+                properties: {
+                    disallowedWords: {
+                        items: { type: 'string' },
+                        type: 'array',
+                    },
+                    ignoreSpaces: {
+                        default: false,
+                        type: 'boolean',
+                    },
+                    ignoreTypeOfDescribeName: {
+                        default: false,
+                        type: 'boolean',
+                    },
+                    ignoreTypeOfTestName: {
+                        default: false,
+                        type: 'boolean',
+                    },
+                },
+                type: 'object',
+            },
+        ],
+        type: 'suggestion',
+    },
+};

package/lib/utils/ast.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isPageMethod = exports.getMatchers = exports.isExpectCall = exports.getExpectType = exports.isTestHook = exports.isTest = exports.findParent = exports.isDescribeCall = exports.isTestIdentifier = exports.isPropertyAccessor = exports.isBooleanLiteral = exports.isStringLiteral = exports.isIdentifier = exports.getRawValue = exports.getStringValue = void 0;
+exports.isPageMethod = exports.dig = exports.getMatchers = exports.isExpectCall = exports.getExpectType = exports.isTestHook = exports.isTestCall = exports.findParent = exports.isDescribeCall = exports.isTestIdentifier = exports.isPropertyAccessor = exports.isStringNode = exports.isBooleanLiteral = exports.isStringLiteral = exports.isIdentifier = exports.getRawValue = exports.getStringValue = void 0;
 function getStringValue(node) {
     if (!node)
         return '';
@@ -28,6 +28,9 @@ function isLiteral(node, type, value) {
             ? typeof node.value === type
             : node.value === value));
 }
+const isTemplateLiteral = (node, value) => node.type === 'TemplateLiteral' &&
+    node.quasis.length === 1 && // bail out if not simple
+    (value === undefined || node.quasis[0].value.raw === value);
 function isStringLiteral(node, value) {
     return isLiteral(node, 'string', value);
 }
@@ -36,6 +39,10 @@ function isBooleanLiteral(node, value) {
     return isLiteral(node, 'boolean', value);
 }
 exports.isBooleanLiteral = isBooleanLiteral;
+function isStringNode(node) {
+    return node && (isStringLiteral(node) || isTemplateLiteral(node));
+}
+exports.isStringNode = isStringNode;
 function isPropertyAccessor(node, name) {
     return getStringValue(node.property) === name;
 }
@@ -76,7 +83,7 @@ function findParent(node, type) {
         : findParent(node.parent, type);
 }
 exports.findParent = findParent;
-function isTest(node, modifiers) {
+function isTestCall(node, modifiers) {
     return (isTestIdentifier(node.callee) &&
         !isDescribeCall(node) &&
         (node.callee.type !== 'MemberExpression' ||
@@ -85,7 +92,7 @@ function isTest(node, modifiers) {
         node.arguments.length === 2 &&
         ['ArrowFunctionExpression', 'FunctionExpression'].includes(node.arguments[1].type));
 }
-exports.isTest = isTest;
+exports.isTestCall = isTestCall;
 const testHooks = new Set(['afterAll', 'afterEach', 'beforeAll', 'beforeEach']);
 function isTestHook(node) {
     return (node.callee.type === 'MemberExpression' &&
@@ -132,6 +139,7 @@ function dig(node, identifier) {
                 ? isIdentifier(node, identifier)
                 : false;
 }
+exports.dig = dig;
 function isPageMethod(node, name) {
     return (node.callee.type === 'MemberExpression' &&
         dig(node.callee.object, /(^(page|frame)|(Page|Frame)$)/) &&

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "eslint-plugin-playwright",
   "description": "ESLint plugin for Playwright testing.",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "packageManager": "pnpm@8.8.0",
   "main": "lib/index.js",
   "repository": "https://github.com/playwright-community/eslint-plugin-playwright",