fix(vitest): expose provide to the public API (#5897)

sheremet-va · web-flow · commit 66e648ff88d9 · 2024-06-16T16:02:22.000+02:00
diff --git a/docs/advanced/api.md b/docs/advanced/api.md
@@ -76,3 +76,45 @@ Benchmark mode calls `bench` functions and throws an error, when it encounters `
 ### start
 
 You can start running tests or benchmarks with `start` method. You can pass an array of strings to filter test files.
+
+### `provide`
+
+Vitest exposes `provide` method which is a shorthand for `vitest.getCoreWorkspaceProject().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.
+
+To recieve the values in the test, you need to import `inject` method from `vitest` entrypont:
+
+```ts
+import { inject } from 'vitest'
+const port = inject('wsPort') // 3000
+```
+
+For better type safety, we encourage you to augment the type of `ProvidedContext`:
+
+```ts
+import { createVitest } from 'vitest/node'
+
+const vitest = await createVitest('test', {
+  watch: false,
+})
+vitest.provide('wsPort', 3000)
+
+declare module 'vitest' {
+  export interface ProvidedContext {
+    wsPort: number
+  }
+}
+```
+
+::: warning
+Technically, `provide` is a method of `WorkspaceProject`, so it is limited to the specific project. However, all projects inherit the values from the core project which makes `vitest.provide` universal way of passing down values to tests.
+:::
+
+::: tip
+This method is also available to [global setup files](/config/#globalsetup) for cases where you don't want to use the public API:
+
+```js
+export default function setup({ provide }) {
+  provide('wsPort', 3000)
+}
+```
+:::
diff --git a/docs/guide/cli-table.md b/docs/guide/cli-table.md
@@ -53,10 +53,11 @@
 | `--browser.api.port [port]` | Specify server port. Note if the port is already being used, Vite will automatically try the next available port so this may not be the actual port the server ends up listening on. If true will be set to `63315` |
 | `--browser.api.host [host]` | Specify which IP addresses the server should listen on. Set this to `0.0.0.0` or `true` to listen on all addresses, including LAN and public addresses |
 | `--browser.api.strictPort` | Set to true to exit if port is already in use, instead of automatically trying the next available port |
-| `--browser.provider <name>` | Provider used to run browser tests. Some browsers are only available for specific providers. Can be "webdriverio", "playwright", or the path to a custom provider. Visit [`browser.provider`](https://vitest.dev/config/#browser-provider) for more information (default: `"webdriverio"`) |
+| `--browser.provider <name>` | Provider used to run browser tests. Some browsers are only available for specific providers. Can be "webdriverio", "playwright", "preview", or the path to a custom provider. Visit [`browser.provider`](https://vitest.dev/config/#browser-provider) for more information (default: `"preview"`) |
 | `--browser.providerOptions <options>` | Options that are passed down to a browser provider. Visit [`browser.providerOptions`](https://vitest.dev/config/#browser-provideroptions) for more information |
 | `--browser.isolate` | Run every browser test file in isolation. To disable isolation, use `--browser.isolate=false` (default: `true`) |
 | `--browser.ui` | Show Vitest UI when running tests (default: `!process.env.CI`) |
+| `--browser.fileParallelism` | Should browser test files run in parallel. Use `--browser.fileParallelism=false` to disable (default: `true`) |
 | `--pool <pool>` | Specify pool, if not running in the browser (default: `threads`) |
 | `--poolOptions.threads.isolate` | Isolate tests in threads pool (default: `true`) |
 | `--poolOptions.threads.singleThread` | Run tests inside a single thread (default: `false`) |
@@ -117,6 +118,7 @@
 | `--expect.requireAssertions` | Require that all tests have at least one assertion |
 | `--expect.poll.interval <interval>` | Poll interval in milliseconds for `expect.poll()` assertions (default: `50`) |
 | `--expect.poll.timeout <timeout>` | Poll timeout in milliseconds for `expect.poll()` assertions (default: `1000`) |
+| `--printConsoleTrace` | Always print console stack traces |
 | `--run` | Disable watch mode |
 | `--no-color` | Removes colors from the console output |
 | `--clearScreen` | Clear terminal screen when re-running tests during watch mode (default: `true`) |
diff --git a/packages/vitest/src/node/core.ts b/packages/vitest/src/node/core.ts
@@ -13,7 +13,7 @@ import type { CancelReason, File, TaskResultPack } from '@vitest/runner'
 import { ViteNodeServer } from 'vite-node/server'
 import type { defineWorkspace } from 'vitest/config'
 import { version } from '../../package.json' with { type: 'json' }
-import type { ArgumentsType, CoverageProvider, OnServerRestartHandler, Reporter, ResolvedConfig, SerializableSpec, UserConfig, UserConsoleLog, UserWorkspaceConfig, VitestRunMode } from '../types'
+import type { ArgumentsType, CoverageProvider, OnServerRestartHandler, ProvidedContext, Reporter, ResolvedConfig, SerializableSpec, UserConfig, UserConsoleLog, UserWorkspaceConfig, VitestRunMode } from '../types'
 import { getTasks, hasFailed, noop, slash, toArray, wildcardPatternToRegExp } from '../utils'
 import { getCoverageProvider } from '../integrations/coverage'
 import { CONFIG_NAMES, configFiles, workspacesFiles as workspaceFiles } from '../constants'
@@ -180,6 +180,10 @@ export class Vitest {
       this.configOverride.testNamePattern = this.config.testNamePattern
   }
 
+  public provide<T extends keyof ProvidedContext>(key: T, value: ProvidedContext[T]) {
+    this.getCoreWorkspaceProject().provide(key, value)
+  }
+
   private async createCoreProject() {
     this.coreWorkspaceProject = await WorkspaceProject.createCoreProject(this)
     return this.coreWorkspaceProject
