@vitest-agent/mcp 1.0.1 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (229) hide show
  1. package/README.md +1 -2
  2. package/bin/vitest-agent-mcp.js +1 -17
  3. package/index.d.ts +324 -315
  4. package/index.js +2 -4
  5. package/middleware/idempotency.js +1 -1
  6. package/package.json +2 -2
  7. package/server.js +2 -4
  8. package/tools/acceptance-metrics.js +1 -1
  9. package/tools/cache-health.js +1 -1
  10. package/tools/commit-changes.js +1 -1
  11. package/tools/configure.js +1 -1
  12. package/tools/coverage.js +1 -1
  13. package/tools/errors.js +1 -1
  14. package/tools/failure-signature-get.js +1 -1
  15. package/tools/file-coverage.js +1 -1
  16. package/tools/history.js +1 -1
  17. package/tools/inventory.js +1 -1
  18. package/tools/overview.js +1 -1
  19. package/tools/run-tests.js +15 -3
  20. package/tools/settings-list.js +1 -1
  21. package/tools/status.js +1 -1
  22. package/tools/tdd-artifact.js +1 -1
  23. package/tools/tdd-task.js +1 -1
  24. package/tools/test.js +1 -1
  25. package/tools/trends.js +1 -1
  26. package/tools/turn-search.js +1 -1
  27. package/public/patterns/_meta.json +0 -67
  28. package/public/patterns/authoring-a-custom-vitest-agent-reporter.md +0 -82
  29. package/public/patterns/known-issues-and-caveats.md +0 -52
  30. package/public/patterns/operating-vitest-agent-as-an-agent.md +0 -53
  31. package/public/patterns/running-tests-via-mcp.md +0 -58
  32. package/public/patterns/silencing-leaking-output-in-tests.md +0 -91
  33. package/public/patterns/testing-effect-schema-definitions.md +0 -71
  34. package/public/patterns/testing-effect-services-with-mock-layers.md +0 -63
  35. package/public/vendor/vitest-docs/ATTRIBUTION.md +0 -5
  36. package/public/vendor/vitest-docs/api/advanced/artifacts.md +0 -189
  37. package/public/vendor/vitest-docs/api/advanced/metadata.md +0 -68
  38. package/public/vendor/vitest-docs/api/advanced/plugin.md +0 -168
  39. package/public/vendor/vitest-docs/api/advanced/reporters.md +0 -342
  40. package/public/vendor/vitest-docs/api/advanced/runner.md +0 -334
  41. package/public/vendor/vitest-docs/api/advanced/test-case.md +0 -302
  42. package/public/vendor/vitest-docs/api/advanced/test-collection.md +0 -89
  43. package/public/vendor/vitest-docs/api/advanced/test-module.md +0 -140
  44. package/public/vendor/vitest-docs/api/advanced/test-project.md +0 -321
  45. package/public/vendor/vitest-docs/api/advanced/test-specification.md +0 -96
  46. package/public/vendor/vitest-docs/api/advanced/test-suite.md +0 -230
  47. package/public/vendor/vitest-docs/api/advanced/vitest.md +0 -684
  48. package/public/vendor/vitest-docs/api/assert-type.md +0 -22
  49. package/public/vendor/vitest-docs/api/assert.md +0 -1960
  50. package/public/vendor/vitest-docs/api/browser/assertions.md +0 -1277
  51. package/public/vendor/vitest-docs/api/browser/commands.md +0 -154
  52. package/public/vendor/vitest-docs/api/browser/context.md +0 -338
  53. package/public/vendor/vitest-docs/api/browser/interactivity.md +0 -681
  54. package/public/vendor/vitest-docs/api/browser/locators.md +0 -1171
  55. package/public/vendor/vitest-docs/api/browser/react.md +0 -346
  56. package/public/vendor/vitest-docs/api/browser/svelte.md +0 -292
  57. package/public/vendor/vitest-docs/api/browser/vue.md +0 -222
  58. package/public/vendor/vitest-docs/api/describe.md +0 -374
  59. package/public/vendor/vitest-docs/api/expect-typeof.md +0 -571
  60. package/public/vendor/vitest-docs/api/expect.md +0 -2304
  61. package/public/vendor/vitest-docs/api/hooks.md +0 -463
  62. package/public/vendor/vitest-docs/api/mock.md +0 -701
  63. package/public/vendor/vitest-docs/api/test.md +0 -926
  64. package/public/vendor/vitest-docs/api/vi.md +0 -1372
  65. package/public/vendor/vitest-docs/config/alias.md +0 -13
  66. package/public/vendor/vitest-docs/config/allowonly.md +0 -32
  67. package/public/vendor/vitest-docs/config/api.md +0 -27
  68. package/public/vendor/vitest-docs/config/attachmentsdir.md +0 -6
  69. package/public/vendor/vitest-docs/config/bail.md +0 -9
  70. package/public/vendor/vitest-docs/config/benchmark.md +0 -65
  71. package/public/vendor/vitest-docs/config/browser/api.md +0 -23
  72. package/public/vendor/vitest-docs/config/browser/commands.md +0 -6
  73. package/public/vendor/vitest-docs/config/browser/connecttimeout.md +0 -10
  74. package/public/vendor/vitest-docs/config/browser/detailspanelposition.md +0 -38
  75. package/public/vendor/vitest-docs/config/browser/enabled.md +0 -40
  76. package/public/vendor/vitest-docs/config/browser/expect.md +0 -250
  77. package/public/vendor/vitest-docs/config/browser/headless.md +0 -7
  78. package/public/vendor/vitest-docs/config/browser/instances.md +0 -47
  79. package/public/vendor/vitest-docs/config/browser/isolate.md +0 -11
  80. package/public/vendor/vitest-docs/config/browser/locators.md +0 -24
  81. package/public/vendor/vitest-docs/config/browser/orchestratorscripts.md +0 -39
  82. package/public/vendor/vitest-docs/config/browser/playwright.md +0 -214
  83. package/public/vendor/vitest-docs/config/browser/preview.md +0 -32
  84. package/public/vendor/vitest-docs/config/browser/provider.md +0 -79
  85. package/public/vendor/vitest-docs/config/browser/screenshotdirectory.md +0 -6
  86. package/public/vendor/vitest-docs/config/browser/screenshotfailures.md +0 -6
  87. package/public/vendor/vitest-docs/config/browser/testerhtmlpath.md +0 -5
  88. package/public/vendor/vitest-docs/config/browser/trace.md +0 -43
  89. package/public/vendor/vitest-docs/config/browser/trackunhandlederrors.md +0 -10
  90. package/public/vendor/vitest-docs/config/browser/ui.md +0 -7
  91. package/public/vendor/vitest-docs/config/browser/viewport.md +0 -6
  92. package/public/vendor/vitest-docs/config/browser/webdriverio.md +0 -64
  93. package/public/vendor/vitest-docs/config/cache.md +0 -26
  94. package/public/vendor/vitest-docs/config/chaiconfig.md +0 -29
  95. package/public/vendor/vitest-docs/config/clearmocks.md +0 -22
  96. package/public/vendor/vitest-docs/config/coverage.md +0 -455
  97. package/public/vendor/vitest-docs/config/css.md +0 -47
  98. package/public/vendor/vitest-docs/config/dangerouslyignoreunhandlederrors.md +0 -23
  99. package/public/vendor/vitest-docs/config/deps.md +0 -127
  100. package/public/vendor/vitest-docs/config/detectasyncleaks.md +0 -39
  101. package/public/vendor/vitest-docs/config/diff.md +0 -96
  102. package/public/vendor/vitest-docs/config/dir.md +0 -7
  103. package/public/vendor/vitest-docs/config/disableconsoleintercept.md +0 -15
  104. package/public/vendor/vitest-docs/config/env.md +0 -5
  105. package/public/vendor/vitest-docs/config/environment.md +0 -96
  106. package/public/vendor/vitest-docs/config/environmentoptions.md +0 -30
  107. package/public/vendor/vitest-docs/config/exclude.md +0 -49
  108. package/public/vendor/vitest-docs/config/execargv.md +0 -10
  109. package/public/vendor/vitest-docs/config/expandsnapshotdiff.md +0 -7
  110. package/public/vendor/vitest-docs/config/expect.md +0 -38
  111. package/public/vendor/vitest-docs/config/experimental.md +0 -510
  112. package/public/vendor/vitest-docs/config/faketimers.md +0 -51
  113. package/public/vendor/vitest-docs/config/fileparallelism.md +0 -11
  114. package/public/vendor/vitest-docs/config/forcereruntriggers.md +0 -19
  115. package/public/vendor/vitest-docs/config/globals.md +0 -42
  116. package/public/vendor/vitest-docs/config/globalsetup.md +0 -72
  117. package/public/vendor/vitest-docs/config/hideskippedtests.md +0 -7
  118. package/public/vendor/vitest-docs/config/hooktimeout.md +0 -7
  119. package/public/vendor/vitest-docs/config/include-source.md +0 -115
  120. package/public/vendor/vitest-docs/config/include.md +0 -71
  121. package/public/vendor/vitest-docs/config/includetasklocation.md +0 -17
  122. package/public/vendor/vitest-docs/config/index.md +0 -85
  123. package/public/vendor/vitest-docs/config/isolate.md +0 -13
  124. package/public/vendor/vitest-docs/config/logheapusage.md +0 -7
  125. package/public/vendor/vitest-docs/config/maxconcurrency.md +0 -9
  126. package/public/vendor/vitest-docs/config/maxworkers.md +0 -49
  127. package/public/vendor/vitest-docs/config/mockreset.md +0 -22
  128. package/public/vendor/vitest-docs/config/mode.md +0 -7
  129. package/public/vendor/vitest-docs/config/name.md +0 -111
  130. package/public/vendor/vitest-docs/config/onconsolelog.md +0 -25
  131. package/public/vendor/vitest-docs/config/onstacktrace.md +0 -32
  132. package/public/vendor/vitest-docs/config/onunhandlederror.md +0 -35
  133. package/public/vendor/vitest-docs/config/open.md +0 -7
  134. package/public/vendor/vitest-docs/config/outputfile.md +0 -7
  135. package/public/vendor/vitest-docs/config/passwithnotests.md +0 -7
  136. package/public/vendor/vitest-docs/config/pool.md +0 -45
  137. package/public/vendor/vitest-docs/config/printconsoletrace.md +0 -6
  138. package/public/vendor/vitest-docs/config/projects.md +0 -6
  139. package/public/vendor/vitest-docs/config/provide.md +0 -45
  140. package/public/vendor/vitest-docs/config/reporters.md +0 -69
  141. package/public/vendor/vitest-docs/config/resolvesnapshotpath.md +0 -36
  142. package/public/vendor/vitest-docs/config/restoremocks.md +0 -22
  143. package/public/vendor/vitest-docs/config/retry.md +0 -140
  144. package/public/vendor/vitest-docs/config/root.md +0 -6
  145. package/public/vendor/vitest-docs/config/runner.md +0 -6
  146. package/public/vendor/vitest-docs/config/sequence.md +0 -158
  147. package/public/vendor/vitest-docs/config/server.md +0 -68
  148. package/public/vendor/vitest-docs/config/setupfiles.md +0 -40
  149. package/public/vendor/vitest-docs/config/silent.md +0 -9
  150. package/public/vendor/vitest-docs/config/slowtestthreshold.md +0 -7
  151. package/public/vendor/vitest-docs/config/snapshotenvironment.md +0 -27
  152. package/public/vendor/vitest-docs/config/snapshotformat.md +0 -28
  153. package/public/vendor/vitest-docs/config/snapshotserializers.md +0 -6
  154. package/public/vendor/vitest-docs/config/stricttags.md +0 -30
  155. package/public/vendor/vitest-docs/config/tags.md +0 -141
  156. package/public/vendor/vitest-docs/config/teardowntimeout.md +0 -7
  157. package/public/vendor/vitest-docs/config/testnamepattern.md +0 -21
  158. package/public/vendor/vitest-docs/config/testtimeout.md +0 -7
  159. package/public/vendor/vitest-docs/config/typecheck.md +0 -77
  160. package/public/vendor/vitest-docs/config/ui.md +0 -15
  161. package/public/vendor/vitest-docs/config/unstubenvs.md +0 -20
  162. package/public/vendor/vitest-docs/config/unstubglobals.md +0 -20
  163. package/public/vendor/vitest-docs/config/update.md +0 -16
  164. package/public/vendor/vitest-docs/config/vmmemorylimit.md +0 -30
  165. package/public/vendor/vitest-docs/config/watch.md +0 -11
  166. package/public/vendor/vitest-docs/config/watchtriggerpatterns.md +0 -29
  167. package/public/vendor/vitest-docs/guide/advanced/index.md +0 -147
  168. package/public/vendor/vitest-docs/guide/advanced/pool.md +0 -148
  169. package/public/vendor/vitest-docs/guide/advanced/reporters.md +0 -93
  170. package/public/vendor/vitest-docs/guide/advanced/tests.md +0 -125
  171. package/public/vendor/vitest-docs/guide/browser/aria-snapshots.md +0 -470
  172. package/public/vendor/vitest-docs/guide/browser/component-testing.md +0 -571
  173. package/public/vendor/vitest-docs/guide/browser/index.md +0 -630
  174. package/public/vendor/vitest-docs/guide/browser/multiple-setups.md +0 -121
  175. package/public/vendor/vitest-docs/guide/browser/trace-view.md +0 -126
  176. package/public/vendor/vitest-docs/guide/browser/visual-regression-testing.md +0 -734
  177. package/public/vendor/vitest-docs/guide/cli-generated.md +0 -972
  178. package/public/vendor/vitest-docs/guide/cli.md +0 -234
  179. package/public/vendor/vitest-docs/guide/common-errors.md +0 -163
  180. package/public/vendor/vitest-docs/guide/coverage.md +0 -515
  181. package/public/vendor/vitest-docs/guide/debugging.md +0 -127
  182. package/public/vendor/vitest-docs/guide/environment.md +0 -101
  183. package/public/vendor/vitest-docs/guide/extending-matchers.md +0 -160
  184. package/public/vendor/vitest-docs/guide/features.md +0 -310
  185. package/public/vendor/vitest-docs/guide/filtering.md +0 -175
  186. package/public/vendor/vitest-docs/guide/ide.md +0 -43
  187. package/public/vendor/vitest-docs/guide/improving-performance.md +0 -245
  188. package/public/vendor/vitest-docs/guide/in-source.md +0 -159
  189. package/public/vendor/vitest-docs/guide/index.md +0 -128
  190. package/public/vendor/vitest-docs/guide/learn/async.md +0 -147
  191. package/public/vendor/vitest-docs/guide/learn/debugging-tests.md +0 -210
  192. package/public/vendor/vitest-docs/guide/learn/matchers.md +0 -277
  193. package/public/vendor/vitest-docs/guide/learn/mock-functions.md +0 -277
  194. package/public/vendor/vitest-docs/guide/learn/setup-teardown.md +0 -240
  195. package/public/vendor/vitest-docs/guide/learn/snapshots.md +0 -166
  196. package/public/vendor/vitest-docs/guide/learn/testing-in-practice.md +0 -430
  197. package/public/vendor/vitest-docs/guide/learn/writing-tests-with-ai.md +0 -127
  198. package/public/vendor/vitest-docs/guide/learn/writing-tests.md +0 -231
  199. package/public/vendor/vitest-docs/guide/lifecycle.md +0 -379
  200. package/public/vendor/vitest-docs/guide/migration.md +0 -863
  201. package/public/vendor/vitest-docs/guide/mocking/classes.md +0 -158
  202. package/public/vendor/vitest-docs/guide/mocking/dates.md +0 -52
  203. package/public/vendor/vitest-docs/guide/mocking/file-system.md +0 -74
  204. package/public/vendor/vitest-docs/guide/mocking/functions.md +0 -61
  205. package/public/vendor/vitest-docs/guide/mocking/globals.md +0 -20
  206. package/public/vendor/vitest-docs/guide/mocking/modules.md +0 -414
  207. package/public/vendor/vitest-docs/guide/mocking/requests.md +0 -114
  208. package/public/vendor/vitest-docs/guide/mocking/timers.md +0 -48
  209. package/public/vendor/vitest-docs/guide/mocking.md +0 -239
  210. package/public/vendor/vitest-docs/guide/open-telemetry.md +0 -156
  211. package/public/vendor/vitest-docs/guide/parallelism.md +0 -82
  212. package/public/vendor/vitest-docs/guide/profiling-test-performance.md +0 -243
  213. package/public/vendor/vitest-docs/guide/projects.md +0 -291
  214. package/public/vendor/vitest-docs/guide/recipes.md +0 -59
  215. package/public/vendor/vitest-docs/guide/reporters.md +0 -723
  216. package/public/vendor/vitest-docs/guide/snapshot.md +0 -620
  217. package/public/vendor/vitest-docs/guide/test-annotations.md +0 -103
  218. package/public/vendor/vitest-docs/guide/test-context.md +0 -902
  219. package/public/vendor/vitest-docs/guide/test-tags.md +0 -314
  220. package/public/vendor/vitest-docs/guide/testing-types.md +0 -149
  221. package/public/vendor/vitest-docs/guide/ui.md +0 -160
  222. package/public/vendor/vitest-docs/guide/using-plugins.md +0 -5
  223. package/public/vendor/vitest-docs/manifest.json +0 -1691
  224. package/resources/index.js +0 -166
  225. package/resources/indexes.js +0 -77
  226. package/resources/manifest-schema.js +0 -46
  227. package/resources/paths.js +0 -20
  228. package/resources/patterns.js +0 -22
  229. package/resources/upstream-docs.js +0 -22
@@ -1,684 +0,0 @@
1
- # Vitest
2
-
3
- Vitest instance requires the current test mode. It can be either:
4
-
5
- - `test` when running runtime tests
6
- - `benchmark` when running benchmarks <Badge type="warning">experimental</Badge>
7
-
8
- ::: details New in Vitest 4
9
- Vitest 4 added several new APIs (they are marked with a "4.0.0+" badge) and removed deprecated APIs:
10
-
11
- - `invalidates`
12
- - `changedTests` (use [`onFilterWatchedSpecification`](#onfilterwatchedspecification) instead)
13
- - `server` (use [`vite`](#vite) instead)
14
- - `getProjectsByTestFile` (use [`getModuleSpecifications`](#getmodulespecifications) instead)
15
- - `getFileWorkspaceSpecs` (use [`getModuleSpecifications`](#getmodulespecifications) instead)
16
- - `getModuleProjects` (filter by [`this.projects`](#projects) yourself)
17
- - `updateLastChanged` (renamed to [`invalidateFile`](#invalidatefile))
18
- - `globTestSpecs` (use [`globTestSpecifications`](#globtestspecifications) instead)
19
- - `globTestFiles` (use [`globTestSpecifications`](#globtestspecifications) instead)
20
- - `listFile` (use [`getRelevantTestSpecifications`](#getrelevanttestspecifications) instead)
21
- :::
22
-
23
- ## mode
24
-
25
- ### test
26
-
27
- Test mode will only call functions inside `test` or `it`, and throws an error when `bench` is encountered. This mode uses `include` and `exclude` options in the config to find test files.
28
-
29
- ### benchmark <Badge type="warning">experimental</Badge>
30
-
31
- Benchmark mode calls `bench` functions and throws an error, when it encounters `test` or `it`. This mode uses `benchmark.include` and `benchmark.exclude` options in the config to find benchmark files.
32
-
33
- ## config
34
-
35
- The root (or global) config. If projects are defined, they will reference this as `globalConfig`.
36
-
37
- ::: warning
38
- This is Vitest config, it doesn't extend _Vite_ config. It only has resolved values from the `test` property.
39
- :::
40
-
41
- ## vite
42
-
43
- This is a global [`ViteDevServer`](https://vite.dev/guide/api-javascript#vitedevserver).
44
-
45
- ## state <Badge type="warning">experimental</Badge>
46
-
47
- ::: warning
48
- Public `state` is an experimental API (except `vitest.state.getReportedEntity`). Breaking changes might not follow SemVer, please pin Vitest's version when using it.
49
- :::
50
-
51
- Global state stores information about the current tests. It uses the same API from `@vitest/runner` by default, but we recommend using the [Reported Tasks API](/api/advanced/reporters#reported-tasks) instead by calling `state.getReportedEntity()` on the `@vitest/runner` API:
52
-
53
- ```ts
54
- const task = vitest.state.idMap.get(taskId) // old API
55
- const testCase = vitest.state.getReportedEntity(task) // new API
56
- ```
57
-
58
- In the future, the old API won't be exposed anymore.
59
-
60
- ## snapshot
61
-
62
- The global snapshot manager. Vitest keeps track of all snapshots using the `snapshot.add` method.
63
-
64
- You can get the latest summary of snapshots via the `vitest.snapshot.summary` property.
65
-
66
- ## cache
67
-
68
- Cache manager that stores information about latest test results and test file stats. In Vitest itself this is only used by the default sequencer to sort tests.
69
-
70
- ## watcher <Version>4.0.0</Version> {#watcher}
71
-
72
- The instance of a Vitest watcher with useful methods to track file changes and rerun tests. You can use `onFileChange`, `onFileDelete` or `onFileCreate` with your own watcher, if the built-in watcher is disabled.
73
-
74
- ## projects
75
-
76
- An array of [test projects](/api/advanced/test-project) that belong to user's projects. If the user did not specify a them, this array will only contain a [root project](#getrootproject).
77
-
78
- Vitest will ensure that there is always at least one project in this array. If the user specifies a non-existent `--project` name, Vitest will throw an error before this array is defined.
79
-
80
- ## getRootProject
81
-
82
- ```ts
83
- function getRootProject(): TestProject
84
- ```
85
-
86
- This returns the root test project. The root project generally doesn't run any tests and is not included in `vitest.projects` unless the user explicitly includes the root config in their configuration, or projects are not defined at all.
87
-
88
- The primary goal of the root project is to setup the global config. In fact, `rootProject.config` references `rootProject.globalConfig` and `vitest.config` directly:
89
-
90
- ```ts
91
- rootProject.config === rootProject.globalConfig === rootProject.vitest.config
92
- ```
93
-
94
- ## provide
95
-
96
- ```ts
97
- function provide<T extends keyof ProvidedContext & string>(
98
- key: T,
99
- value: ProvidedContext[T],
100
- ): void
101
- ```
102
-
103
- Vitest exposes `provide` method which is a shorthand for `vitest.getRootProject().provide`. With this method you can pass down values from the main thread to tests. All values are checked with `structuredClone` before they are stored, but the values themselves are not cloned.
104
-
105
- To receive the values in the test, you need to import `inject` method from `vitest` entrypoint:
106
-
107
- ```ts
108
- import { inject } from 'vitest'
109
- const port = inject('wsPort') // 3000
110
- ```
111
-
112
- For better type safety, we encourage you to augment the type of `ProvidedContext`:
113
-
114
- ```ts
115
- import { createVitest } from 'vitest/node'
116
-
117
- const vitest = await createVitest('test', {
118
- watch: false,
119
- })
120
- vitest.provide('wsPort', 3000)
121
-
122
- declare module 'vitest' {
123
- export interface ProvidedContext {
124
- wsPort: number
125
- }
126
- }
127
- ```
128
-
129
- ::: warning
130
- Technically, `provide` is a method of [`TestProject`](/api/advanced/test-project), so it is limited to the specific project. However, all projects inherit the values from the root project which makes `vitest.provide` universal way of passing down values to tests.
131
- :::
132
-
133
- ## getProvidedContext
134
-
135
- ```ts
136
- function getProvidedContext(): ProvidedContext
137
- ```
138
-
139
- This returns the root context object. This is a shorthand for `vitest.getRootProject().getProvidedContext`.
140
-
141
- ## getProjectByName
142
-
143
- ```ts
144
- function getProjectByName(name: string): TestProject
145
- ```
146
-
147
- This method returns the project by its name. Similar to calling `vitest.projects.find`.
148
-
149
- ::: warning
150
- In case the project doesn't exist, this method will return the root project - make sure to check the names again if the project you are looking for is the one returned.
151
-
152
- If user didn't customize a name, the Vitest will assign an empty string as a name.
153
- :::
154
-
155
- ## globTestSpecifications
156
-
157
- ```ts
158
- function globTestSpecifications(
159
- filters?: string[],
160
- ): Promise<TestSpecification[]>
161
- ```
162
-
163
- This method constructs new [test specifications](/api/advanced/test-specification) by collecting every test in all projects with [`project.globTestFiles`](/api/advanced/test-project#globtestfiles). It accepts string filters to match the test files - these are the same filters that [CLI supports](/guide/filtering#cli).
164
-
165
- This method automatically caches all test specifications. When you call [`getModuleSpecifications`](#getmodulespecifications) next time, it will return the same specifications unless [`clearSpecificationsCache`](#clearspecificationscache) was called before that.
166
-
167
- ::: warning
168
- As of Vitest 3, it's possible to have multiple test specifications with the same module ID (file path) if `poolMatchGlob` has several pools or if `typecheck` is enabled. This possibility will be removed in Vitest 4.
169
- :::
170
-
171
- ```ts
172
- const specifications = await vitest.globTestSpecifications(['my-filter'])
173
- // [TestSpecification{ moduleId: '/tests/my-filter.test.ts' }]
174
- console.log(specifications)
175
- ```
176
-
177
- ## getRelevantTestSpecifications
178
-
179
- ```ts
180
- function getRelevantTestSpecifications(
181
- filters?: string[]
182
- ): Promise<TestSpecification[]>
183
- ```
184
-
185
- This method resolves every test specification by calling [`project.globTestFiles`](/api/advanced/test-project#globtestfiles). It accepts string filters to match the test files - these are the same filters that [CLI supports](/guide/filtering#cli). If `--changed` flag was specified, the list will be filtered to include only files that changed. `getRelevantTestSpecifications` doesn't run any test files.
186
-
187
- ::: warning
188
- This method can be slow because it needs to filter `--changed` flags. Do not use it if you just need a list of test files.
189
-
190
- - If you need to get the list of specifications for known test files, use [`getModuleSpecifications`](#getmodulespecifications) instead.
191
- - If you need to get the list of all possible test files, use [`globTestSpecifications`](#globtestspecifications).
192
- :::
193
-
194
- ## mergeReports
195
-
196
- ```ts
197
- function mergeReports(directory?: string): Promise<TestRunResult>
198
- ```
199
-
200
- Merge reports from multiple runs located in the specified directory (value from `--merge-reports` if not specified). This value can also be set on `config.mergeReports` (by default, it will read `.vitest-reports` folder).
201
-
202
- Note that the `directory` will always be resolved relative to the working directory.
203
-
204
- This method is called automatically by [`startVitest`](/guide/advanced/tests) if `config.mergeReports` is set.
205
-
206
- ## collect
207
-
208
- ```ts
209
- function collect(filters?: string[]): Promise<TestRunResult>
210
- ```
211
-
212
- Execute test files without running test callbacks. `collect` returns unhandled errors and an array of [test modules](/api/advanced/test-module). It accepts string filters to match the test files - these are the same filters that [CLI supports](/guide/filtering#cli).
213
-
214
- This method resolves tests specifications based on the config `include`, `exclude`, and `includeSource` values. Read more at [`project.globTestFiles`](/api/advanced/test-project#globtestfiles). If `--changed` flag was specified, the list will be filtered to include only files that changed.
215
-
216
- ::: warning
217
- Note that Vitest doesn't use static analysis to collect tests. Vitest will run every test file in isolation, just like it runs regular tests.
218
-
219
- This makes this method very slow, unless you disable isolation before collecting tests.
220
- :::
221
-
222
- ## start
223
-
224
- ```ts
225
- function start(filters?: string[]): Promise<TestRunResult>
226
- ```
227
-
228
- Initialize reporters, the coverage provider, and run tests. This method accepts string filters to match the test files - these are the same filters that [CLI supports](/guide/filtering#cli).
229
-
230
- ::: warning
231
- This method should not be called if [`vitest.standalone()`](#standalone) is also invoked. Use [`runTestSpecifications`](#runtestspecifications) or [`rerunTestSpecifications`](#reruntestspecifications) instead if you need to run tests after Vitest was initialised.
232
- :::
233
-
234
- This method is called automatically by [`startVitest`](/guide/advanced/tests) if `config.mergeReports` and `config.standalone` are not set.
235
-
236
- ## standalone <Version type="experimental">4.1.1</Version> {#standalone}
237
-
238
- ```ts
239
- function standalone(): Promise<void>
240
- ```
241
-
242
- - **Alias:** `init` <Deprecated />
243
-
244
- Initialize reporters and the coverage provider. This method doesn't run any tests. If the `--watch` flag is provided, Vitest will still run changed tests even if this method was not called.
245
-
246
- Internally, this method is called only if [`--standalone`](/guide/cli#standalone) flag is enabled.
247
-
248
- ::: warning
249
- This method should not be called if [`vitest.start()`](#start) is also invoked.
250
- :::
251
-
252
- This method is called automatically by [`startVitest`](/guide/advanced/tests) if `config.standalone` is set.
253
-
254
- ## getModuleSpecifications
255
-
256
- ```ts
257
- function getModuleSpecifications(moduleId: string): TestSpecification[]
258
- ```
259
-
260
- Returns a list of test specifications related to the module ID. The ID should already be resolved to an absolute file path. If ID doesn't match `include` or `includeSource` patterns, the returned array will be empty.
261
-
262
- This method can return already cached specifications based on the `moduleId` and `pool`. But note that [`project.createSpecification`](/api/advanced/test-project#createspecification) always returns a new instance and it's not cached automatically. However, specifications are automatically cached when [`runTestSpecifications`](#runtestspecifications) is called.
263
-
264
- ::: warning
265
- As of Vitest 3, this method uses a cache to check if the file is a test. To make sure that the cache is not empty, call [`globTestSpecifications`](#globtestspecifications) at least once.
266
- :::
267
-
268
- ## clearSpecificationsCache
269
-
270
- ```ts
271
- function clearSpecificationsCache(moduleId?: string): void
272
- ```
273
-
274
- Vitest automatically caches test specifications for each file when [`globTestSpecifications`](#globtestspecifications) or [`runTestSpecifications`](#runtestspecifications) is called. This method clears the cache for the given file or the whole cache altogether depending on the first argument.
275
-
276
- ## runTestSpecifications
277
-
278
- ```ts
279
- function runTestSpecifications(
280
- specifications: TestSpecification[],
281
- allTestsRun = false
282
- ): Promise<TestRunResult>
283
- ```
284
-
285
- This method runs every test based on the received [specifications](/api/advanced/test-specification). The second argument, `allTestsRun`, is used by the coverage provider to determine if it needs to include uncovered files in report.
286
-
287
- ::: warning
288
- This method doesn't trigger `onWatcherRerun`, `onWatcherStart` and `onTestsRerun` callbacks. If you are rerunning tests based on the file change, consider using [`rerunTestSpecifications`](#reruntestspecifications) instead.
289
- :::
290
-
291
- ## rerunTestSpecifications
292
-
293
- ```ts
294
- function rerunTestSpecifications(
295
- specifications: TestSpecification[],
296
- allTestsRun = false
297
- ): Promise<TestRunResult>
298
- ```
299
-
300
- This method emits `reporter.onWatcherRerun` and `onTestsRerun` events, then it runs tests with [`runTestSpecifications`](#runtestspecifications). If there were no errors in the main process, it will emit `reporter.onWatcherStart` event.
301
-
302
- ## runTestFiles <Version>4.1.0</Version> {#runtestfiles}
303
-
304
- ```ts
305
- function runTestFiles(
306
- filepaths: string[],
307
- allTestsRun = false
308
- ): Promise<TestRunResult>
309
- ```
310
-
311
- This automatically creates specifications to run based on filepaths filters.
312
-
313
- This is different from [`start`](#start) because it does not create a coverage provider, trigger `onInit` and `onWatcherStart` events, or throw an error if there are no files to run (in this case, the function will return empty arrays without triggering a test run).
314
-
315
- This function accepts the same filters as [`start`](#start) and the CLI.
316
-
317
- ## updateSnapshot
318
-
319
- ```ts
320
- function updateSnapshot(files?: string[]): Promise<TestRunResult>
321
- ```
322
-
323
- Update snapshots in specified files. If no files are provided, it will update files with failed tests and obsolete snapshots.
324
-
325
- ## collectTests
326
-
327
- ```ts
328
- function collectTests(
329
- specifications: TestSpecification[]
330
- ): Promise<TestRunResult>
331
- ```
332
-
333
- Execute test files without running test callbacks. `collectTests` returns unhandled errors and an array of [test modules](/api/advanced/test-module).
334
-
335
- This method works exactly the same as [`collect`](#collect), but you need to provide test specifications yourself.
336
-
337
- ::: warning
338
- Note that Vitest doesn't use static analysis to collect tests. Vitest will run every test file in isolation, just like it runs regular tests.
339
-
340
- This makes this method very slow, unless you disable isolation before collecting tests.
341
- :::
342
-
343
- ## cancelCurrentRun
344
-
345
- ```ts
346
- function cancelCurrentRun(reason: CancelReason): Promise<void>
347
- ```
348
-
349
- This method will gracefully cancel all ongoing tests. It will stop the on-going tests and will not run tests that were scheduled to run but haven't started yet.
350
-
351
- ## setGlobalTestNamePattern
352
-
353
- ```ts
354
- function setGlobalTestNamePattern(pattern: string | RegExp): void
355
- ```
356
-
357
- This methods overrides the global [test name pattern](/config/testnamepattern).
358
-
359
- ::: warning
360
- This method doesn't start running any tests. To run tests with updated pattern, call [`runTestSpecifications`](#runtestspecifications).
361
- :::
362
-
363
- ## getGlobalTestNamePattern <Version>4.0.0</Version> {#getglobaltestnamepattern}
364
-
365
- ```ts
366
- function getGlobalTestNamePattern(): RegExp | undefined
367
- ```
368
-
369
- Returns the regexp used for the global test name pattern.
370
-
371
- ## resetGlobalTestNamePattern
372
-
373
- ```ts
374
- function resetGlobalTestNamePattern(): void
375
- ```
376
-
377
- This methods resets the [test name pattern](/config/testnamepattern). It means Vitest won't skip any tests now.
378
-
379
- ::: warning
380
- This method doesn't start running any tests. To run tests without a pattern, call [`runTestSpecifications`](#runtestspecifications).
381
- :::
382
-
383
- ## enableSnapshotUpdate
384
-
385
- ```ts
386
- function enableSnapshotUpdate(): void
387
- ```
388
-
389
- Enable the mode that allows updating snapshots when running tests. Every test that runs after this method is called will update snapshots. To disable the mode, call [`resetSnapshotUpdate`](#resetsnapshotupdate).
390
-
391
- ::: warning
392
- This method doesn't start running any tests. To update snapshots, run tests with [`runTestSpecifications`](#runtestspecifications).
393
- :::
394
-
395
- ## resetSnapshotUpdate
396
-
397
- ```ts
398
- function resetSnapshotUpdate(): void
399
- ```
400
-
401
- Disable the mode that allows updating snapshots when running tests. This method doesn't start running any tests.
402
-
403
- ## invalidateFile
404
-
405
- ```ts
406
- function invalidateFile(filepath: string): void
407
- ```
408
-
409
- This method invalidates the file in the cache of every project. It is mostly useful if you rely on your own watcher because Vite's cache persist in memory.
410
-
411
- ::: danger
412
- If you disable Vitest's watcher but keep Vitest running, it is important to manually clear the cache with this method because there is no way to disable the cache. This method will also invalidate file's importers.
413
- :::
414
-
415
- ## import
416
-
417
- <!--@include: ./import-example.md-->
418
-
419
- Import a file using Vite module runner. The file will be transformed by Vite with the global config and executed in a separate context. Note that `moduleId` will be relative to the `config.root`.
420
-
421
- ::: danger
422
- `project.import` reuses Vite's module graph, so importing the same module using a regular import will return a different module:
423
-
424
- ```ts
425
- import * as staticExample from './example.js'
426
- const dynamicExample = await vitest.import('./example.js')
427
-
428
- dynamicExample !== staticExample // ✅
429
- ```
430
- :::
431
-
432
- ::: info
433
- Internally, Vitest uses this method to import global setups, custom coverage providers, and custom reporters, meaning all of them share the same module graph as long as they belong to the same Vite server.
434
- :::
435
-
436
- ## close
437
-
438
- ```ts
439
- function close(): Promise<void>
440
- ```
441
-
442
- Closes all projects and their associated resources. This can only be called once; the closing promise is cached until the server restarts.
443
-
444
- ## exit
445
-
446
- ```ts
447
- function exit(force = false): Promise<void>
448
- ```
449
-
450
- Closes all projects and exit the process. If `force` is set to `true`, the process will exit immediately after closing the projects.
451
-
452
- This method will also forcefully call `process.exit()` if the process is still active after [`config.teardownTimeout`](/config/teardowntimeout) milliseconds.
453
-
454
- ## shouldKeepServer
455
-
456
- ```ts
457
- function shouldKeepServer(): boolean
458
- ```
459
-
460
- This method will return `true` if the server should be kept running after the tests are done. This usually means that the `watch` mode was enabled.
461
-
462
- ## onServerRestart
463
-
464
- ```ts
465
- function onServerRestart(fn: OnServerRestartHandler): void
466
- ```
467
-
468
- Register a handler that will be called when the server is restarted due to a config change.
469
-
470
- ## onCancel
471
-
472
- ```ts
473
- function onCancel(fn: (reason: CancelReason) => Awaitable<void>): () => void
474
- ```
475
-
476
- Register a handler that will be called when the test run is cancelled with [`vitest.cancelCurrentRun`](#cancelcurrentrun).
477
-
478
- Since 4.0.10, `onCancel` experimentally returns a teardown function that will remove the listener. Since 4.1.0 this behaviour is considered stable.
479
-
480
- ## onClose
481
-
482
- ```ts
483
- function onClose(fn: () => Awaitable<void>): void
484
- ```
485
-
486
- Register a handler that will be called when the server is closed.
487
-
488
- ## onTestsRerun
489
-
490
- ```ts
491
- function onTestsRerun(fn: OnTestsRerunHandler): void
492
- ```
493
-
494
- Register a handler that will be called when the tests are rerunning. The tests can rerun when [`rerunTestSpecifications`](#reruntestspecifications) is called manually or when a file is changed and the built-in watcher schedules a rerun.
495
-
496
- ## onFilterWatchedSpecification
497
-
498
- ```ts
499
- function onFilterWatchedSpecification(
500
- fn: (specification: TestSpecification) => boolean
501
- ): void
502
- ```
503
- Register a handler that will be called when a file is changed. This callback should return `true` or `false`, indicating whether the test file needs to be rerun.
504
-
505
- With this method, you can hook into the default watcher logic to delay or discard tests that the user doesn't want to keep track of at the moment:
506
-
507
- ```ts
508
- const continuesTests: string[] = []
509
-
510
- myCustomWrapper.onContinuesRunEnabled(testItem =>
511
- continuesTests.push(item.fsPath)
512
- )
513
-
514
- vitest.onFilterWatchedSpecification(specification =>
515
- continuesTests.includes(specification.moduleId)
516
- )
517
- ```
518
-
519
- Vitest can create different specifications for the same file depending on the `pool` or `locations` options, so do not rely on the reference. Vitest can also return cached specification from [`vitest.getModuleSpecifications`](#getmodulespecifications) - the cache is based on the `moduleId` and `pool`. Note that [`project.createSpecification`](/api/advanced/test-project#createspecification) always returns a new instance.
520
-
521
- ## matchesProjectFilter <Version>3.1.0</Version> {#matchesprojectfilter}
522
-
523
- ```ts
524
- function matchesProjectFilter(name: string): boolean
525
- ```
526
-
527
- Check if the name matches the current [project filter](/guide/cli#project). If there is no project filter, this will always return `true`.
528
-
529
- It is not possible to programmatically change the `--project` CLI option.
530
-
531
- ## waitForTestRunEnd <Version>4.0.0</Version> {#waitfortestrunend}
532
-
533
- ```ts
534
- function waitForTestRunEnd(): Promise<void>
535
- ```
536
-
537
- If there is a test run happening, returns a promise that will resolve when the test run is finished.
538
-
539
- ## createCoverageProvider <Version>4.0.0</Version> {#createcoverageprovider}
540
-
541
- ```ts
542
- function createCoverageProvider(): Promise<CoverageProvider | null>
543
- ```
544
-
545
- Creates a coverage provider if `coverage` is enabled in the config. This is done automatically if you are running tests with [`start`](#start) or [`standalone`](#standalone) methods.
546
-
547
- ::: warning
548
- This method will also clean all previous reports if [`coverage.clean`](/config/coverage#coverage-clean) is not set to `false`.
549
- :::
550
-
551
- ## enableCoverage <Version>4.0.0</Version> {#enablecoverage}
552
-
553
- ```ts
554
- function enableCoverage(): Promise<void>
555
- ```
556
-
557
- This method enables coverage for tests that run after this call. `enableCoverage` doesn't run any tests; it only sets up Vitest to collect coverage.
558
-
559
- It creates a new coverage provider if one doesn't already exist.
560
-
561
- ## disableCoverage <Version>4.0.0</Version> {#disablecoverage}
562
-
563
- ```ts
564
- function disableCoverage(): void
565
- ```
566
-
567
- This method disables coverage collection for tests that run afterwards.
568
-
569
- ## getSeed <Version>4.0.0</Version> {#getseed}
570
-
571
- ```ts
572
- function getSeed(): number | null
573
- ```
574
-
575
- Returns the seed, if tests are running in a random order.
576
-
577
- ## experimental_parseSpecification <Version type="experimental">4.0.0</Version> <Experimental /> {#parsespecification}
578
-
579
- ```ts
580
- function experimental_parseSpecification(
581
- specification: TestSpecification
582
- ): Promise<TestModule>
583
- ```
584
-
585
- This function will collect all tests inside the file without running it. It uses rollup's `parseAst` function on top of Vite's `ssrTransform` to statically analyse the file and collect all tests that it can.
586
-
587
- ::: warning
588
- If Vitest could not analyse the name of the test, it will inject a `dynamic: true` property to the test or a suite. The `id` will also have a postfix with `-dynamic` to not break tests that were collected properly.
589
-
590
- Vitest always injects this property in tests with `for` or `each` modifier or tests with a dynamic name (like, `hello ${property}` or `'hello' + ${property}`). Vitest will still assign a name to the test, but it cannot be used to filter tests.
591
-
592
- There is nothing Vitest can do to make it possible to filter dynamic tests, but you can turn a test with `for` or `each` modifier into a name pattern with `escapeTestName` function:
593
-
594
- ```ts
595
- import { escapeTestName } from 'vitest/node'
596
-
597
- // turns into /hello, .+?/
598
- const escapedPattern = new RegExp(escapeTestName('hello, %s', true))
599
- ```
600
- :::
601
-
602
- ::: warning
603
- Vitest will only collect tests defined in the file. It will never follow imports to other files.
604
-
605
- Vitest collects all `it`, `test`, `suite` and `describe` definitions even if they were not imported from the `vitest` entry point.
606
- :::
607
-
608
- ## experimental_parseSpecifications <Version type="experimental">4.0.0</Version> <Experimental /> {#parsespecifications}
609
-
610
- ```ts
611
- function experimental_parseSpecifications(
612
- specifications: TestSpecification[],
613
- options?: {
614
- concurrency?: number
615
- }
616
- ): Promise<TestModule[]>
617
- ```
618
-
619
- This method will [collect tests](#parsespecification) from an array of specifications. By default, Vitest will run only `os.availableParallelism()` number of specifications at a time to reduce the potential performance degradation. You can specify a different number in a second argument.
620
-
621
- ## experimental_clearCache <Version type="experimental">4.0.11</Version> <Experimental /> {#clearcache}
622
-
623
- ```ts
624
- function experimental_clearCache(): Promise<void>
625
- ```
626
-
627
- Deletes all Vitest caches, including [`experimental.fsModuleCache`](/config/experimental#experimental-fsmodulecache).
628
-
629
- ## experimental_getSourceModuleDiagnostic <Version type="experimental">4.0.15</Version> <Experimental /> {#getsourcemodulediagnostic}
630
-
631
- ```ts
632
- export function experimental_getSourceModuleDiagnostic(
633
- moduleId: string,
634
- testModule?: TestModule,
635
- ): Promise<SourceModuleDiagnostic>
636
- ```
637
-
638
- ::: details Types
639
- ```ts
640
- export interface ModuleDefinitionLocation {
641
- line: number
642
- column: number
643
- }
644
-
645
- export interface SourceModuleLocations {
646
- modules: ModuleDefinitionDiagnostic[]
647
- untracked: ModuleDefinitionDiagnostic[]
648
- }
649
-
650
- export interface ModuleDefinitionDiagnostic {
651
- start: ModuleDefinitionLocation
652
- end: ModuleDefinitionLocation
653
- startIndex: number
654
- endIndex: number
655
- url: string
656
- resolvedId: string
657
- }
658
-
659
- export interface ModuleDefinitionDurationsDiagnostic extends ModuleDefinitionDiagnostic {
660
- selfTime: number
661
- totalTime: number
662
- external?: boolean
663
- }
664
-
665
- export interface UntrackedModuleDefinitionDiagnostic {
666
- url: string
667
- resolvedId: string
668
- selfTime: number
669
- totalTime: number
670
- external?: boolean
671
- }
672
-
673
- export interface SourceModuleDiagnostic {
674
- modules: ModuleDefinitionDurationsDiagnostic[]
675
- untrackedModules: UntrackedModuleDefinitionDiagnostic[]
676
- }
677
- ```
678
- :::
679
-
680
- Returns module's diagnostic. If [`testModule`](/api/advanced/test-module) is not provided, `selfTime` and `totalTime` will be aggregated across all tests that were running the last time. If the module was not transformed or executed, the diagnostic will be empty.
681
-
682
- ::: warning
683
- At the moment, the [browser](/guide/browser/) modules are not supported.
684
- :::