refactor!: separate config resolution from the server creation (#10554)

Author: sheremet-va

docs/.vitepress/config.ts

@@ -618,18 +618,10 @@ export default ({ mode }: { mode: string }) => {
                 text: 'browser.headless',
                 link: '/config/browser/headless',
               },
-              {
-                text: 'browser.isolate',
-                link: '/config/browser/isolate',
-              },
               {
                 text: 'browser.testerHtmlPath',
                 link: '/config/browser/testerhtmlpath',
               },
-              {
-                text: 'browser.api',
-                link: '/config/browser/api',
-              },
               {
                 text: 'browser.provider',
                 link: '/config/browser/provider',

docs/.vitepress/scripts/cli-generator.ts

@@ -39,7 +39,6 @@ const skipConfig = new Set([
   'project',
   'ui',
   'browser.name',
-  'browser.fileParallelism',
   'clearCache',
   'tagsFilter',
   'listTags',

docs/api/advanced/artifacts.md

@@ -67,7 +67,7 @@ The `TestArtifactBase` interface is the base for all test artifacts.
 Extend this interface when creating custom test artifacts. Vitest automatically manages the `attachments` array and injects the `location` property to indicate where the artifact was created in your test code.
 
 ::: danger
-When running with [`api.allowWrite`](/config/api#api-allowwrite) or [`browser.api.allowWrite`](/config/browser/api#api-allowwrite) disabled, Vitest empties the `attachments` array on every artifact before reporting it.
+When running with [`api.allowWrite`](/config/api#api-allowwrite) disabled, Vitest empties the `attachments` array on every artifact before reporting it.
 
 If your custom artifact narrows the `attachments` type (e.g. to a tuple), include `| []` in the union so the type reflects what actually happens at runtime.
 :::

docs/api/advanced/test-module.md

@@ -153,7 +153,7 @@ interface ImportDuration {
 function logs(): ReadonlyArray<UserConsoleLog>
 ```
 
-Console logs recorded on top level of the module during test collection.For example:
+Console logs recorded on top level of the module during test collection. For example:
 
 ```ts
 console.log('included') // [!code highlight]

docs/api/browser/commands.md

@@ -18,7 +18,7 @@ By default, Vitest uses `utf-8` encoding but you can override it with options.
 ::: tip
 The built-in file commands follow Vite's [`server.fs`](https://vitejs.dev/config/server-options.html#server-fs-allow) restrictions for security reasons.
 
-`writeFile` and `removeFile` also require write access through [`browser.api.allowWrite`](/config/browser/api) and [`api.allowWrite`](/config/api#api-allowwrite).
+`writeFile` and `removeFile` also require write access through [`api.allowWrite`](/config/api#api-allowwrite).
 :::
 
 ```ts
@@ -60,7 +60,7 @@ expect(input).toHaveValue('a')
 ::: warning
 CDP session works only with `playwright` provider and only when using `chromium` browser. You can read more about it in playwright's [`CDPSession`](https://playwright.dev/docs/api/class-cdpsession) documentation.
 
-CDP is a privileged debugging API. It is available only when browser API write and exec operations are enabled through [`browser.api.allowWrite`](/config/browser/api#api-allowwrite), [`browser.api.allowExec`](/config/browser/api#api-allowexec), [`api.allowWrite`](/config/api#api-allowwrite), and [`api.allowExec`](/config/api#api-allowexec).
+CDP is a privileged debugging API. It is available only when browser API write and exec operations are enabled through [`api.allowWrite`](/config/api#api-allowwrite), and [`api.allowExec`](/config/api#api-allowexec).
 :::
 
 ## Custom Commands
@@ -131,7 +131,7 @@ Custom commands run in the Vitest Node process and are callable from browser tes
 
 Vitest's built-in file commands validate paths against Vite's [`server.fs`](https://vite.dev/config/server-options#server-fs-allow) restrictions and separately check whether writes are allowed. Custom commands do not automatically inherit these protections. If a custom command accepts browser-provided input and uses it to read, write, delete, execute, or expose local resources, validate that input before using it.
 
-For file reads or fixture loading, use `isFileLoadingAllowed` from `vitest/node` or an explicit allowlist. For writes and deletes, also require an explicit mutation policy, such as [`browser.api.allowWrite`](/config/browser/api#api-allowwrite), [`api.allowWrite`](/config/api#api-allowwrite), and a command-specific allowed directory. For commands that execute code, shell commands, or project scripts, also check [`browser.api.allowExec`](/config/browser/api#api-allowexec) and [`api.allowExec`](/config/api#api-allowexec).
+For file reads or fixture loading, use `isFileLoadingAllowed` from `vitest/node` or an explicit allowlist. For writes and deletes, also require an explicit mutation policy, such as [`api.allowWrite`](/config/api#api-allowwrite), and a command-specific allowed directory. For commands that execute code, shell commands, or project scripts, also check [`api.allowExec`](/config/api#api-allowexec).
 
 For example, if you create your own file-writing command instead of using Vitest's built-in `writeFile`, apply the same checks:
 

docs/api/browser/context.md

@@ -212,7 +212,7 @@ The `cdp` export returns the current Chrome DevTools Protocol session. It is mos
 ::: warning
 CDP session works only with `playwright` provider and only when using `chromium` browser. You can read more about it in playwright's [`CDPSession`](https://playwright.dev/docs/api/class-cdpsession) documentation.
 
-CDP is a privileged debugging API. It is available only when browser API write and exec operations are enabled through [`browser.api.allowWrite`](/config/browser/api#api-allowwrite), [`browser.api.allowExec`](/config/browser/api#api-allowexec), [`api.allowWrite`](/config/api#api-allowwrite), and [`api.allowExec`](/config/api#api-allowexec).
+CDP is a privileged debugging API. It is available only when browser API write and exec operations are enabled through [`api.allowWrite`](/config/api#api-allowwrite), and [`api.allowExec`](/config/api#api-allowexec).
 :::
 
 ```ts

docs/config/api.md

@@ -9,7 +9,7 @@ outline: deep
 - **Default:** `false`
 - **CLI:** `--api`, `--api.port`, `--api.host`, `--api.strictPort`
 
-Listen to port and serve API for [the UI](/guide/ui) or [browser server](/guide/browser/). When set to `true`, the default port is `51204`.
+Listen to port and serve API for [the UI](/guide/ui) or [browser server](/guide/browser/). When set to `true`, the default port is `51204` or `63315` if running in Browser Mode.
 
 ## api.allowWrite <Version>4.1.0</Version> {#api-allowwrite}
 
@@ -18,6 +18,8 @@ Listen to port and serve API for [the UI](/guide/ui) or [browser server](/guide/
 
 Vitest server can save test files or snapshot files via the API. This allows anyone who can connect to the API the ability to run any arbitrary code on your machine.
 
+In Browser Mode Vitest saves [annotation attachments](/guide/test-annotations), [artifacts](/api/advanced/artifacts) and [snapshots](/guide/snapshot) by receiving a WebSocket connection from the browser. This allows anyone who can connect to the API write any arbitrary code on your machine within the root of your project (configured by [`fs.allow`](https://vite.dev/config/server-options#server-fs-allow)). This option also gates privileged browser APIs that can write files indirectly, such as raw Chrome DevTools Protocol access through [`cdp()`](/api/browser/context#cdp).
+
 ::: danger SECURITY ADVICE
 Vitest does not expose the API to the internet by default and only listens on `localhost`. However if `host` is manually exposed to the network, anyone who connects to it can run arbitrary code on your machine, unless `api.allowWrite` and `api.allowExec` are set to `false`.
 
@@ -29,4 +31,5 @@ If the host is set to anything other than `localhost` or `127.0.0.1`, Vitest wil
 - **Type:** `boolean`
 - **Default:** `true` if not exposed to the network, `false` otherwise
 
-Allows running any test file via the API. See the security advice in [`api.allowWrite`](#api-allowwrite).
+Allows running any test file via the UI. This applies to the interactive elements (and the server code behind them) in the [UI](/guide/ui) that can run the code. This option also gates privileged browser APIs that can execute code indirectly, such as raw Chrome DevTools Protocol access through [`cdp()`](/api/browser/context#cdp).
+

docs/config/browser/api.md

@@ -85,19 +85,18 @@ The ["Running Tests"](/guide/advanced/tests#createvitest) guide has a usage exam
 function resolveConfig(
   options: UserConfig = {},
   viteOverrides: ViteUserConfig = {},
-): Promise<{
-  vitestConfig: ResolvedConfig
-  viteConfig: ResolvedViteConfig
-}>
+  harness?: PluginHarness,
+): Promise<ResolvedViteConfig>
 ```
 
-This method resolves the config with custom parameters. If no parameters are given, the `root` will be `process.cwd()`.
+This method resolves the config with custom parameters, without creating a Vite server. If no parameters are given, the `root` will be `process.cwd()`.
+
+It returns the resolved Vite config. The fully resolved Vitest config, including every project, lives on its `test` property.
 
 ```ts
 import { resolveConfig } from 'vitest/node'
 
-// vitestConfig only has resolved "test" properties
-const { vitestConfig, viteConfig } = await resolveConfig({
+const viteConfig = await resolveConfig({
   mode: 'custom',
   configFile: false,
   resolve: {
@@ -108,18 +107,14 @@ const { vitestConfig, viteConfig } = await resolveConfig({
     pool: 'threads',
   },
 })
+
+viteConfig.test.pool // 'threads'
 ```
 
 ::: info
-Due to how Vite's `createServer` works, Vitest has to resolve the config during the plugin's `configResolve` hook. Therefore, this method is not actually used internally and is exposed exclusively as a public API.
-
-If you pass down the config to the `startVitest` or `createVitest` APIs, Vitest will still resolve the config again.
-:::
+This is the same method Vitest uses internally to resolve the config before creating the server. If you pass the options down to `startVitest` or `createVitest`, Vitest resolves them again.
 
-::: warning
-The `resolveConfig` doesn't resolve `projects`. To resolve projects configs, Vitest needs an established Vite server.
-
-Also note that `viteConfig.test` will not be fully resolved. If you need Vitest config, use `vitestConfig` instead.
+You can pass a shared [`PluginHarness`](#pluginharness) as the third argument to reuse a logger and package installer across calls.
 :::
 
 ## parseCLI
@@ -147,3 +142,52 @@ result.options
 result.filter
 // ['./files.ts']
 ```
+
+## createCLI
+
+```ts
+function createCLI(options?: CliParseOptions): CAC
+```
+
+Creates the Vitest command-line interface: a [`cac`](https://github.com/cacjs/cac) instance with all of Vitest's commands and options registered. [`parseCLI`](#parsecli) is built on top of it; use `createCLI` directly if you need the raw parser.
+
+```ts
+import { createCLI } from 'vitest/node'
+
+const cli = createCLI()
+```
+
+## PluginHarness
+
+```ts
+class PluginHarness {
+  vitest?: Vitest
+  version: string
+  logger: Logger
+  packageInstaller: VitestPackageInstaller
+  getVitest(): Vitest
+}
+```
+
+A container that Vitest passes to its internal plugins while the config is being resolved, before a [`Vitest`](/api/advanced/vitest) instance exists. It holds the [`Logger`](#logger), the package installer and the resolved version, and exposes the `Vitest` instance via `getVitest()` once it has been created (calling it earlier throws).
+
+This is an advanced, plugin-facing API. You rarely construct one directly, but you can pass a shared instance to [`resolveConfig`](#resolveconfig) to reuse a logger and package installer.
+
+## Logger
+
+```ts
+class Logger {
+  constructor(
+    outputStream?: Writable,
+    errorStream?: Writable,
+  )
+}
+```
+
+Vitest's terminal logger, exposed as [`vitest.logger`](/api/advanced/vitest). It handles formatted output, the error summary, the run banner and screen clearing. Construct one with custom `stdout`/`stderr` streams to capture or redirect Vitest's output when running it programmatically.
+
+```ts
+import { Logger } from 'vitest/node'
+
+const logger = new Logger(process.stdout, process.stderr)
+```