eslint-plugin-test-governance 0.12.1 → 0.13.0

package/CHANGELOG.md

@@ -6,6 +6,20 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-11-05
+
+### Added
+
+- `requireReasonForConditional`, off by default: a conditional skip, such as `test.skip(isMobile)` or
+  `if (isWeekend) this.skip()`, needs a reason but no ticket. A comment above it or at the end of its line, above
+  the `if` around it, or above its hook, step or test counts, and so does the reason the call takes where the runner
+  has one, as Playwright's `test.skip(condition, 'why')`, Vitest's `context.skip(condition, 'why')`, node:test's
+  `t.skip('why')` and `{ skip: isWindows && 'why' }`, and Jasmine's `pending('why')`. `require-ticket` reports the
+  skips that give none.
+- `knownTags`, such as `['@smoke', '@regression']`: `no-conflicting-states` gives these tags the case and typo
+  checks state tags get, so `@Smoke` is fixed to `@smoke` and `@smok` is reported. A listed tag is never reported as
+  a typo of a state tag.
+
 ## [0.12.1] - 2026-11-04
 
 ### Fixed
@@ -493,7 +507,8 @@ First release.
 - Support for ESLint 9 and 10 flat config, JavaScript and TypeScript test files, `.extend()`
   fixtures, describe blocks, runtime skips and tags in titles or the `tag` option.
 
-[Unreleased]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.12.1...HEAD
+[Unreleased]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.13.0...HEAD
+[0.13.0]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.12.1...v0.13.0
 [0.12.1]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.12.0...v0.12.1
 [0.12.0]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.11.1...v0.12.0
 [0.11.1]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.11.0...v0.11.1

package/README.md

@@ -20,6 +20,10 @@ Without the comment, `test-governance/require-ticket` fails the lint. When the t
 skip removed, `no-orphaned-marker` flags the leftover comment. The markers are plain
 comments, so `grep -rn "SKIP:" tests/` lists every disabled test and its ticket.
 
+The same check covers tests commented out by hand, `FIXME` and `TODO` comments in test files, and, once
+turned on, retried tests. The ticket can also go in the description of an `eslint-disable` comment, or in
+a Playwright annotation or Vitest `meta`, which reach the test report.
+
 > **Status:** early release (0.x). Options may still change before 1.0. Coming from 0.5?
 > [Upgrading to 0.6](docs/upgrading.md#upgrading-to-06) shows what to change.
 
@@ -148,8 +152,9 @@ turn on the same rules. What puts a test in a state in each framework:
 | `fixme` (`// FIXME:`)                  | `test.fixme(...)`, `test.describe.fixme`, `testInfo.fixme()`                                                        |                                                                      |                                                                                                                                                                                            |                                                                                                                                                                           |                                          |             |                                                                                                                                                                                                   |                                                                                                                          |
 | `fail` (`// FAIL:`), off by default    | `test.fail(...)`, `testInfo.fail()`                                                                                 | `test.failing`                                                       | `test.fails`, `{ fails: true }`                                                                                                                                                            |                                                                                                                                                                           |                                          |             | `test.expectFailure`, `expectFailure()`, `{ expectFailure }`                                                                                                                                      |                                                                                                                          |
 | `slow` (`// SLOW:`), off by default    | `test.slow()`, `testInfo.slow()`                                                                                    |                                                                      |                                                                                                                                                                                            |                                                                                                                                                                           |                                          |             |                                                                                                                                                                                                   |                                                                                                                          |
+| `retry` (`// RETRY:`), off by default  | `test.describe.configure({ retries })`                                                                              | `jest.retryTimes()`                                                  | `{ retry }`                                                                                                                                                                                | `this.retries()` in a describe, test or hook written as a `function`                                                                                                      | as Mocha, and `{ retries }`              | as Mocha    |                                                                                                                                                                                                   |                                                                                                                          |
 | conditional skip, no ticket by default | `test.skip(condition)`, `if (...) test.skip()`, `(condition ? test.skip : test)(...)`                               | `(condition ? it.skip : it)(...)`                                    | `skipIf(condition)`, `runIf(condition)`, `{ skip: condition }`, `context.skip(condition)`, `if (...) context.skip()`, `(condition ? it.skip : it)(...)`                                    | `if (...) this.skip()`, `(condition ? it.skip : it)(...)`                                                                                                                 | as Mocha, and `{ browser: '!webkit' }`   | as Mocha    | `{ skip: condition }`, `{ todo: condition }`, `if (...) t.skip()`, `(condition ? it.skip : it)(...)`                                                                                              | `if (...) pending()`, `(condition ? xit : it)(...)`                                                                      |
-| tags such as `@new` (`// NEW:`)        | the title, `{ tag }`                                                                                                | the title                                                            | the title, `{ tags }`, where `'new'` and `'@new'` both mean `@new`                                                                                                                         | the title                                                                                                                                                                 | the title, `{ tags }` from @cypress/grep | the title   | the title                                                                                                                                                                                         | the title                                                                                                                |
+| tags such as `@new` (`// NEW:`)        | the title, `{ tag }`                                                                                                | the title                                                            | the title, `{ tags }`, where `'new'` and `'@new'` both mean `@new`                                                                                                                         | the title                                                                                                                                                                 | the title, `{ tags }` from @cypress/grep | the title   | the title, `{ tags }`, as in Vitest                                                                                                                                                               | the title                                                                                                                |
 
 Table-driven tests count too: `test.skip.each(table)(...)`, `describe.skip.each` and Vitest's `.for`.
 A test or describe whose function a condition picks, as in `(isMobile ? test.skip : test)('title', fn)`,
@@ -200,7 +205,7 @@ condition. A function or variable of your own called `pending` is not Jasmine's.
 | [marker-matches-state](docs/rules/marker-matches-state.md)                                     | Require the marker keyword to match the test's state                              | 🌲 🌼 🃏 ☕ 🟢 🎭 ⚡ 🤖 |                         |     | 💡  |
 | [no-conflicting-states](docs/rules/no-conflicting-states.md)                                   | Disallow state tags that contradict each other, differ in case or look like typos |                         | 🌲 🌼 🃏 ☕ 🟢 🎭 ⚡ 🤖 | 🔧  |     |
 | [no-orphaned-marker](docs/rules/no-orphaned-marker.md)                                         | Disallow marker comments that no longer match a test state                        | 🌲 🌼 🃏 ☕ 🟢 🎭 ⚡ 🤖 |                         |     | 💡  |
-| [require-ticket](docs/rules/require-ticket.md)                                                 | Require a ticket marker comment above skipped, fixme and tagged tests             | 🌲 🌼 🃏 ☕ 🟢 🎭 ⚡ 🤖 |                         |     | 💡  |
+| [require-ticket](docs/rules/require-ticket.md)                                                 | Require a ticket for skipped, fixme, todo, retried and tagged tests               | 🌲 🌼 🃏 ☕ 🟢 🎭 ⚡ 🤖 |                         |     | 💡  |
 | [require-ticket-for-commented-out-tests](docs/rules/require-ticket-for-commented-out-tests.md) | Require a ticket marker on commented-out tests                                    |                         | 🌲 🌼 🃏 ☕ 🟢 🎭 ⚡ 🤖 |     | 💡  |
 | [require-ticket-in-comments](docs/rules/require-ticket-in-comments.md)                         | Require FIXME and TODO comments in test files to start with a ticket              | 🌲 🌼 🃏 ☕ 🟢 🎭 ⚡ 🤖 |                         |     | 💡  |
 
@@ -214,7 +219,7 @@ The defaults follow how most teams already work, so each framework config is use
 | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | States that need a ticket                                                                                 | `skip`, `fixme`; in the other frameworks `skip`, `todo`                                             | Every team skips tests. Chromium DevTools, GitLab and Slack all require a bug link on disabled tests.                                                                        |
 | `@new`, `@quarantined`                                                                                    | off; `lifecycleTags: true` turns both on                                                            | A promotion workflow is not universal. Teams that say `@flaky` instead [rename the tag](#tag-names).                                                                         |
-| Conditional skips (`test.skip(browserName === 'webkit', ...)`, `if (...) test.skip()`, a skip in `catch`) | no ticket needed                                                                                    | These are usually permanent platform limits, not bugs. `requireTicketForConditional: true` changes this.                                                                     |
+| Conditional skips (`test.skip(browserName === 'webkit', ...)`, `if (...) test.skip()`, a skip in `catch`) | no ticket needed                                                                                    | These are usually permanent platform limits, not bugs. `requireTicketForConditional: true` asks for a ticket, `requireReasonForConditional: true` for a reason.              |
 | `test.fail`, `test.slow`, Jest's `test.failing`, Vitest's `test.fails`                                    | off                                                                                                 | They don't remove coverage. Turn them on with `states: { fail: true, slow: true }`.                                                                                          |
 | Retries: `describe.configure({ retries })`, `jest.retryTimes()`, `retry`, `this.retries()`                | off                                                                                                 | Retries hide flaky tests. `states: { retry: true }` needs a ticket wherever tests retry, even only on CI.                                                                    |
 | Marker format                                                                                             | `// SKIP: TRADE-123` or `// SKIP: TRADE-123, TRADE-124`                                             | Uppercase keyword and colon, like `TODO:`. Easy to grep.                                                                                                                     |
@@ -241,7 +246,9 @@ and markers. To turn a rule off, set it to `'off'` as usual.
 | `lifecycleTags`               | `boolean`                                                                                                 | `false`                           | Turns on the `new` (`@new`) and `quarantined` (`@quarantined`) states.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `states`                      | `{ [state]: boolean \| { enabled?, tag?, marker?, ticket? } }`                                            | `skip`, `fixme` and `todo` on     | Turns built-in states (`skip`, `fixme`, `fail`, `slow`, `todo`, `retry`, `new`, `quarantined`) on or off, renames their tag or marker, or gives them their own ticket format. `fail`, `slow` and `retry` are off by default; a setting for `new` or `quarantined` here wins over `lifecycleTags`. Only `new` and `quarantined` have a tag to rename; see [Tag names](#tag-names). `fixme` and `slow` exist only in Playwright, `todo` in every framework but Playwright, `fail` in Playwright, Jest, Vitest and node:test, and `retry` in every framework but node:test and Jasmine, so turning one on elsewhere has no effect. |
 | `customStates`                | `{ [name]: { when, marker, ticket? } }`                                                                   | `{}`                              | Adds a state for a tag, e.g. `{ 'needs-data': { when: '@needs-data', marker: 'NEEDS-DATA' } }`. `when` is a tag and `marker` an uppercase keyword; neither can be shared with another state.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `knownTags`                   | `string[]`                                                                                                | `[]`                              | Your team's other tags, such as `['@smoke', '@regression']`, written with the `@`. `no-conflicting-states` reports them in the wrong case or misspelled, as it does state tags, and never reports a listed tag as a typo of a state tag.                                                                                                                                                                                                                                                                                                                                                                                        |
 | `requireTicketForConditional` | `boolean`                                                                                                 | `false`                           | Require a ticket for conditional skips too: `test.skip(condition, ...)`, `if (...) test.skip()`, `(condition ? test.skip : test)(...)`, a skip in a `catch` block, after other code in a `try` block with a `catch`, or after an early `return` or `throw`.                                                                                                                                                                                                                                                                                                                                                                     |
+| `requireReasonForConditional` | `boolean`                                                                                                 | `false`                           | Require a reason, but no ticket, for conditional skips: a comment above the skip or at the end of its line, above the `if` around it or above its hook, step or test, or the reason the call takes, as `test.skip(condition, 'why')`. See [require-ticket](docs/rules/require-ticket.md#reasons-for-conditional-skips).                                                                                                                                                                                                                                                                                                         |
 | `allowBlankLine`              | `boolean`                                                                                                 | `false`                           | Let blank lines separate a marker from its test.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `allowNotes`                  | `boolean`                                                                                                 | `false`                           | Allow free text after the tickets, e.g. `// SKIP: TRADE-123 flaky on CI`. Applies to markers and to `FIXME` / `TODO` comments.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `comments`                    | `false \| { keywords?: string[] }`                                                                        | `{ keywords: ['FIXME', 'TODO'] }` | Comment keywords that must start with a ticket anywhere in a test file, e.g. `// TODO: TRADE-123`. Your keywords replace the default ones. `false` allows free-form comments.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
@@ -471,10 +478,9 @@ The [Frameworks](#frameworks) table lists what each framework's tests can do. In
 Not covered in this version: tests generated in loops with dynamic titles, and tags or details imported
 from other modules (see `reportUnreadableTags`), fixtures imported from other modules under a name not in
 `testFunctions`, a Vitest test with only a title, which Vitest runs as a todo but which looks the same as a
-helper called `test`, Playwright annotations as markers, Cypress tests skipped with @cypress/skip-test's
-`skipOn()` and `onlyOn()`, `node:test`'s experimental `tags` option and `getTestContext()`, Jasmine's
-`pending()` in a helper function that tests call, Jasmine 5 and 6's `require('jasmine-core').noGlobals()`,
-and other runners such as Bun.
+helper called `test`, Cypress tests skipped with @cypress/skip-test's `skipOn()` and `onlyOn()`, `node:test`'s
+`getTestContext()`, Jasmine's `pending()` in a helper function that tests call, Jasmine 5 and 6's
+`require('jasmine-core').noGlobals()`, and other runners such as Bun.
 
 ## TypeScript
 

package/dist/rules/no-conflicting-states.js

@@ -20,7 +20,8 @@ export default createRule({
         },
     },
     create(context, analysis, options) {
-        const tagStates = options.states.filter(isTagState);
+        // State tags first, so a tag near both a state tag and a known tag is read as the state's.
+        const checkedTags = [...options.states.filter(isTagState).map((s) => s.tag), ...options.knownTags];
         const newTag = options.states.find((s) => s.name === 'new')?.tag;
         const quarantinedTag = options.states.find((s) => s.name === 'quarantined')?.tag;
         for (const subject of analysis.subjects) {
@@ -53,23 +54,23 @@ export default createRule({
             const { tag, range } = occurrence;
             // A Vitest tag name is written without its `@`, so show it, and fix it, the same way.
             const written = (name) => (occurrence.plain ? name.slice(1) : name);
-            if (tagStates.some((s) => s.tag === tag))
+            if (checkedTags.includes(tag))
                 return;
             const lower = tag.toLowerCase();
-            const sameLetters = tagStates.find((s) => s.tag.toLowerCase() === lower);
+            const sameLetters = checkedTags.find((checked) => checked.toLowerCase() === lower);
             if (sameLetters) {
                 context.report({
                     node: occurrence.node,
                     messageId: 'tagCase',
-                    data: { found: written(tag), expected: written(sameLetters.tag) },
-                    fix: range && ((fixer) => fixer.replaceTextRange(range, written(sameLetters.tag))),
+                    data: { found: written(tag), expected: written(sameLetters) },
+                    fix: range && ((fixer) => fixer.replaceTextRange(range, written(sameLetters))),
                 });
                 return;
             }
             // A typo changes, adds, drops or swaps a letter or two. A tag that is two or more letters
             // shorter or longer, like `@unquarantined` next to `@quarantined`, is a different word.
-            const near = tagStates.find((s) => {
-                const expected = s.tag.toLowerCase();
+            const near = checkedTags.find((checked) => {
+                const expected = checked.toLowerCase();
                 return (Math.abs(lower.length - expected.length) < 2 &&
                     editDistance(lower, expected) <= typoThreshold(expected.length - 1));
             });
@@ -77,7 +78,7 @@ export default createRule({
                 context.report({
                     node: occurrence.node,
                     messageId: 'tagTypo',
-                    data: { found: written(tag), expected: written(near.tag) },
+                    data: { found: written(tag), expected: written(near) },
                 });
             }
         }

package/dist/rules/require-ticket.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("../utils/create-rule.ts").Rule<"missingMarker" | "missingTicket" | "invalidTicket" | "placeholderTicket" | "extraText" | "removeExtraText" | "markerCase" | "dynamicTitle" | "dynamicTags" | "invalidAnnotation" | "useAnnotation" | "missingAnnotation" | "moveToAnnotation" | "unreadAnnotation">;
+declare const _default: import("../utils/create-rule.ts").Rule<"missingMarker" | "missingTicket" | "invalidTicket" | "placeholderTicket" | "extraText" | "removeExtraText" | "missingReason" | "markerCase" | "dynamicTitle" | "dynamicTags" | "invalidAnnotation" | "useAnnotation" | "missingAnnotation" | "moveToAnnotation" | "unreadAnnotation">;
 export default _default;

package/dist/rules/require-ticket.js

@@ -5,7 +5,7 @@ export default createRule({
     meta: {
         type: 'problem',
         docs: {
-            description: 'Require a ticket marker comment above skipped, fixme and tagged tests',
+            description: 'Require a ticket for skipped, fixme, todo, retried and tagged tests',
             recommended: 'error',
             url: 'https://github.com/Huldoser/eslint-plugin-test-governance/blob/main/docs/rules/require-ticket.md',
         },
@@ -13,6 +13,7 @@ export default createRule({
         schema: [],
         messages: {
             missingMarker: "{{subject}} is in the '{{state}}' state but has no `// {{marker}}: <ticket>` comment directly above it, e.g. `// {{marker}}: {{example}}`.",
+            missingReason: "{{subject}} is in the '{{state}}' state only under a condition and doesn't say why. Write the reason in a comment above it{{argument}}.",
             missingTicket: '`{{marker}}:` needs a ticket right after the colon, e.g. `// {{marker}}: {{example}}`.',
             invalidTicket: "'{{ticket}}' is not a valid ticket for the '{{state}}' state. Expected {{expected}}.",
             placeholderTicket: "'{{ticket}}' is a placeholder, not a real ticket. Link the ticket that tracks this test.",
@@ -65,6 +66,24 @@ export default createRule({
                 data: { subject: describeSubject(subject), state: state.name, type, example },
             });
         };
+        /** Reports a conditional state that gives no reason and has no ticket, which would say why as well. */
+        const reportReason = (subject, state) => {
+            if (evaluate(subject, state).kind === 'ok' || hasAnnotationTicket(subject, state, options))
+                return;
+            const callee = context.sourceCode.getText(subject.node.callee);
+            const first = subject.node.arguments.at(0);
+            const where = options.framework.reasonArgument;
+            // Vitest's `context.skip()` takes either a reason alone or a condition and then the reason.
+            const reasonOnly = where === 'only' ||
+                (where === 'either' && (first === undefined || first.type === 'Literal' || first.type === 'TemplateLiteral'));
+            const example = reasonOnly ? `${callee}('why')` : `${callee}(condition, 'why')`;
+            const argument = subject.kind === 'runtime' && where !== undefined ? `, or pass it to the call: \`${example}\`` : '';
+            context.report({
+                loc: headLoc(subject),
+                messageId: 'missingReason',
+                data: { subject: describeSubject(subject), state: state.name, argument },
+            });
+        };
         for (const subject of analysis.subjects) {
             const needsTicket = subject.states.some((s) => s.required);
             if (options.reportUnreadableTags && hasTagStates) {
@@ -82,9 +101,12 @@ export default createRule({
                 }
             }
             const annotationOnly = only && (subject.kind === 'test' || subject.kind === 'describe') ? only : undefined;
-            for (const { state, required } of subject.states) {
-                if (!required)
+            for (const { state, required, reasoned } of subject.states) {
+                if (!required) {
+                    if (options.requireReasonForConditional && reasoned === false)
+                        reportReason(subject, state);
                     continue;
+                }
                 if (annotationOnly) {
                     reportAnnotationOnly(subject, state, annotationOnly);
                     continue;

package/dist/utils/analyze.d.ts

@@ -56,6 +56,11 @@ interface StateSource {
     state: StateDef;
     /** False for conditional skips unless `requireTicketForConditional` is set. */
     required: boolean;
+    /**
+     * Set for a conditional state: whether something says why, a comment above it or its test, the reason its
+     * call takes, or one its option gives.
+     */
+    reasoned?: boolean;
 }
 export interface Subject {
     kind: 'test' | 'describe' | 'step' | 'runtime';
@@ -69,6 +74,8 @@ export interface Subject {
     inherited: Set<string>;
     /** Names of states added by runtime calls directly inside this test or describe. */
     runtimeStates: Set<string>;
+    /** Whether the comment block above this node holds any text, an `eslint-disable` description included. */
+    commented: boolean;
     /** Every tag written on this node, known or not. */
     tags: TagOccurrence[];
     /** Tags this node inherits from enclosing describes. */

package/dist/utils/analyze.js

@@ -841,6 +841,7 @@ const NO_TAGS = {
     opaqueDetails: false,
     annotations: [],
     unreadAnnotations: [],
+    reasonedOptions: new Set(),
 };
 function collectTags(sourceCode, call, hasTitle, framework, details) {
     const source = sourceCode.text;
@@ -987,6 +988,52 @@ function isUnconditional(call, notes) {
     const always = first === undefined || booleanOf(first) === true || (notes && isStaticText(first));
     return always && !isGuarded(call);
 }
+/**
+ * Whether a comment says anything: a line with text other than a marker keyword alone, such as `SKIP:`. A
+ * directive counts only by its description.
+ */
+function hasText(comment) {
+    return commentLines(comment).some(({ text }) => /[^\s*]/.test(text) && MARKER_LINE_RE.exec(text)?.[2].trim() !== '');
+}
+/**
+ * Whether a reason argument says why: text that isn't blank, or a value known only when the tests run, as
+ * `reason` or `` `${browserName} has no clipboard` ``, which is taken on trust.
+ */
+function saysWhy(sourceCode, node) {
+    const text = staticText(sourceCode, node);
+    if (text !== undefined)
+        return text.trim() !== '';
+    const value = unwrap(node);
+    return value.type !== 'Literal' && !(value.type === 'Identifier' && value.name === 'undefined');
+}
+/** Whether `node` is text that isn't blank. */
+function isReasonText(sourceCode, node) {
+    return Boolean(staticText(sourceCode, node)?.trim());
+}
+/** Whether a runtime call gives the reason for its state where its framework takes one (see `reasonArgument`). */
+function callReason(sourceCode, call, where) {
+    const first = call.arguments.at(0);
+    const second = call.arguments.at(1);
+    if (where === 'only')
+        return first !== undefined && saysWhy(sourceCode, first);
+    // Vitest's `context.skip(isMobile)` takes a condition, so only text first is a reason.
+    if (where === 'either' && first !== undefined && staticText(sourceCode, first) !== undefined) {
+        return isReasonText(sourceCode, first);
+    }
+    return second !== undefined && saysWhy(sourceCode, second);
+}
+/**
+ * Whether a conditional option gives its reason, as node:test's `{ skip: isWindows && 'no symlinks' }` or
+ * `{ skip: isWindows ? 'no symlinks' : false }`, where the text is what Node reports.
+ */
+function optionReason(sourceCode, node) {
+    const value = unwrap(node);
+    if (value.type === 'LogicalExpression')
+        return value.operator === '&&' && isReasonText(sourceCode, value.right);
+    if (value.type !== 'ConditionalExpression')
+        return false;
+    return isReasonText(sourceCode, value.consequent) || isReasonText(sourceCode, value.alternate);
+}
 const FUNCTIONS = new Set(['FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression']);
 /** Whether a statement always leaves the function or block: `return`, `throw`, or a block containing one. */
 function exits(statement) {
@@ -1114,6 +1161,33 @@ function runAnalysis(sourceCode, options) {
     const thisBodies = new Set();
     /** Describe bodies written as a `function`, whose `this` is Mocha's suite, which `this.retries()` acts on. */
     const suiteBodies = new Set();
+    /**
+     * Whether a statement around `anchor` has a comment that says something above it, as `// why` above an `if`,
+     * up to `owner`, the test or describe the call acts on. The walk goes on through a callback passed to another
+     * call, such as a hook's or a step's, but stops at a function declared some other way.
+     */
+    const commentedAround = (anchor, owner) => {
+        for (let node = anchor.parent; node; node = node.parent) {
+            if (FUNCTIONS.has(node.type)) {
+                const call = node.parent;
+                if (call?.type !== 'CallExpression' || call === owner || !call.arguments.includes(node)) {
+                    return false;
+                }
+                continue;
+            }
+            const container = node.parent;
+            if (!container || !STATEMENT_CONTAINERS.has(container.type))
+                continue;
+            const block = commentBlock(sourceCode, node, options.allowBlankLine);
+            if (block.some((comment) => !commentedOut.comments.has(comment) && hasText(comment)))
+                return true;
+        }
+        return false;
+    };
+    /** Whether a comment that says something ends the line `node` ends on, as `test.skip(isMobile); // why`. */
+    const trailingText = (node) => sourceCode
+        .getCommentsAfter(node)
+        .some((comment) => comment.loc.start.line === node.loc.end.line && hasText(comment));
     /**
      * `modifiers` maps each state modifier the call has to whether it always applies; a conditional one,
      * like `test.skip(isMobile)` or Vitest's `skipIf(...)`, needs a ticket only with `requireTicketForConditional`.
@@ -1129,6 +1203,14 @@ function runAnalysis(sourceCode, options) {
         const inRegions = regions.filter((r) => r.start <= call.range[0] && call.range[0] < r.end && !block.includes(r.comment));
         for (const comment of [...block, ...inRegions.map((r) => r.comment)])
             claimed.add(comment);
+        const commented = [...block, ...inRegions.map((r) => r.comment)].some(hasText);
+        // A runtime call can also say why above the statements around it in its function, above its test, or in
+        // its arguments.
+        const reasonedCall = () => kind === 'runtime' &&
+            ((framework.reasonArgument !== undefined && callReason(sourceCode, call, framework.reasonArgument)) ||
+                parent?.commented === true ||
+                trailingText(anchor) ||
+                commentedAround(anchor, parent?.node));
         const ownTags = new Set(tagInfo.tags.map((t) => t.tag));
         const sources = [];
         for (const state of states) {
@@ -1138,8 +1220,12 @@ function runAnalysis(sourceCode, options) {
                 continue;
             }
             const always = modifiers.get(state.modifier);
-            if (always !== undefined)
-                sources.push({ state, required: always || options.requireTicketForConditional });
+            if (always === undefined)
+                continue;
+            const source = { state, required: always || options.requireTicketForConditional };
+            if (!always)
+                source.reasoned = commented || tagInfo.reasonedOptions.has(state.modifier) || reasonedCall();
+            sources.push(source);
         }
         const inherited = new Set();
         const inheritedTags = new Set();
@@ -1173,6 +1259,7 @@ function runAnalysis(sourceCode, options) {
             anchor,
             parent,
             states: sources,
+            commented,
             inherited,
             runtimeStates: new Set(),
             tags: tagInfo.tags,
@@ -1332,9 +1419,17 @@ function runAnalysis(sourceCode, options) {
         const annotations = options.annotations === undefined || framework.annotations === undefined
             ? { annotations: [], unreadAnnotations: [] }
             : collectAnnotations(sourceCode, details, framework.annotations, options.annotations);
+        const reasonedOptions = new Set();
+        if (framework.anyOptionValue) {
+            for (const [key, value] of details.entries) {
+                const modifier = framework.optionEffects.get(key);
+                if (modifier && optionReason(sourceCode, value))
+                    reasonedOptions.add(modifier);
+            }
+        }
         return {
             details,
-            tagInfo: { ...collectTags(sourceCode, call, !untitled, framework, details), ...annotations },
+            tagInfo: { ...collectTags(sourceCode, call, !untitled, framework, details), ...annotations, reasonedOptions },
         };
     };
     const declare = (call, { kind, members, args: conditions }, infos) => {

package/dist/utils/frameworks.d.ts

@@ -95,6 +95,13 @@ export interface Framework {
      * `context.skip('why')`. In Playwright the first argument is always a condition.
      */
     skipNotes: boolean;
+    /**
+     * Where a runtime call takes the reason for its state: `after-condition`, as Playwright's
+     * `test.skip(condition, 'why')`; `only`, as node:test's `t.skip('why')` and Jasmine's `pending('why')`; or
+     * `either`, as Vitest's `context.skip('why')` and `context.skip(condition, 'why')`. Unset when it takes none,
+     * as Mocha's `this.skip()`.
+     */
+    reasonArgument?: 'after-condition' | 'only' | 'either';
     /**
      * The methods a test or hook written as a `function` can change its state with at runtime through `this`,
      * as Mocha's `this.skip()`. Empty when `this` can't.

package/dist/utils/frameworks.js

@@ -48,6 +48,7 @@ const playwright = {
     subtests: false,
     skipWithoutBody: false,
     skipNotes: false,
+    reasonArgument: 'after-condition',
     thisMethods: new Set(),
     todoWithoutBody: false,
     runtimeFunctions: new Map(),
@@ -138,6 +139,7 @@ const vitest = {
     subtests: false,
     skipWithoutBody: true,
     skipNotes: true,
+    reasonArgument: 'either',
     thisMethods: new Set(),
     todoWithoutBody: false,
     runtimeFunctions: new Map(),
@@ -244,6 +246,7 @@ const nodeTest = {
     skipWithoutBody: true,
     // `t.skip('why')` takes a message, not a condition.
     skipNotes: true,
+    reasonArgument: 'only',
     thisMethods: NODE_TEST_CONTEXT,
     todoWithoutBody: false,
     runtimeFunctions: new Map(),
@@ -288,6 +291,7 @@ const jasmine = {
     skipWithoutBody: true,
     // `pending('why')` takes a reason, not a condition.
     skipNotes: true,
+    reasonArgument: 'only',
     thisMethods: new Set(),
     todoWithoutBody: true,
     runtimeFunctions: new Map([

package/dist/utils/options.d.ts

@@ -50,8 +50,18 @@ export interface GovernanceOptions {
     states?: Partial<Record<BuiltinStateName, boolean | StateOverride>>;
     /** Adds a state for a tag, e.g. `{ 'needs-data': { when: '@needs-data', marker: 'NEEDS-DATA' } }`. */
     customStates?: Record<string, CustomState>;
+    /**
+     * Your team's other tags, such as `['@smoke', '@regression']`, which get the case and typo checks state tags
+     * get: `@Smoke` and `@smok` are reported. Write them with the `@`, also for Vitest's `tags: ['smoke']`.
+     */
+    knownTags?: string[];
     /** Require a ticket for conditional skips such as `test.skip(browserName === 'webkit')`. */
     requireTicketForConditional?: boolean;
+    /**
+     * Require a reason for conditional skips, without a ticket: a comment above the skip, or the reason the
+     * call takes, as `test.skip(browserName === 'webkit', 'No clipboard API')`.
+     */
+    requireReasonForConditional?: boolean;
     /** Let blank lines separate a marker from the test it belongs to. */
     allowBlankLine?: boolean;
     /**
@@ -104,7 +114,10 @@ export interface ResolvedOptions {
     framework: Framework;
     testFunctions: Set<string>;
     states: StateDef[];
+    /** Tags besides the state tags whose case and spelling `no-conflicting-states` checks. */
+    knownTags: string[];
     requireTicketForConditional: boolean;
+    requireReasonForConditional: boolean;
     allowBlankLine: boolean;
     allowNotes: boolean;
     reportUnreadableTags: boolean;

package/dist/utils/options.js

@@ -217,7 +217,9 @@ export function compileOptions(options) {
         framework,
         testFunctions: new Set(options.testFunctions ?? framework.testFunctions),
         states,
+        knownTags: options.knownTags ?? [],
         requireTicketForConditional: options.requireTicketForConditional ?? false,
+        requireReasonForConditional: options.requireReasonForConditional ?? false,
         allowBlankLine: options.allowBlankLine ?? false,
         allowNotes: options.allowNotes ?? false,
         reportUnreadableTags: options.reportUnreadableTags ?? false,

package/dist/utils/schema.js

@@ -96,6 +96,7 @@ export const optionsSchema = {
                 additionalProperties: false,
             },
         },
+        knownTags: { type: 'array', items: { type: 'string', pattern: TAG_RE.source, patternHint: TAG_HINT } },
         comments: {
             anyOf: [
                 { type: 'boolean', enum: [false] },
@@ -119,6 +120,7 @@ export const optionsSchema = {
             ],
         },
         requireTicketForConditional: { type: 'boolean' },
+        requireReasonForConditional: { type: 'boolean' },
         allowBlankLine: { type: 'boolean' },
         allowNotes: { type: 'boolean' },
         reportUnreadableTags: { type: 'boolean' },

package/docs/rules/no-conflicting-states.md

@@ -14,13 +14,26 @@ rule reports:
 - `@new` together with `@quarantined` on the same test, including tags inherited from a `describe`;
 - `@new` on a test that is skipped or fixme'd, since a test that doesn't run can't be promoted;
 - a state tag written in the wrong case, such as `@New` (autofixed to `@new`);
-- a near-miss spelling of a state tag, such as `@quarantiend`.
+- a near-miss spelling of a state tag, such as `@quarantiend`;
+- the same for the tags listed in `knownTags`, such as `@Smoke` or `@smok` next to `@smoke`.
 
 The `@new` checks run when the `new` state is on (`lifecycleTags: true`). Case and typo checks cover
 every tag state that is on, including custom states. A tag kept in a `const` in the same file is
 reported where the test uses it, without an autofix, since other tests may share the constant. Vitest
 tag names are written without the `@`, so `{ tags: ['New'] }` is reported, and fixed, as `'new'`.
 
+Tags such as `@smoke` usually pick which tests a CI job runs, so a misspelled one quietly drops a test
+from that job. List your team's tags in `knownTags`, written with the `@`, also for Vitest, to give them
+the same checks. A listed tag is never reported as a typo of a state tag, so `knownTags: ['@quarantine']`
+keeps a tag your team uses next to `@quarantined`. Tags of four letters or fewer after the `@`, such as
+`@e2e` or `@fast`, get only the case check, since one letter off is often another word.
+
+<!-- example: invalid settings={"knownTags":["@smoke","@regression"]} -->
+
+```js
+test('places a market order @smok', async () => {});
+```
+
 ## Examples
 
 Incorrect:
@@ -68,4 +81,5 @@ This rule has no options of its own. It reads the shared options described in th
   is on, and `@new` together with `@quarantined` is reported when both are on. A tag renamed in
   `states`, such as `@flaky`, is checked in place of the default one.
 - `customStates`: the tags of custom states get the same case and typo checks.
+- `knownTags`: other tags that get the case and typo checks.
 - `framework` and `testFunctions`: which functions count as the framework's `test`.

package/docs/rules/require-ticket.md

@@ -1,6 +1,6 @@
-# Require a ticket marker comment above skipped, fixme and tagged tests (`test-governance/require-ticket`)
+# Require a ticket for skipped, fixme, todo, retried and tagged tests (`test-governance/require-ticket`)
 
-📝 Require a ticket marker comment above skipped, fixme and tagged tests.
+📝 Require a ticket for skipped, fixme, todo, retried and tagged tests.
 
 💼 This rule is enabled in the following [configs](https://github.com/Huldoser/eslint-plugin-test-governance#usage): 🌲 `cypress`, 🌼 `jasmine`, 🃏 `jest`, ☕ `mocha`, 🟢 `node-test`, 🎭 `playwright`, ⚡ `vitest`, 🤖 `webdriverio`.
 
@@ -109,6 +109,43 @@ title and tags count as usual, and a marker goes above it, or in code without se
 If one test or describe has several markers for the same state, each must be valid: in
 `// SKIP: TRADE-1` followed by `// SKIP: nope`, the second line is reported.
 
+## Reasons for conditional skips
+
+With `requireReasonForConditional: true`, a conditional skip needs a reason but no ticket, so nobody has
+to guess later why it doesn't run. Any of these counts:
+
+- a comment above it or at the end of its line, above a statement around it, such as the `if`, or above
+  the hook, step or test it is in. Commented-out code, a marker keyword alone such as `// SKIP:`, and an
+  `eslint-disable` comment without a description after `--` say nothing, so they don't count;
+- the reason its call takes, where the runner has one: Playwright's `test.skip(condition, 'why')` and
+  `testInfo.skip(condition, 'why')`, Vitest's `context.skip(condition, 'why')` or `context.skip('why')`,
+  node:test's `t.skip('why')` and Jasmine's `pending('why')`. A reason held in a name or built in a
+  template is taken on trust;
+- in node:test, text in the option, as `{ skip: isWindows && 'No symlinks' }`, which Node reports;
+- a ticket, from a marker or an annotation.
+
+The same goes for the other states a condition can set, such as `test.fixme(condition)`. With
+`requireTicketForConditional` as well, the ticket is required and the reason alone is not enough.
+
+<!-- example: valid settings={"requireReasonForConditional":true} -->
+
+```js
+test('copies the order ID', async ({ browserName }) => {
+  test.skip(browserName === 'webkit', 'WebKit has no clipboard API in headless mode');
+});
+
+// Touch screens have no hover.
+(isMobile ? test.skip : test)('shows the price on hover', async ({ page }) => {});
+```
+
+<!-- example: invalid settings={"framework":"mocha","requireReasonForConditional":true} -->
+
+```js
+it('places an order', function () {
+  if (isWeekend) this.skip();
+});
+```
+
 ## Titles and tags that can't be read
 
 Tags can only be read from text: a string or a template literal such as `` `buys ${symbol} @new` ``,
@@ -332,6 +369,7 @@ change what it reports:
 - `lifecycleTags`, `states` and `customStates`: which states need a marker, which tag puts a test in
   each, what the marker is called, and, for a state with its own `ticket`, which tickets it accepts.
 - `requireTicketForConditional`: conditional skips need a ticket too.
+- `requireReasonForConditional`: conditional skips need a reason, a comment or the call's own reason argument.
 - `allowBlankLine`: blank lines may separate a marker from its test.
 - `allowNotes`: text may follow the tickets.
 - `annotations`: the ticket may also come from a Playwright annotation of the configured type or Vitest's `meta` key of that name. With `only: true`, a test or describe must take it from there, and a marker comment above one is reported with a suggestion that moves it.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "eslint-plugin-test-governance",
-  "version": "0.12.1",
-  "description": "ESLint rules that require a ticket comment above skipped, fixme, todo and tagged Playwright, Jest, Vitest, Mocha, Cypress, WebdriverIO, node:test and Jasmine tests.",
+  "version": "0.13.0",
+  "description": "ESLint rules that require a ticket for skipped, fixme, todo, retried, tagged and commented-out Playwright, Jest, Vitest, Mocha, Cypress, WebdriverIO, node:test and Jasmine tests.",
   "keywords": [
     "eslint",
     "eslintplugin",