docs: add reported tasks docs (#6245)

Author: sheremet-va

docs/advanced/reporters.md

@@ -56,6 +56,374 @@ export default defineConfig({
 })
 ```
 
+## Reported Tasks
+
+::: warning
+This is an experimental API. Breaking changes might not follow SemVer. Please pin Vitest's version when using it.
+
+You can get access to this API by calling `vitest.state.getReportedEntity(runnerTask)`:
+
+```ts twoslash
+import type { Vitest } from 'vitest/node'
+import type { RunnerTestFile } from 'vitest'
+import type { Reporter, TestFile } from 'vitest/reporters'
+
+class MyReporter implements Reporter {
+  ctx!: Vitest
+
+  onInit(ctx: Vitest) {
+    this.ctx = ctx
+  }
+
+  onFinished(files: RunnerTestFile[]) {
+    for (const fileTask of files) {
+      const testFile = this.ctx.state.getReportedEntity(fileTask) as TestFile
+      for (const task of testFile.children) {
+        //                         ^?
+        console.log('finished', task.type, task.fullName)
+      }
+    }
+  }
+}
+```
+
+We are planning to stabilize this API in Vitest 2.1.
+:::
+
+### TestCase
+
+`TestCase` represents a single test.
+
+```ts
+declare class TestCase {
+  readonly type = 'test' | 'custom'
+  /**
+   * Task instance.
+   * @experimental Public task API is experimental and does not follow semver.
+   */
+  readonly task: RunnerTestCase | RunnerCustomCase
+  /**
+   * The project associated with the test.
+   */
+  readonly project: TestProject
+  /**
+   * Direct reference to the test file where the test is defined.
+   */
+  readonly file: TestFile
+  /**
+   * Name of the test.
+   */
+  readonly name: string
+  /**
+   * Full name of the test including all parent suites separated with `>`.
+   */
+  readonly fullName: string
+  /**
+   * Unique identifier.
+   * This ID is deterministic and will be the same for the same test across multiple runs.
+   * The ID is based on the project name, file path and test position.
+   */
+  readonly id: string
+  /**
+   * Location in the file where the test was defined.
+   * Locations are collected only if `includeTaskLocation` is enabled in the config.
+   */
+  readonly location: { line: number; column: number } | undefined
+  /**
+   * Parent suite. If the test was called directly inside the file, the parent will be the file.
+   */
+  readonly parent: TestSuite | TestFile
+  /**
+   * Options that test was initiated with.
+   */
+  readonly options: TaskOptions
+  /**
+   * Checks if the test did not fail the suite.
+   * If the test is not finished yet or was skipped, it will return `true`.
+   */
+  ok(): boolean
+  /**
+   * Custom metadata that was attached to the test during its execution.
+   */
+  meta(): TaskMeta
+  /**
+   * Test results. Will be `undefined` if test is not finished yet or was just collected.
+   */
+  result(): TestResult | undefined
+  /**
+   * Useful information about the test like duration, memory usage, etc.
+   */
+  diagnostic(): TestDiagnostic | undefined
+}
+
+export type TestResult = TestResultPassed | TestResultFailed | TestResultSkipped
+
+export interface TestResultPassed {
+  /**
+   * The test passed successfully.
+   */
+  state: 'passed'
+  /**
+   * Errors that were thrown during the test execution.
+   *
+   * **Note**: If test was retried successfully, errors will still be reported.
+   */
+  errors: TestError[] | undefined
+}
+
+export interface TestResultFailed {
+  /**
+   * The test failed to execute.
+   */
+  state: 'failed'
+  /**
+   * Errors that were thrown during the test execution.
+   */
+  errors: TestError[]
+}
+
+export interface TestResultSkipped {
+  /**
+   * The test was skipped with `only`, `skip` or `todo` flag.
+   * You can see which one was used in the `mode` option.
+   */
+  state: 'skipped'
+  /**
+   * Skipped tests have no errors.
+   */
+  errors: undefined
+}
+
+export interface TestDiagnostic {
+  /**
+   * The amount of memory used by the test in bytes.
+   * This value is only available if the test was executed with `logHeapUsage` flag.
+   */
+  heap: number | undefined
+  /**
+   * The time it takes to execute the test in ms.
+   */
+  duration: number
+  /**
+   * The time in ms when the test started.
+   */
+  startTime: number
+  /**
+   * The amount of times the test was retried.
+   */
+  retryCount: number
+  /**
+   * The amount of times the test was repeated as configured by `repeats` option.
+   * This value can be lower if the test failed during the repeat and no `retry` is configured.
+   */
+  repeatCount: number
+  /**
+   * If test passed on a second retry.
+   */
+  flaky: boolean
+}
+```
+
+### TestSuite
+
+`TestSuite` represents a single suite that contains tests and other suites.
+
+```ts
+declare class TestSuite {
+  readonly type = 'suite'
+  /**
+   * Task instance.
+   * @experimental Public task API is experimental and does not follow semver.
+   */
+  readonly task: RunnerTestSuite
+  /**
+   * The project associated with the test.
+   */
+  readonly project: TestProject
+  /**
+   * Direct reference to the test file where the suite is defined.
+   */
+  readonly file: TestFile
+  /**
+   * Name of the suite.
+   */
+  readonly name: string
+  /**
+   * Full name of the suite including all parent suites separated with `>`.
+   */
+  readonly fullName: string
+  /**
+   * Unique identifier.
+   * This ID is deterministic and will be the same for the same test across multiple runs.
+   * The ID is based on the project name, file path and test position.
+   */
+  readonly id: string
+  /**
+   * Location in the file where the suite was defined.
+   * Locations are collected only if `includeTaskLocation` is enabled in the config.
+   */
+  readonly location: { line: number; column: number } | undefined
+  /**
+   * Collection of suites and tests that are part of this suite.
+   */
+  readonly children: TaskCollection
+  /**
+   * Options that the suite was initiated with.
+   */
+  readonly options: TaskOptions
+}
+```
+
+### TestFile
+
+`TestFile` represents a single file that contains suites and tests.
+
+```ts
+declare class TestFile extends SuiteImplementation {
+  readonly type = 'file'
+  /**
+   * Task instance.
+   * @experimental Public task API is experimental and does not follow semver.
+   */
+  readonly task: RunnerTestFile
+  /**
+   * Collection of suites and tests that are part of this file.
+   */
+  readonly children: TestCollection
+  /**
+   * This is usually an absolute Unix file path.
+   * It can be a virtual id if the file is not on the disk.
+   * This value corresponds to Vite's `ModuleGraph` id.
+   */
+  readonly moduleId: string
+  /**
+   * Useful information about the file like duration, memory usage, etc.
+   * If the file was not executed yet, all diagnostic values will return `0`.
+   */
+  diagnostic(): FileDiagnostic
+}
+
+export interface FileDiagnostic {
+  /**
+   * The time it takes to import and initiate an environment.
+   */
+  environmentSetupDuration: number
+  /**
+   * The time it takes Vitest to setup test harness (runner, mocks, etc.).
+   */
+  prepareDuration: number
+  /**
+   * The time it takes to import the test file.
+   * This includes importing everything in the file and executing suite callbacks.
+   */
+  collectDuration: number
+  /**
+   * The time it takes to import the setup file.
+   */
+  setupDuration: number
+  /**
+   * Accumulated duration of all tests and hooks in the file.
+   */
+  duration: number
+}
+```
+
+### TestCollection
+
+`TestCollection` represents a collection of suites and tests. It also provides useful methods to iterate over itself.
+
+```ts
+declare class TestCollection {
+  /**
+   * Returns the test or suite at a specific index in the array.
+   */
+  at(index: number): TestCase | TestSuite | undefined
+  /**
+   * The number of tests and suites in the collection.
+   */
+  size: number
+  /**
+   * Returns the collection in array form for easier manipulation.
+   */
+  array(): (TestCase | TestSuite)[]
+  /**
+   * Filters all suites that are part of this collection and its children.
+   */
+  allSuites(): IterableIterator<TestSuite>
+  /**
+   * Filters all tests that are part of this collection and its children.
+   */
+  allTests(state?: TestResult['state'] | 'running'): IterableIterator<TestCase>
+  /**
+   * Filters only the tests that are part of this collection.
+   */
+  tests(state?: TestResult['state'] | 'running'): IterableIterator<TestCase>
+  /**
+   * Filters only the suites that are part of this collection.
+   */
+  suites(): IterableIterator<TestSuite>;
+  [Symbol.iterator](): IterableIterator<TestSuite | TestCase>
+}
+```
+
+For example, you can iterate over all tests inside a file by calling `testFile.children.allTests()`:
+
+```ts
+function onFileCollected(testFile: TestFile): void {
+  console.log('collecting tests in', testFile.moduleId)
+
+  // iterate over all tests and suites in the file
+  for (const task of testFile.children.allTests()) {
+    console.log('collected', task.type, task.fullName)
+  }
+}
+```
+
+### TestProject
+
+`TestProject` is a project assosiated with the file. Every test and suite inside that file will reference the same project.
+
+Project is useful to get the configuration or provided context.
+
+```ts
+declare class TestProject {
+  /**
+   * The global vitest instance.
+   * @experimental The public Vitest API is experimental and does not follow semver.
+   */
+  readonly vitest: Vitest
+  /**
+   * The workspace project this test project is associated with.
+   * @experimental The public Vitest API is experimental and does not follow semver.
+   */
+  readonly workspaceProject: WorkspaceProject
+  /**
+   * Resolved project configuration.
+   */
+  readonly config: ResolvedProjectConfig
+  /**
+   * Resolved global configuration. If there are no workspace projects, this will be the same as `config`.
+   */
+  readonly globalConfig: ResolvedConfig
+  /**
+   * Serialized project configuration. This is the config that tests receive.
+   */
+  get serializedConfig(): SerializedConfig
+  /**
+   * The name of the project or an empty string if not set.
+   */
+  name(): string
+  /**
+   * Custom context provided to the project.
+   */
+  context(): ProvidedContext
+  /**
+   * Provide a custom serializable context to the project. This context will be available for tests once they run.
+   */
+  provide<T extends keyof ProvidedContext & string>(key: T, value: ProvidedContext[T]): void
+}
+```
+
 ## Exported Reporters
 
 `vitest` comes with a few [built-in reporters](/guide/reporters) that you can use out of the box.

packages/vitest/src/node/reported-workspace-project.ts

@@ -52,7 +52,7 @@ export class TestProject {
   }
 
   /**
-   * Provide a custom context to the project. This context will be available for tests once they run.
+   * Provide a custom serializable context to the project. This context will be available for tests once they run.
    */
   public provide<T extends keyof ProvidedContext & string>(
     key: T,

packages/vitest/src/node/reporters/index.ts

@@ -29,6 +29,7 @@ export {
 export type { BaseReporter, Reporter }
 
 export { TestCase, TestFile, TestSuite } from './reported-tasks'
+export type { TestProject } from '../reported-workspace-project'
 export type {
   TestCollection,