瀏覽器配置參考
你可以透過更新你的 設定檔 中的 test.browser 欄位來修改瀏覽器配置。一個簡單設定檔的範例：
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
browser: {
enabled: true,
provider: 'playwright',
instances: [
{
browser: 'chromium',
setupFile: './chromium-setup.js',
},
],
},
},
});請參閱「配置參考」文章以取得不同的配置範例。
WARNING
本頁面所有列出的選項皆位於配置中的 test 屬性下：
export default defineConfig({
test: {
browser: {},
},
});browser.enabled
- 類型：
boolean - 預設值：
false - CLI：
--browser、--browser.enabled=false
預設情況下，此選項控制是否在瀏覽器中執行所有測試。請注意，--browser 僅在您至少有一個 browser.instances 項目時才有效。
browser.instances
- 類型：
BrowserConfig - 預設值：
[{ browser: name }]
定義多個瀏覽器配置。每個配置都必須至少包含一個 browser 欄位。此配置支援針對您的提供者進行設定：
TIP
為了在使用內建提供者時取得更好的類型安全，您應該在您的 設定檔 中引用這些類型之一（針對您正在使用的提供者）：
/// <reference types="@vitest/browser/providers/playwright" />
/// <reference types="@vitest/browser/providers/webdriverio" />此外，您還可以指定大多數 專案選項（未標記 * 圖示的）以及部分 browser 選項，例如 browser.testerHtmlPath。
WARNING
每個瀏覽器配置都會繼承根配置的選項：
export default defineConfig({
test: {
setupFile: ['./root-setup-file.js'],
browser: {
enabled: true,
testerHtmlPath: './custom-path.html',
instances: [
{
// 將同時擁有「根」和「瀏覽器」兩個設定檔
setupFile: ['./browser-setup-file.js'],
// 隱含地從根配置繼承了 "testerHtmlPath"
// testerHtmlPath: './custom-path.html',
},
],
},
},
})在開發過程中，Vitest 僅支援一個 非無頭 配置。您可以透過在配置中指定 headless: false、提供 --browser.headless=false 旗標，或使用 --project=chromium 旗標來過濾專案，以限制有頭專案。
更多範例請參考「多重設定」指南。
可用的 browser 選項列表：
browser.headlessbrowser.locatorsbrowser.viewportbrowser.testerHtmlPathbrowser.screenshotDirectorybrowser.screenshotFailures
預設情況下，Vitest 會建立一個包含單一元素的陣列，並使用 browser.name 欄位作為 browser。請注意，此行為將在 Vitest 4 中移除。
在底層實現中，Vitest 會將這些實例轉換為獨立的 測試專案，共用一個 Vite 伺服器以取得更好的快取效能。
browser.name 已棄用
- 類型：
string - CLI：
--browser=safari
已棄用
此 API 已棄用，並將於 Vitest 4 中移除。請改用 browser.instances 選項。
使用特定瀏覽器執行所有測試。不同提供者中可能的選項：
webdriverio：firefox、chrome、edge、safariplaywright：firefox、webkit、chromium- 自訂：任何將傳遞給提供者的字串
browser.headless
- 類型：
boolean - 預設值：
process.env.CI - CLI：
--browser.headless、--browser.headless=false
以「無頭 (headless)」模式執行瀏覽器。如果您在 CI 環境中執行 Vitest，此模式將預設啟用。
browser.isolate
- 類型：
boolean - 預設值：
true - CLI：
--browser.isolate、--browser.isolate=false
在獨立的 iframe 中執行每個測試。
browser.testerHtmlPath
- 類型：
string
HTML 入口點的路徑。可以是相對於專案根目錄的路徑。此檔案會透過 transformIndexHtml 鉤子進行處理。
browser.api
- 類型：
number | { port?, strictPort?, host? } - 預設值：
63315 - CLI：
--browser.api=63315、--browser.api.port=1234、--browser.api.host=example.com
配置用於在瀏覽器中提供程式碼的 Vite 伺服器選項。不影響 test.api 選項。預設情況下，Vitest 會分配埠號 63315，以避免與開發伺服器衝突，讓您可以同時執行兩者。
browser.provider
- 類型：
'webdriverio' | 'playwright' | 'preview' | string - 預設值：
'preview' - CLI：
--browser.provider=playwright
執行瀏覽器測試時所使用的提供者路徑。Vitest 提供三個內建提供者：preview（預設）、webdriverio 和 playwright。自訂提供者應使用 default 匯出，並符合以下結構：
export interface BrowserProvider {
name: string;
supportsParallelism: boolean;
getSupportedBrowsers: () => readonly string[];
beforeCommand?: (command: string, args: unknown[]) => Awaitable<void>;
afterCommand?: (command: string, args: unknown[]) => Awaitable<void>;
getCommandsContext: (sessionId: string) => Record<string, unknown>;
openPage: (
sessionId: string,
url: string,
beforeNavigate?: () => Promise<void>
) => Promise<void>;
getCDPSession?: (sessionId: string) => Promise<CDPSession>;
close: () => Awaitable<void>;
initialize(
ctx: TestProject,
options: BrowserProviderInitializationOptions
): Awaitable<void>;
}進階 API
自訂提供者 API 仍處於高度實驗階段，並且可能在修補版本之間發生變化。如果您僅需在瀏覽器中執行測試，請改用 browser.instances 選項。
browser.providerOptions 已棄用
- 類型：
BrowserProviderOptions
已棄用
此 API 已棄用，並將於 Vitest 4 中移除。請改用 browser.instances 選項。
呼叫 provider.initialize 時會傳遞給提供者的選項。
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
browser: {
providerOptions: {
launch: {
devtools: true,
},
},
},
},
});TIP
為了在使用內建提供者時取得更好的類型安全，您應該在您的 設定檔 中引用這些類型之一（針對您正在使用的提供者）：
/// <reference types="@vitest/browser/providers/playwright" />
/// <reference types="@vitest/browser/providers/webdriverio" />browser.ui
- 類型：
boolean - 預設值：
!isCI - CLI：
--browser.ui=false
Vitest UI 是否應注入到頁面中。預設情況下，在開發期間會注入 UI iframe。
browser.viewport
- 類型：
{ width, height } - 預設值：
414x896
預設 iframe 的視埠大小。
browser.locators
內建 瀏覽器定位器 的選項。
browser.locators.testIdAttribute
- 類型：
string - 預設值：
data-testid
用於透過 getByTestId 定位器尋找元素的屬性。
browser.screenshotDirectory
- 類型：
string - 預設值： 測試檔案目錄中的
__screenshots__
螢幕截圖目錄相對於專案根目錄 (root) 的路徑。
browser.screenshotFailures
- 類型：
boolean - 預設值：
!browser.ui
如果測試失敗，Vitest 是否會截圖。
browser.orchestratorScripts
- 類型：
BrowserScript[] - 預設值：
[]
在測試 iframe 初始化之前，應注入到協調器 HTML 中的自訂腳本。此 HTML 文件僅用於設定 iframe，並未實際匯入您的程式碼。
腳本的 src 和 content 會由 Vite 插件處理。腳本應提供以下形式：
export interface BrowserScript {
/**
* 如果提供了 "content" 且類型為 "module"，這將是其識別符。
*
* 如果您正在使用 TypeScript，您可以在此處添加 .ts 副檔名。
* @default `injected-${index}.js`
*/
id?: string;
/**
* 要注入的 JavaScript 內容。如果類型為 "module"，此字串會由 Vite 插件處理。
*
* 您可以使用 `id` 來提示 Vite 檔案副檔名。
*/
content?: string;
/**
* 腳本的路徑。此值會由 Vite 解析，因此可以是節點模組或檔案路徑。
*/
src?: string;
/**
* 腳本是否應非同步載入。
*/
async?: boolean;
/**
* 腳本類型。
* @default 'module'
*/
type?: string;
}browser.testerScripts
- 類型：
BrowserScript[] - 預設值：
[]
已棄用
此 API 已棄用，並將於 Vitest 4 中移除。請改用 browser.testerHtmlPath 欄位。
在測試環境初始化之前，應注入到測試器 HTML 中的自訂腳本。這對於注入 Vitest 瀏覽器實作所需的 polyfill 很有幫助。在幾乎所有情況下，建議使用 setupFiles 而非此選項。
腳本的 src 和 content 會由 Vite 插件處理。
browser.commands
- 類型：
Record<string, BrowserCommand> - 預設值：
{ readFile, writeFile, ... }
在瀏覽器測試期間，可以從 @vitest/browser/commands 匯入的自訂 命令。
browser.connectTimeout
- 類型：
number - 預設值：
60_000
逾時時間（單位：毫秒）。如果連接到瀏覽器花費的時間過長，測試套件將會失敗。
INFO
這是瀏覽器與 Vitest 伺服器建立 WebSocket 連線所需的時間。在正常情況下，此逾時不應被觸發。