TestModule

The TestModule class represents a single module in a single project. This class is only available in the main thread. Refer to the "Runner API" if you are working with runtime tasks.

The TestModule instance always has a type property with the value of module. You can use it to distinguish between different task types:

if (task.type === 'module') {
  task // TestModule
}

::: warning Extending Suite Methods The TestModule class inherits all methods and properties from the TestSuite. This guide will only list methods and properties unique to the TestModule. :::

moduleId

This is usually an absolute unix file path (even on Windows). It can be a virtual id if the file is not on the disk. This value corresponds to Vite's ModuleGraph id.

'C:/Users/Documents/project/example.test.ts' // ✅
'/Users/mac/project/example.test.ts' // ✅
'C:\\Users\\Documents\\project\\example.test.ts' // ❌

relativeModuleId

Module id relative to the project. This is the same as task.name in the deprecated API.

'project/example.test.ts' // ✅
'example.test.ts' // ✅
'project\\example.test.ts' // ❌

state

function state(): TestModuleState

Works the same way as testSuite.state(), but can also return queued if module wasn't executed yet.

meta 3.1.0

function meta(): TaskMeta

Custom metadata that was attached to the module during its execution or collection. The meta can be attached by assigning a property to the task.meta object during a test run:

import { test } from 'vitest'

describe('the validation works correctly', (task) => {
  // assign "decorated" during collection
  task.file.meta.decorated = false

  test('some test', ({ task }) => {
    // assign "decorated" during test run, it will be available
    // only in onTestCaseReady hook
    task.file.meta.decorated = false
  })
})

:::tip If metadata was attached during collection (outside of the test function), then it will be available in onTestModuleCollected hook in the custom reporter. :::

diagnostic

function diagnostic(): ModuleDiagnostic

Useful information about the module like duration, memory usage, etc. If the module was not executed yet, all diagnostic values will return 0.

interface ModuleDiagnostic {
  /**
   * The time it takes to import and initiate an environment.
   */
  readonly environmentSetupDuration: number
  /**
   * The time it takes Vitest to setup test harness (runner, mocks, etc.).
   */
  readonly prepareDuration: number
  /**
   * The time it takes to import the test module.
   * This includes importing everything in the module and executing suite callbacks.
   */
  readonly collectDuration: number
  /**
   * The time it takes to import the setup module.
   */
  readonly setupDuration: number
  /**
   * Accumulated duration of all tests and hooks in the module.
   */
  readonly duration: number
  /**
   * The amount of memory used by the module in bytes.
   * This value is only available if the test was executed with `logHeapUsage` flag.
   */
  readonly heap: number | undefined
  /**
   * The time spent importing every non-externalized dependency that Vitest has processed.
   */
  readonly importDurations: Record<string, ImportDuration>
}

/** The time spent importing & executing a non-externalized file. */
interface ImportDuration {
  /** The time spent importing & executing the file itself, not counting all non-externalized imports that the file does. */
  selfTime: number

  /** The time spent importing & executing the file and all its imports. */
  totalTime: number
}

3.7 KiB Raw Blame History