feat(api): expose Vitest watcher (#8413)

sheremet-va · web-flow · commit aaa6e651259c · 2025-08-08T14:43:02.000+02:00
diff --git a/docs/advanced/api/vitest.md b/docs/advanced/api/vitest.md
@@ -99,6 +99,10 @@ You can get the latest summary of snapshots via the `vitest.snapshot.summary` pr
 
 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.
 
+## watcher <Version>4.0.0</Version> {#watcher}
+
+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.
+
 ## projects
 
 An array of [test projects](/advanced/api/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).
diff --git a/packages/vitest/src/node/core.ts b/packages/vitest/src/node/core.ts
@@ -84,6 +84,14 @@ export class Vitest {
    * If projects were filtered with `--project` flag, they won't appear here.
    */
   public projects: TestProject[] = []
+  /**
+   * A watcher handler. This is not the file system watcher. The handler only
+   * exposes methods to handle changed files.
+   *
+   * If you have your own watcher, you can use these methods to replicate
+   * Vitest behaviour.
+   */
+  public readonly watcher: VitestWatcher
 
   /** @internal */ configOverride: Partial<ResolvedConfig> = {}
   /** @internal */ coverageProvider: CoverageProvider | null | undefined
@@ -103,7 +111,6 @@ export class Vitest {
   private restartsCount = 0
 
   private readonly specifications: VitestSpecifications
-  private readonly watcher: VitestWatcher
   private pool: ProcessPool | undefined
   private _config?: ResolvedConfig
   private _vite?: ViteDevServer
@@ -121,7 +128,7 @@ export class Vitest {
     this.packageInstaller = options.packageInstaller || new VitestPackageInstaller()
     this.specifications = new VitestSpecifications(this)
     this.watcher = new VitestWatcher(this).onWatcherRerun(file =>
-      this.scheduleRerun([file]), // TODO: error handling
+      this.scheduleRerun(file), // TODO: error handling
     )
   }
 
@@ -1013,8 +1020,7 @@ export class Vitest {
   }
 
   private _rerunTimer: any
-  // we can't use a single `triggerId` yet because vscode extension relies on this
-  private async scheduleRerun(triggerId: string[]): Promise<void> {
+  private async scheduleRerun(triggerId: string): Promise<void> {
     const currentCount = this.restartsCount
     clearTimeout(this._rerunTimer)
     await this.runningPromise
@@ -1053,8 +1059,7 @@ export class Vitest {
 
       this.watcher.changedTests.clear()
 
-      const triggerIds = new Set(triggerId.map(id => relative(this.config.root, id)))
-      const triggerLabel = Array.from(triggerIds).join(', ')
+      const triggerLabel = relative(this.config.root, triggerId)
       // get file specifications and filter them if needed
       const specifications = files.flatMap(file => this.getModuleSpecifications(file)).filter((specification) => {
         if (this._onFilterWatchedSpecification.length === 0) {
diff --git a/packages/vitest/src/node/watcher.ts b/packages/vitest/src/node/watcher.ts
@@ -38,14 +38,14 @@ export class VitestWatcher {
       watcher.add(this.vitest.config.forceRerunTriggers)
     }
 
-    watcher.on('change', this.onChange)
-    watcher.on('unlink', this.onUnlink)
-    watcher.on('add', this.onAdd)
+    watcher.on('change', this.onFileChange)
+    watcher.on('unlink', this.onFileDelete)
+    watcher.on('add', this.onFileCreate)
 
     this.unregisterWatcher = () => {
-      watcher.off('change', this.onChange)
-      watcher.off('unlink', this.onUnlink)
-      watcher.off('add', this.onAdd)
+      watcher.off('change', this.onFileChange)
+      watcher.off('unlink', this.onFileDelete)
+      watcher.off('add', this.onFileCreate)
       this.unregisterWatcher = noop
     }
     return this
@@ -77,7 +77,7 @@ export class VitestWatcher {
     return triggered
   }
 
-  private onChange = (id: string): void => {
+  public onFileChange = (id: string): void => {
     id = slash(id)
     this.vitest.logger.clearHighlightCache(id)
     this.vitest.invalidateFile(id)
@@ -93,7 +93,7 @@ export class VitestWatcher {
     }
   }
 
-  private onUnlink = (id: string): void => {
+  public onFileDelete = (id: string): void => {
     id = slash(id)
     this.vitest.logger.clearHighlightCache(id)
     this.invalidates.add(id)
@@ -108,7 +108,7 @@ export class VitestWatcher {
     }
   }
 
-  private onAdd = (id: string): void => {
+  public onFileCreate = (id: string): void => {
     id = slash(id)
     this.vitest.invalidateFile(id)
 

Original file line number	Diff line number	Diff line change
`@@ -38,14 +38,14 @@ export class VitestWatcher {`
`38`	`38`	`watcher.add(this.vitest.config.forceRerunTriggers)`
`39`	`39`	`}`
`40`	`40`
`41`		`- watcher.on('change', this.onChange)`
`42`		`- watcher.on('unlink', this.onUnlink)`
`43`		`- watcher.on('add', this.onAdd)`
	`41`	`+ watcher.on('change', this.onFileChange)`
	`42`	`+ watcher.on('unlink', this.onFileDelete)`
	`43`	`+ watcher.on('add', this.onFileCreate)`
`44`	`44`
`45`	`45`	`this.unregisterWatcher = () => {`
`46`		`- watcher.off('change', this.onChange)`
`47`		`- watcher.off('unlink', this.onUnlink)`
`48`		`- watcher.off('add', this.onAdd)`
	`46`	`+ watcher.off('change', this.onFileChange)`
	`47`	`+ watcher.off('unlink', this.onFileDelete)`
	`48`	`+ watcher.off('add', this.onFileCreate)`
`49`	`49`	`this.unregisterWatcher = noop`
`50`	`50`	`}`
`51`	`51`	`return this`
`@@ -77,7 +77,7 @@ export class VitestWatcher {`
`77`	`77`	`return triggered`
`78`	`78`	`}`
`79`	`79`
`80`		`- private onChange = (id: string): void => {`
	`80`	`+ public onFileChange = (id: string): void => {`
`81`	`81`	`id = slash(id)`
`82`	`82`	`this.vitest.logger.clearHighlightCache(id)`
`83`	`83`	`this.vitest.invalidateFile(id)`
`@@ -93,7 +93,7 @@ export class VitestWatcher {`
`93`	`93`	`}`
`94`	`94`	`}`
`95`	`95`
`96`		`- private onUnlink = (id: string): void => {`
	`96`	`+ public onFileDelete = (id: string): void => {`
`97`	`97`	`id = slash(id)`
`98`	`98`	`this.vitest.logger.clearHighlightCache(id)`
`99`	`99`	`this.invalidates.add(id)`
`@@ -108,7 +108,7 @@ export class VitestWatcher {`
`108`	`108`	`}`
`109`	`109`	`}`
`110`	`110`
`111`		`- private onAdd = (id: string): void => {`
	`111`	`+ public onFileCreate = (id: string): void => {`
`112`	`112`	`id = slash(id)`
`113`	`113`	`this.vitest.invalidateFile(id)`
`114`	`114`