feat(api): expose runTestFiles as alternative to runTestSpecifications

docs/api/advanced/vitest.md

@@ -302,6 +302,21 @@ function rerunTestSpecifications(
 
 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.
 
+## runTestFiles <Version>4.1.0</Version> {#runtestfiles}
+
+```ts
+function runTestFiles(
+  filepaths: string[],
+  allTestsRun = false
+): Promise<TestRunResult>
+```
+
+This automatically creates specifications to run based on filepaths filters.
+
+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).
+
+This function accepts the same filters as [`start`](#start) and the CLI.
+
 ## updateSnapshot
 
 ```ts

packages/vitest/src/node/core.ts

@@ -668,7 +668,7 @@ export class Vitest {
 
       this.filenamePattern = filters && filters?.length > 0 ? filters : undefined
       startSpan.setAttribute('vitest.start.filters', this.filenamePattern || [])
-      const files = await this._traces.$(
+      const specifications = await this._traces.$(
         'vitest.config.resolve_include_glob',
         async () => {
           const specifications = await this.specifications.getRelevantTestSpecifications(filters)
@@ -687,7 +687,7 @@ export class Vitest {
       )
 
       // if run with --changed, don't exit if no tests are found
-      if (!files.length) {
+      if (!specifications.length) {
         await this._traces.$('vitest.test_run', async () => {
           await this._testRun.start([])
           const coverage = await this.coverageProvider?.generateCoverage?.({ allTestsRun: true })
@@ -707,11 +707,11 @@ export class Vitest {
         unhandledErrors: [],
       }
 
-      if (files.length) {
+      if (specifications.length) {
         // populate once, update cache on watch
-        await this.cache.stats.populateStats(this.config.root, files)
+        await this.cache.stats.populateStats(this.config.root, specifications)
 
-        testModules = await this.runFiles(files, true)
+        testModules = await this.runFiles(specifications, true)
       }
 
       if (this.config.watch) {
@@ -788,6 +788,19 @@ export class Vitest {
     return this.runFiles(specifications, allTestsRun)
   }
 
+  /**
+   * Runs tests for the given file paths. This does not trigger `onWatcher*` events.
+   * @param filepaths A list of file paths to run tests for.
+   * @param allTestsRun Indicates whether all tests were run. This only matters for coverage.
+   */
+  public async runTestFiles(filepaths: string[], allTestsRun = false): Promise<TestRunResult> {
+    const specifications = await this.specifications.getRelevantTestSpecifications(filepaths)
+    if (!specifications.length) {
+      return { testModules: [], unhandledErrors: [] }
+    }
+    return this.runFiles(specifications, allTestsRun)
+  }
+
   /**
    * Rerun files and trigger `onWatcherRerun`, `onWatcherStart` and `onTestsRerun` events.
    * @param specifications A list of specifications to run.