feat: Add require-tags rule

Fixes #401

Author: mskelton

AGENTS.md

@@ -178,8 +178,7 @@ runRuleTester('{rule-name}', rule, {
 
 ### Test Utilities
 
-- `javascript` template literal for multi-line code
-- `typescript` template literal for TypeScript code
+- `dedent` template literal for multi-line code
 - `test()` wrapper for common test patterns
 - Global alias testing with settings
 

README.md

@@ -168,6 +168,7 @@ CLI option\
 | [prefer-web-first-assertions](https://github.com/mskelton/eslint-plugin-playwright/tree/main/docs/rules/prefer-web-first-assertions.md)             | Suggest using web first assertions                                 | ✅  | 🔧  |     |
 | [require-hook](https://github.com/mskelton/eslint-plugin-playwright/tree/main/docs/rules/require-hook.md)                                           | Require setup and teardown code to be within a hook                |     |     |     |
 | [require-soft-assertions](https://github.com/mskelton/eslint-plugin-playwright/tree/main/docs/rules/require-soft-assertions.md)                     | Require assertions to use `expect.soft()`                          |     | 🔧  |     |
+| [require-tags](https://github.com/mskelton/eslint-plugin-playwright/tree/main/docs/rules/require-tags.md)                                           | Require test blocks to have tags                                   |     |     |     |
 | [require-to-pass-timeout](https://github.com/mskelton/eslint-plugin-playwright/tree/main/docs/rules/require-to-pass-timeout.md)                     | Require a timeout option for `toPass()`                            |     |     |     |
 | [require-to-throw-message](https://github.com/mskelton/eslint-plugin-playwright/tree/main/docs/rules/require-to-throw-message.md)                   | Require a message for `toThrow()`                                  |     |     |     |
 | [require-top-level-describe](https://github.com/mskelton/eslint-plugin-playwright/tree/main/docs/rules/require-top-level-describe.md)               | Require test cases and hooks to be inside a `test.describe` block  |     |     |     |

docs/rules/missing-playwright-await.md

@@ -40,10 +40,7 @@ const responsePromise = page.waitForResponse('https://example.com/api')
 await page.locator('button').click()
 await responsePromise
 
-await Promise.all([
-  page.locator('button').click(),
-  page.waitForResponse('https://example.com/api'),
-])
+await Promise.all([page.locator('button').click(), page.waitForResponse('https://example.com/api')])
 ```
 
 ## Options

docs/rules/require-tags.md

@@ -0,0 +1,43 @@
+# Require test blocks to have tags (`require-tags`)
+
+This rule enforces that all test blocks have at least one tag.
+
+Tags can be specified in the test title (e.g., `@e2e my test`) or in the
+options object (e.g., `{ tag: '@e2e' }`). Tests also inherit tags from parent
+`describe` blocks.
+
+## Rule details
+
+This rule triggers a warning if a test block does not have any tags and none of
+its parent `describe` blocks have tags.
+
+The following patterns are considered warnings:
+
+```js
+test('my test', async ({ page }) => {})
+
+test('my test', { timeout: 5000 }, async ({ page }) => {})
+
+test.describe('my suite', () => {
+  test('my test', async ({ page }) => {})
+})
+```
+
+The following patterns are **not** considered warnings:
+
+```js
+test('@e2e my test', async ({ page }) => {})
+
+test('my test', { tag: '@e2e' }, async ({ page }) => {})
+
+test('my test', { tag: ['@e2e', '@smoke'] }, async ({ page }) => {})
+
+// Tests inherit tags from parent describe blocks
+test.describe('@suite my suite', () => {
+  test('my test', async ({ page }) => {})
+})
+
+test.describe('my suite', { tag: '@e2e' }, () => {
+  test('my test', async ({ page }) => {})
+})
+```

src/plugin.ts

@@ -48,6 +48,7 @@ import preferToHaveLength from './rules/prefer-to-have-length.js'
 import preferWebFirstAssertions from './rules/prefer-web-first-assertions.js'
 import requireHook from './rules/require-hook.js'
 import requireSoftAssertions from './rules/require-soft-assertions.js'
+import requireTags from './rules/require-tags.js'
 import requireToPassTimeout from './rules/require-to-pass-timeout.js'
 import requireToThrowMessage from './rules/require-to-throw-message.js'
 import requireTopLevelDescribe from './rules/require-top-level-describe.js'
@@ -109,6 +110,7 @@ export const plugin = {
     'prefer-web-first-assertions': preferWebFirstAssertions,
     'require-hook': requireHook,
     'require-soft-assertions': requireSoftAssertions,
+    'require-tags': requireTags,
     'require-to-pass-timeout': requireToPassTimeout,
     'require-to-throw-message': requireToThrowMessage,
     'require-top-level-describe': requireTopLevelDescribe,

src/rules/require-tags.test.ts

@@ -0,0 +1,161 @@
+import dedent from 'dedent'
+import { runRuleTester } from '../utils/rule-tester.js'
+import requireTags from './require-tags.js'
+
+runRuleTester('require-tags', requireTags, {
+  invalid: [
+    // Test without any tags
+    {
+      code: "test('my test', async ({ page }) => {})",
+      errors: [{ data: { title: 'my test' }, messageId: 'missingTag' }],
+    },
+    // Test with options but no tag
+    {
+      code: "test('my test', { timeout: 5000 }, async ({ page }) => {})",
+      errors: [{ data: { title: 'my test' }, messageId: 'missingTag' }],
+    },
+    // test.skip without tags
+    {
+      code: "test.skip('my test', async ({ page }) => {})",
+      errors: [{ data: { title: 'my test' }, messageId: 'missingTag' }],
+    },
+    // test.fixme without tags
+    {
+      code: "test.fixme('my test', async ({ page }) => {})",
+      errors: [{ data: { title: 'my test' }, messageId: 'missingTag' }],
+    },
+    // test.only without tags
+    {
+      code: "test.only('my test', async ({ page }) => {})",
+      errors: [{ data: { title: 'my test' }, messageId: 'missingTag' }],
+    },
+    // Test inside describe without tags (describe has no tags either)
+    {
+      code: dedent`
+        test.describe('my suite', () => {
+          test('my test', async ({ page }) => {})
+        })
+      `,
+      errors: [{ data: { title: 'my test' }, messageId: 'missingTag' }],
+    },
+    // Nested describes - test with no tags and no parent tags
+    {
+      code: dedent`
+        test.describe('outer', () => {
+          test.describe('inner', () => {
+            test('my test', async ({ page }) => {})
+          })
+        })
+      `,
+      errors: [{ data: { title: 'my test' }, messageId: 'missingTag' }],
+    },
+  ],
+  valid: [
+    // Test with tag in options
+    {
+      code: "test('my test', { tag: '@e2e' }, async ({ page }) => {})",
+    },
+    // Test with array of tags
+    {
+      code: "test('my test', { tag: ['@e2e', '@login'] }, async ({ page }) => {})",
+    },
+    // Test with tag in title
+    {
+      code: "test('@e2e my test', async ({ page }) => {})",
+    },
+    // Test with multiple tags in title
+    {
+      code: "test('@e2e @login my test', async ({ page }) => {})",
+    },
+    // Test with tag at end of title
+    {
+      code: "test('my test @e2e', async ({ page }) => {})",
+    },
+    // test.skip with tag
+    {
+      code: "test.skip('@e2e my test', async ({ page }) => {})",
+    },
+    {
+      code: "test.skip('my test', { tag: '@e2e' }, async ({ page }) => {})",
+    },
+    // test.fixme with tag
+    {
+      code: "test.fixme('@e2e my test', async ({ page }) => {})",
+    },
+    {
+      code: "test.fixme('my test', { tag: '@e2e' }, async ({ page }) => {})",
+    },
+    // test.only with tag
+    {
+      code: "test.only('@e2e my test', async ({ page }) => {})",
+    },
+    {
+      code: "test.only('my test', { tag: '@e2e' }, async ({ page }) => {})",
+    },
+    // Test inheriting tag from parent describe (in title)
+    {
+      code: dedent`
+        test.describe('@suite my suite', () => {
+          test('my test', async ({ page }) => {})
+        })
+      `,
+    },
+    // Test inheriting tag from parent describe (in options)
+    {
+      code: dedent`
+        test.describe('my suite', { tag: '@e2e' }, () => {
+          test('my test', async ({ page }) => {})
+        })
+      `,
+    },
+    // Test inheriting tag from nested parent describe
+    {
+      code: dedent`
+        test.describe('@suite outer', () => {
+          test.describe('inner', () => {
+            test('my test', async ({ page }) => {})
+          })
+        })
+      `,
+    },
+    {
+      code: dedent`
+        test.describe('outer', { tag: '@e2e' }, () => {
+          test.describe('inner', () => {
+            test('my test', async ({ page }) => {})
+          })
+        })
+      `,
+    },
+    // Test inheriting tag from inner describe when outer has none
+    {
+      code: dedent`
+        test.describe('outer', () => {
+          test.describe('@suite inner', () => {
+            test('my test', async ({ page }) => {})
+          })
+        })
+      `,
+    },
+    // Test with its own tag ignores parent inheritance check
+    {
+      code: dedent`
+        test.describe('my suite', () => {
+          test('@e2e my test', async ({ page }) => {})
+        })
+      `,
+    },
+    // describe blocks themselves should not be flagged
+    {
+      code: "test.describe('my suite', () => {})",
+    },
+    // step blocks should not be flagged
+    {
+      code: dedent`
+        test('@e2e my test', async ({ page }) => {
+          await test.step('my step', async () => {})
+        })
+      `,
+    },
+  ],
+})

src/rules/require-tags.ts

@@ -0,0 +1,75 @@
+import type * as ESTree from 'estree'
+import { createRule } from '../utils/createRule.js'
+import { isTypeOfFnCall, parseFnCall } from '../utils/parseFnCall.js'
+
+const tagRegex = /@[\S]+/
+
+function hasTagInOptions(node: ESTree.CallExpression): boolean {
+  const options = node.arguments[1]
+  if (!options || options.type !== 'ObjectExpression') {
+    return false
+  }
+
+  return options.properties.some(
+    (prop) => prop.type === 'Property' && prop.key.type === 'Identifier' && prop.key.name === 'tag',
+  )
+}
+
+function hasTagInTitle(node: ESTree.CallExpression): boolean {
+  const title = node.arguments[0]
+  if (!title || title.type !== 'Literal' || typeof title.value !== 'string') {
+    return false
+  }
+
+  return tagRegex.test(title.value)
+}
+
+function hasTags(node: ESTree.CallExpression): boolean {
+  return hasTagInTitle(node) || hasTagInOptions(node)
+}
+
+export default createRule({
+  create(context) {
+    const describeStack: boolean[] = []
+
+    return {
+      'CallExpression'(node) {
+        const call = parseFnCall(context, node)
+        if (!call) {
+          return
+        }
+
+        if (call.type === 'describe') {
+          describeStack.push(hasTags(node) || !!describeStack.at(-1))
+          return
+        }
+
+        if (call.type === 'test') {
+          if (hasTags(node) || !!describeStack.at(-1)) {
+            return
+          }
+
+          context.report({ messageId: 'missingTag', node })
+        }
+      },
+      'CallExpression:exit'(node) {
+        if (isTypeOfFnCall(context, node, ['describe'])) {
+          describeStack.pop()
+        }
+      },
+    }
+  },
+  meta: {
+    docs: {
+      category: 'Best Practices',
+      description: 'Require test blocks to have tags',
+      recommended: false,
+      url: 'https://github.com/mskelton/eslint-plugin-playwright/tree/main/docs/rules/require-tags.md',
+    },
+    messages: {
+      missingTag: 'Test must have at least one tag',
+    },
+    schema: [],
+    type: 'suggestion',
+  },
+})