feat: add toTestSpecification to reported tasks (#9464)

sheremet-va · web-flow · commit 1a4705da9944 · 2026-01-15T19:01:23.000+01:00
diff --git a/docs/api/advanced/test-case.md b/docs/api/advanced/test-case.md
@@ -280,3 +280,11 @@ function artifacts(): ReadonlyArray<TestArtifact>
 ```
 
 [Test artifacts](/api/advanced/artifacts) recorded via the `recordArtifact` API during the test execution.
+
+## toTestSpecification <Version>4.1.0</Version> {#totestspecification}
+
+```ts
+function toTestSpecification(): TestSpecification
+```
+
+Returns a new [test specification](/api/advanced/test-specification) that can be used to filter or run this specific test case.
diff --git a/docs/api/advanced/test-module.md b/docs/api/advanced/test-module.md
@@ -124,3 +124,11 @@ interface ImportDuration {
 ## viteEnvironment <Version type="experimental">4.0.15</Version> <Experimental /> {#viteenvironment}
 
 This is a Vite's [`DevEnvironment`](https://vite.dev/guide/api-environment) that transforms all files inside of the test module.
+
+## toTestSpecification <Version>4.1.0</Version> {#totestspecification}
+
+```ts
+function toTestSpecification(): TestSpecification
+```
+
+Returns a new [test specification](/api/advanced/test-specification) that can be used to filter or run this specific test module.
diff --git a/docs/api/advanced/test-suite.md b/docs/api/advanced/test-suite.md
@@ -218,3 +218,11 @@ describe('the validation works correctly', () => {
 :::tip
 If metadata was attached during collection (outside of the `test` function), then it will be available in [`onTestModuleCollected`](./reporters#ontestmodulecollected) hook in the custom reporter.
 :::
+
+## toTestSpecification <Version>4.1.0</Version> {#totestspecification}
+
+```ts
+function toTestSpecification(): TestSpecification
+```
+
+Returns a new [test specification](/api/advanced/test-specification) that can be used to filter or run this specific test suite.
diff --git a/packages/vitest/src/node/reporters/reported-tasks.ts b/packages/vitest/src/node/reporters/reported-tasks.ts
@@ -12,6 +12,7 @@ import type {
 import type { SerializedError, TestError } from '@vitest/utils'
 import type { DevEnvironment } from 'vite'
 import type { TestProject } from '../project'
+import type { TestSpecification } from '../test-specification'
 
 class ReportedTaskImplementation {
   /**
@@ -220,6 +221,18 @@ export class TestCase extends ReportedTaskImplementation {
       flaky: !!result.retryCount && result.state === 'pass' && result.retryCount > 0,
     }
   }
+
+  /**
+   * Returns a new test specification that can be used to filter or run this specific test case.
+   */
+  public toTestSpecification(): TestSpecification {
+    const isTypecheck = this.task.meta.typecheck === true
+    return this.project.createSpecification(
+      this.module.moduleId,
+      { testIds: [this.id] },
+      isTypecheck ? 'typecheck' : undefined,
+    )
+  }
 }
 
 class TestCollection {
@@ -420,6 +433,19 @@ export class TestSuite extends SuiteImplementation {
     return getSuiteState(this.task)
   }
 
+  /**
+   * Returns a new test specification that can be used to filter or run this specific test suite.
+   */
+  public toTestSpecification(): TestSpecification {
+    const isTypecheck = this.task.meta.typecheck === true
+    const testIds = [...this.children.allTests()].map(test => test.id)
+    return this.project.createSpecification(
+      this.module.moduleId,
+      { testIds },
+      isTypecheck ? 'typecheck' : undefined,
+    )
+  }
+
   /**
    * Full name of the suite including all parent suites separated with `>`.
    */
@@ -474,6 +500,18 @@ export class TestModule extends SuiteImplementation {
     }
   }
 
+  /**
+   * Returns a new test specification that can be used to filter or run this specific test module.
+   */
+  public toTestSpecification(): TestSpecification {
+    const isTypecheck = this.task.meta.typecheck === true
+    return this.project.createSpecification(
+      this.moduleId,
+      undefined,
+      isTypecheck ? 'typecheck' : undefined,
+    )
+  }
+
   /**
    * Checks the running state of the test file.
    */
