TestSuite.project property
The project property references the TestProject that the test suite belongs to.
advanced/node-api
97 notes in this subject, read out of this brain and free to use. This is page 2 of 2.
TestSuite.module property
The module property is a direct reference to the TestModule where the test suite is defined.
TestSuite.name property
The name property is the suite name that was passed to the describe function.
TestSuite.fullName property
The fullName property contains the name of the suite including all parent suites separated with the > symbol. For example, 'the validation logic > validating cities'.
TestSuite.id property format and structure
The id property is a unique, deterministic identifier for the suite that remains the same across multiple runs. The ID format is composed of: a file hash (10 characters), a suite index, a nested suite index, and a test index, separated by underscores. Example: 1223128da3_0_0_0. The ID can have a minus sign at the start like -1223128da3_0_0_0, and should never be parsed.
generateFileHash function for TestSuite ID
The generateFileHash function from 'vitest/node' (available since Vitest 3) can be used to generate file hashes for test suite IDs. It takes a relative file path as the first parameter and the project name (or undefined if not set) as the second parameter.
TestSuite.location property
The location property contains the location in the module where the suite was defined as an object with line and column properties. Locations are collected only if includeTaskLocation is enabled in the config, or if --reporter=html, --ui, or --browser flags are used.
TaskOptions interface for suite options
The options property returns a TaskOptions interface with the following readonly properties: each (boolean | undefined), fails (boolean | undefined), concurrent (boolean | undefined), shuffle (boolean | undefined), retry (number | undefined), repeats (number | undefined), tags (string[] | undefined), and mode ('run' | 'only' | 'skip' | 'todo'). These represent the options the suite was collected with.
TestSuite.children property
The children property is a collection of all direct child suites and tests inside the current suite. Iterating suite.children only iterates the first level of nesting and does not go deeper. Use children.allTests() or children.allSuites() for all tests or suites, or a recursive function to iterate over everything.
TestSuite.ok() method
The ok() method checks if the suite has any failed tests and returns a boolean. It returns false if the suite failed during collection. In that case, check the errors() method for thrown errors.
TestSuite.state() method return values
The state() method returns a TestSuiteState with possible values: 'pending' (tests did not finish running yet), 'failed' (suite has failed tests or they couldn't be collected), 'passed' (every test passed), or 'skipped' (suite was skipped during collection).
TestSuite.errors() method
The errors() method returns a TestError[] array containing errors that happened outside of test runs during collection, such as syntax errors. Errors are serialized into simple objects, so instanceof Error will always return false.
TestSuite.meta() method
The meta() method returns TaskMeta containing custom metadata attached to the suite during execution or collection. Since Vitest 4.1, metadata can be attached by providing a meta object during test collection. Suite metadata is inherited by tests since Vitest 4.1.
generateFileHash function from vitest/node
You can generate a file hash using the generateFileHash function from 'vitest/node', available since Vitest 3. It takes a relative file path as the first argument and the project name or undefined as the second argument. Example: const hash = generateFileHash('/file/path.js', undefined)
TestCollection represents top-level suites and tests
TestCollection represents a collection of top-level suites and tests in a suite or a module, and provides useful methods to iterate over itself.
TestCollection methods return iterators for performance
Most TestCollection methods return an iterator instead of an array for better performance. If you prefer working with an array, you can spread the iterator using the spread operator, for example: [...children.allSuites()].
TestCollection itself is an iterator
TestCollection itself is an iterator and can be used in a for...of loop to iterate over children. Example: for (const child of module.children) { console.log(child.type, child.name) }.
TestCollection.size property
The size property returns the number of tests and suites in the collection. This number includes only tests and suites at the top-level and does not include nested suites and tests.
TestCollection.at() method signature
The at(index: number) method returns the test or suite at a specific index. It returns TestCase | TestSuite | undefined and accepts negative indexes.
TestCollection.array() method signature
The array() method returns the same collection but as an array of type (TestCase | TestSuite)[]. This is useful when you want to use Array methods like map and filter that are not supported by the TaskCollection implementation.
TestCollection.allSuites() method signature
The allSuites() method has signature function allSuites(): Generator<TestSuite, undefined, void>. It filters all suites that are part of this collection and its children recursively.
TestCollection.allSuites() example with error checking
Example of using allSuites(): for (const suite of module.children.allSuites()) { if (suite.errors().length) { console.log('failed to collect', suite.errors()) } }
TestCollection.allTests() method signature
The allTests(state?: TestState) method has signature function allTests(state?: TestState): Generator<TestCase, undefined, void>. It filters all tests that are part of this collection and its children. You can pass a state value to filter tests by the state.
TestCollection.allTests() example with state checking
Example of using allTests(): for (const test of module.children.allTests()) { if (test.result().state === 'pending') { console.log('test', test.fullName, 'did not finish') } }
TestCollection.tests() method signature
The tests(state?: TestState) method has signature function tests(state?: TestState): Generator<TestCase, undefined, void>. It filters only the tests that are part of this collection without including nested tests. You can pass a state value to filter tests by the state.
TestCollection.suites() method signature
The suites() method has signature function suites(): Generator<TestSuite, undefined, void>. It filters only the suites that are part of this collection without including nested suites.
TestModule class represents a single module in a project
The TestModule class represents a single module in a single project. It is only available in the main thread. You can distinguish TestModule from other task types by checking if task.type === 'module'.
TestModule.moduleId property format
moduleId is usually an absolute unix file path even on Windows. It can be a virtual id if the file is not on disk. Valid examples: 'C:/Users/Documents/project/example.test.ts' and '/Users/mac/project/example.test.ts'. Invalid: 'C:\\Users\\Documents\\project\\example.test.ts' (backslashes are not used).
TestModule.relativeModuleId property
relativeModuleId is module id relative to the project. This is the same as task.name in the deprecated API. Valid examples: 'project/example.test.ts' and 'example.test.ts'. Invalid: 'project\\example.test.ts' (uses backslashes).
TestModule.viteEnvironment property
viteEnvironment is a Vite DevEnvironment that transforms all files inside of the test module. This property was added in Vitest v4.1.0.
TestModule.state() method returns module state
TestModule.state() works the same way as testSuite.state() but can also return 'queued' if the module was not executed yet.
TestModule.meta() returns custom metadata
TestModule.meta() returns TaskMeta which is custom metadata attached to the module during its execution or collection. Metadata can be assigned by setting properties on task.meta during a test run. If metadata was attached during collection (outside of the test function), it will be available in the onTestModuleCollected hook in custom reporters.
TestModule.diagnostic() returns module diagnostics
TestModule.diagnostic() returns ModuleDiagnostic with the following properties: environmentSetupDuration (time to import and initiate environment), prepareDuration (time for Vitest to setup test harness), collectDuration (time to import test module), setupDuration (time to import setup module), duration (accumulated duration of all tests and hooks), heap (memory used in bytes, only if logHeapUsage flag used), importDurations (Record<string, ImportDuration> for time spent importing dependencies), concurrencyId (worker id, cannot exceed maxWorkers), and workerId (incremental worker number). Node.js and browser tests run in different pools with separate concurrencyId and workerId values.
ImportDuration interface for module diagnostics
ImportDuration has two properties: selfTime (time importing and executing the file itself, not counting non-externalized imports) and totalTime (time importing and executing the file and all its imports).
TestModule.logs() returns console logs from module collection
TestModule.logs() returns ReadonlyArray<UserConsoleLog> containing console logs recorded at the top level of the module during test collection. Logs inside describe blocks or test functions are not included.
TestModule.toTestSpecification() creates test specification
TestModule.toTestSpecification(testCases?: TestCase[]) returns a new test specification that can be used to filter or run a specific test module. It accepts an optional array of test cases that should be filtered.
TestModule inherits from TestSuite
TestModule inherits all methods and properties from TestSuite. The documentation only lists methods and properties unique to TestModule.