eslint-plugin-test-governance 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -6,6 +6,24 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-10-13
+
+### Fixed
+
+- In Jest and Vitest, a test or describe whose title is a variable and whose body is defined
+  elsewhere, as in `test.skip(title, placeOrder)`, is checked. Before, it was read as Playwright's
+  runtime `test.skip(condition, description)` and left alone, though Jest and Vitest have no such call.
+  In Playwright, a title kept in a `const` in the same file now counts as a title too.
+- Vitest's `test.skip('title')` and `describe.skip('title')` with no body need a `// SKIP:` marker, since
+  Vitest reports them as skipped. Before, only `.todo` was checked without a body.
+- Vitest's `context.skip('note')` always skips, so it needs a `// SKIP:` marker. Before, the note was
+  read as a condition and the skip as conditional.
+- In Playwright, `describe` taken out of `test`, as in `const { describe } = test`, works like
+  `test.describe`: `describe.skip(...)` needs a marker, and tags in its title apply to the tests inside.
+  Before, it wasn't recognized.
+- A function declared inside another function that happens to be called `test` is no longer taken for
+  the framework's `test`, as a local variable already wasn't.
+
 ## [0.5.0] - 2026-10-08
 
 This release changes how the plugin is configured, ahead of 1.0.
@@ -245,7 +263,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.5.0...HEAD
+[Unreleased]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.5.1...HEAD
+[0.5.1]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.5.0...v0.5.1
 [0.5.0]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.3.0...v0.3.1

package/README.md

@@ -129,19 +129,20 @@ export default [
 `configure()` for the same files keeps that config's options and changes only the framework. All three
 turn on the same rules. What puts a test in a state in each framework:
 
-| State (marker)                         | Playwright                                                                                                          | Jest                                                                 | Vitest                                                                                                                                                             |
-| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `skip` (`// SKIP:`)                    | `test.skip(...)`, `test.describe.skip`, `test.skip()` in a body, `testInfo.skip()`, `test.step.skip`, `step.skip()` | `test.skip`, `it.skip`, `describe.skip`, `xit`, `xtest`, `xdescribe` | `test.skip`, `it.skip`, `describe.skip`, `suite.skip`, `skipIf(true)`, `runIf(false)`, `{ skip: true }`, `context.skip()` or `skip()` in a body or in `beforeEach` |
-| `todo` (`// TODO:`)                    |                                                                                                                     | `test.todo`, `it.todo`                                               | `test.todo`, `describe.todo`, `{ todo: true }`                                                                                                                     |
-| `fixme` (`// FIXME:`)                  | `test.fixme(...)`, `test.describe.fixme`, `testInfo.fixme()`                                                        |                                                                      |                                                                                                                                                                    |
-| `fail` (`// FAIL:`), off by default    | `test.fail(...)`, `testInfo.fail()`                                                                                 | `test.failing`                                                       | `test.fails`, `{ fails: true }`                                                                                                                                    |
-| `slow` (`// SLOW:`), off by default    | `test.slow()`, `testInfo.slow()`                                                                                    |                                                                      |                                                                                                                                                                    |
-| conditional skip, no ticket by default | `test.skip(condition)`, `if (...) test.skip()`                                                                      |                                                                      | `skipIf(condition)`, `runIf(condition)`, `{ skip: condition }`, `context.skip(condition)`, `if (...) context.skip()`                                               |
-| tags such as `@new` (`// NEW:`)        | the title, `{ tag }`                                                                                                | the title                                                            | the title, `{ tags }`, where `'new'` and `'@new'` both mean `@new`                                                                                                 |
+| State (marker)                         | Playwright                                                                                                          | Jest                                                                 | Vitest                                                                                                                                                                                     |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `skip` (`// SKIP:`)                    | `test.skip(...)`, `test.describe.skip`, `test.skip()` in a body, `testInfo.skip()`, `test.step.skip`, `step.skip()` | `test.skip`, `it.skip`, `describe.skip`, `xit`, `xtest`, `xdescribe` | `test.skip`, `it.skip`, `describe.skip`, `suite.skip`, `skipIf(true)`, `runIf(false)`, `{ skip: true }`, `context.skip()`, `context.skip('note')` or `skip()` in a body or in `beforeEach` |
+| `todo` (`// TODO:`)                    |                                                                                                                     | `test.todo`, `it.todo`                                               | `test.todo`, `describe.todo`, `{ todo: true }`                                                                                                                                             |
+| `fixme` (`// FIXME:`)                  | `test.fixme(...)`, `test.describe.fixme`, `testInfo.fixme()`                                                        |                                                                      |                                                                                                                                                                                            |
+| `fail` (`// FAIL:`), off by default    | `test.fail(...)`, `testInfo.fail()`                                                                                 | `test.failing`                                                       | `test.fails`, `{ fails: true }`                                                                                                                                                            |
+| `slow` (`// SLOW:`), off by default    | `test.slow()`, `testInfo.slow()`                                                                                    |                                                                      |                                                                                                                                                                                            |
+| conditional skip, no ticket by default | `test.skip(condition)`, `if (...) test.skip()`                                                                      |                                                                      | `skipIf(condition)`, `runIf(condition)`, `{ skip: condition }`, `context.skip(condition)`, `if (...) context.skip()`                                                                       |
+| tags such as `@new` (`// NEW:`)        | the title, `{ tag }`                                                                                                | the title                                                            | the title, `{ tags }`, where `'new'` and `'@new'` both mean `@new`                                                                                                                         |
 
 Table-driven tests count too: `test.skip.each(table)(...)`, `describe.skip.each` and Vitest's `.for`.
 A literal condition decides on its own: `skipIf(true)` and `runIf(false)` always skip, and `skipIf(false)`,
 `runIf(true)` and `{ skip: false }` never do.
+In Vitest, `test.skip('title')` and `describe.skip('title')` with no body are skipped too.
 Vitest writes tag names without the `@`, as in `{ tags: ['flaky'] }`, so a name in `tags` counts as the
 tag with an `@` in front: `'flaky'` is `@flaky`, and a custom state with `when: '@flaky'` matches it.
 
@@ -266,16 +267,17 @@ In Jest and Vitest files:
 A name imported or required from another test runner (Playwright, `vitest`, `@jest/globals`,
 `node:test`, `bun:test`, `mocha`, `ava`, `tap`, `uvu`), or a variable set from one such as
 `const test = require('ava')`, is never treated as the framework's `test`, and neither is a local
-variable declared inside a function that happens to be called `test`.
+variable or function declared inside a function that happens to be called `test`.
 
 ### Syntax the rules understand
 
 The [Frameworks](#frameworks) table lists what each framework's tests can do. In Playwright:
 
 - `test.skip('title', fn)`, `test.fixme(...)`, `test.fail(...)`, with or without a details object,
-  and with a body defined elsewhere, as in `test.skip('places a limit order', placeLimitOrder)`.
-- `test.describe.skip(...)` and `test.describe.fixme(...)`, including `serial` and `parallel` variants.
-  The state covers every test inside.
+  and with a body defined elsewhere, as in `test.skip('places a limit order', placeLimitOrder)`. The
+  title can also be a `const` declared in the same file.
+- `test.describe.skip(...)` and `test.describe.fixme(...)`, including `serial` and `parallel` variants,
+  and `describe.skip(...)` after `const { describe } = test`. The state covers every test inside.
 - Runtime calls inside a test, a describe or a hook such as `test.beforeEach`: `test.skip()`,
   `test.skip(true)`, `test.fixme()`, `test.fail()`, `test.slow()`, the same methods on `testInfo`,
   and `test.info().skip()`.
@@ -289,7 +291,8 @@ 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`, Playwright annotations as markers, and other runners such as Mocha, Bun and `node:test`.
+`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, and other runners such as Mocha, Bun and `node:test`.
 
 ## TypeScript
 

package/dist/utils/analyze.js

@@ -1,5 +1,6 @@
 import { isOtherRunner, RUNTIME_MODIFIERS } from "./frameworks.js";
 const TEST = { kind: 'test', modifiers: [] };
+const DESCRIBE = { kind: 'describe', modifiers: [] };
 /** Modifiers that keep a test from running. */
 const SKIPPING_MODIFIERS = new Set(['skip', 'fixme', 'todo']);
 /** What a step's `TestStepInfo` can do at runtime: `step.skip()`. */
@@ -173,6 +174,15 @@ function collectTestNames(program, framework, configured) {
                 }
             }
             else if (declarator.id.type === 'ObjectPattern') {
+                // Playwright's `const { describe } = test`, used as `describe.skip(...)`.
+                if (framework.playwright && resolve(init)) {
+                    for (const prop of declarator.id.properties) {
+                        if (prop.type === 'Property' && prop.value.type === 'Identifier' && propertyName(prop) === 'describe') {
+                            roots.set(prop.value.name, DESCRIBE);
+                        }
+                    }
+                    continue;
+                }
                 const source = requireSource(init);
                 if (source === undefined)
                     continue;
@@ -209,8 +219,8 @@ function requireSource(node) {
     return first?.type === 'Literal' && typeof first.value === 'string' ? first.value : undefined;
 }
 /**
- * Whether `id` refers to a variable declared inside a function or block, such as a local helper that
- * happens to be called `test`. Top-level variables, imports, parameters and globals still count.
+ * Whether `id` refers to a variable or function declared inside a function or block, such as a local
+ * helper that happens to be called `test`. Top-level variables, imports, parameters and globals still count.
  */
 function isLocalVariable(sourceCode, id) {
     for (let scope = sourceCode.getScope(id); scope; scope = scope.upper) {
@@ -221,7 +231,7 @@ function isLocalVariable(sourceCode, id) {
         // wraps the module.
         if (scope.block.type === 'Program')
             return false;
-        return variable.defs.some((def) => def.type === 'Variable');
+        return variable.defs.some((def) => def.type === 'Variable' || def.type === 'FunctionName');
     }
     return false;
 }
@@ -478,28 +488,38 @@ function collectTags(sourceCode, call, hasTitle, framework, details) {
     return { tags, dynamic: title.unread.size > 0, unread, opaqueDetails: details.unread !== undefined };
 }
 /**
- * Whether a call declares a test or describe block: a title and a body, as in `test('title', fn)` or
- * `test('title', details, fn)`, a static title with a body defined elsewhere, as in
- * `test.skip('pays', payWithCard)`, a describe with only a body, or a `todo` with only a title. A string
- * title tells `test.skip('pays', payWithCard)` apart from a runtime `test.skip(isMobile, 'why')`.
+ * Whether a call declares a test or describe block: a title and a body, as in `test('title', fn)`,
+ * `test('title', details, fn)` or `test.skip(title, payWithCard)` with the body defined elsewhere, a
+ * describe with only a body, or a `todo` with only a title, and in Vitest a `skip` with only a title.
+ * Only Playwright has a runtime `test.skip(isMobile, 'why')`; there a title, written out or held in a
+ * constant, or a body written in place tells the two apart.
  */
-function isDeclaration(kind, args, todo) {
+function isDeclaration(sourceCode, framework, kind, args, members) {
     const first = args.at(0);
     if (isFunction(first))
         return kind === 'describe';
     if (first === undefined)
         return false;
     if (args.length === 1)
-        return todo;
-    return isStaticText(first) || args.slice(1).some(isFunction);
+        return members.includes('todo') || (framework.skipWithoutBody && members.includes('skip'));
+    if (!framework.playwright)
+        return true;
+    const title = unwrap(first);
+    const value = constantValue(sourceCode, title);
+    return isStaticText(title) || (value !== undefined && isStaticText(unwrap(value))) || args.slice(1).some(isFunction);
 }
 /** The value of a `true` or `false` literal; undefined for anything else. */
 function booleanOf(node) {
     return node?.type === 'Literal' && typeof node.value === 'boolean' ? node.value : undefined;
 }
-function isUnconditional(call) {
+/**
+ * Whether a runtime call always applies: it has no condition, or `true`, or with `notes` only a note, as
+ * Vitest's `context.skip('Broker sandbox is down')`, and nothing around it makes it conditional.
+ */
+function isUnconditional(call, notes) {
     const first = call.arguments.at(0);
-    return (first === undefined || booleanOf(first) === true) && !isGuarded(call);
+    const always = first === undefined || booleanOf(first) === true || (notes && isStaticText(first));
+    return always && !isGuarded(call);
 }
 const FUNCTIONS = new Set(['FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression']);
 /** Whether a statement always leaves the function or block: `return`, `throw`, or a block containing one. */
@@ -736,7 +756,7 @@ function runAnalysis(sourceCode, options) {
         }
         const members = [...root.modifiers, ...path];
         const allowed = kind === 'test' ? framework.testMembers : framework.describeMembers;
-        if (members.every((m) => allowed.has(m)) && isDeclaration(kind, args, members.includes('todo'))) {
+        if (members.every((m) => allowed.has(m)) && isDeclaration(sourceCode, framework, kind, args, members)) {
             // A declaration always has a first argument: its title, or the body of a describe without one.
             const details = detailsOf(sourceCode, call);
             const tagInfo = collectTags(sourceCode, call, !isFunction(args[0]), framework, details);
@@ -778,7 +798,7 @@ function runAnalysis(sourceCode, options) {
     const runtimeSubject = (call, modifier, step) => {
         if (!states.some((s) => s.modifier === modifier))
             return undefined;
-        const subject = makeSubject('runtime', call, new Map([[modifier, isUnconditional(call)]]), NO_TAGS, step ?? stack.findLast((s) => s.kind !== 'step'));
+        const subject = makeSubject('runtime', call, new Map([[modifier, isUnconditional(call, framework.skipNotes)]]), NO_TAGS, step ?? stack.findLast((s) => s.kind !== 'step'));
         const parent = subject.parent;
         if (parent) {
             parent.runtimeStates.add(subject.states[0].state.name);

package/dist/utils/frameworks.d.ts

@@ -55,6 +55,13 @@ export interface Framework {
         param: number;
         methods: ReadonlySet<string>;
     };
+    /** Whether `skip` with only a title declares a skipped test or describe, as Vitest's `test.skip('title')`. */
+    skipWithoutBody: boolean;
+    /**
+     * Whether a runtime skip with only text always skips, the text being a note, as Vitest's
+     * `context.skip('why')`. In Playwright the first argument is always a condition.
+     */
+    skipNotes: boolean;
     /** Built-in states a test can be put in with this framework. */
     states: ReadonlySet<BuiltinStateName>;
     /** Playwright's own API on `test`: `test.describe`, `test.step`, `test.info()` and runtime `test.skip()`. */

package/dist/utils/frameworks.js

@@ -31,6 +31,8 @@ const playwright = {
     tagKey: 'tag',
     plainTags: false,
     info: { param: 1, methods: RUNTIME_MODIFIERS },
+    skipWithoutBody: false,
+    skipNotes: false,
     states: new Set(['skip', 'fixme', 'fail', 'slow', 'new', 'unstable']),
     playwright: true,
 };
@@ -60,6 +62,8 @@ const jest = {
     ]),
     optionEffects: new Map(),
     plainTags: false,
+    skipWithoutBody: false,
+    skipNotes: false,
     states: new Set(['skip', 'todo', 'fail', 'new', 'unstable']),
     playwright: false,
 };
@@ -98,6 +102,8 @@ const vitest = {
     tagKey: 'tags',
     plainTags: true,
     info: { param: 0, methods: new Set(['skip']) },
+    skipWithoutBody: true,
+    skipNotes: true,
     states: new Set(['skip', 'todo', 'fail', 'new', 'unstable']),
     playwright: false,
 };

package/docs/rules/require-ticket.md

@@ -23,8 +23,8 @@ A test is in a state when it is:
 | `fail`, `slow` | `test.fail(...)`, `test.slow()`, `testInfo.fail()`, `testInfo.slow()`                                                                 | `// FAIL:`, `// SLOW:` | no                         |
 | custom         | any tag you list in `customStates`                                                                                                    | your keyword           | when configured            |
 
-In Jest and Vitest, `xit`, `xdescribe`, Vitest's `{ skip: true }`, `skipIf(true)` and `context.skip()`,
-in a test or in `beforeEach`, skip a test too, and `test.failing` and `test.fails` put it in the `fail` state. The
+In Jest and Vitest, `xit`, `xdescribe`, Vitest's `{ skip: true }`, `skipIf(true)`, `context.skip()` and
+`context.skip('note')`, in a test or in `beforeEach`, skip a test too, and `test.failing` and `test.fails` put it in the `fail` state. The
 [README](../../README.md#frameworks) lists every form.
 
 Tags are read from the title (`'places a limit order @new'`) and from `{ tag: '@new' }` or `{ tag: ['@new', '@smoke'] }`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-test-governance",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "ESLint rules that require a ticket comment above skipped, fixme, todo and tagged Playwright, Jest and Vitest tests.",
   "keywords": [
     "eslint",
@@ -46,8 +46,8 @@
   "scripts": {
     "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json",
-    "test": "node --test 'tests/**/*.test.ts'",
-    "test:coverage": "node --test --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-branches=100 --test-coverage-functions=100 --test-coverage-lines=100 'tests/**/*.test.ts'",
+    "test": "node --test \"tests/**/*.test.ts\"",
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-include=\"src/**\" --test-coverage-branches=100 --test-coverage-functions=100 --test-coverage-lines=100 \"tests/**/*.test.ts\"",
     "test:pack": "node scripts/pack-smoke.mjs",
     "docs": "npm run build && eslint-doc-generator",
     "docs:check": "npm run build && eslint-doc-generator --check",