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
}

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
}