Riferimento alla Configurazione del Browser
È possibile modificare la configurazione del browser aggiornando il campo test.browser
nel proprio file di configurazione. Di seguito un esempio di un semplice file di configurazione:
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
browser: {
enabled: true,
provider: 'playwright',
instances: [
{
browser: 'chromium',
setupFile: './chromium-setup.js',
},
],
},
},
});
Per ulteriori esempi di configurazione, fare riferimento all'articolo "Riferimento Configurazione".
WARNING
Tutte le opzioni elencate in questa pagina si trovano all'interno della proprietà test
nella configurazione:
export default defineConfig({
test: {
browser: {},
},
});
browser.enabled
- Tipo:
boolean
- Predefinito:
false
- CLI:
--browser
,--browser.enabled=false
Se abilitato, esegue tutti i test all'interno di un browser. Si noti che l'opzione --browser
funziona solo se è presente almeno un elemento in browser.instances
.
browser.instances
- Tipo:
BrowserConfig
- Predefinito:
[{ browser: name }]
Definisce più configurazioni del browser. Ogni configurazione deve contenere almeno un campo browser
. La configurazione supporta i seguenti provider:
TIP
Per una maggiore sicurezza dei tipi quando si utilizzano i provider integrati, è consigliabile fare riferimento a uno di questi tipi (per il provider in uso) nel proprio file di configurazione:
/// <reference types="@vitest/browser/providers/playwright" />
/// <reference types="@vitest/browser/providers/webdriverio" />
Inoltre, è possibile specificare la maggior parte delle opzioni di progetto (quelle non contrassegnate con un'icona *) e alcune delle opzioni browser
come browser.testerHtmlPath
.
WARNING
Ogni configurazione del browser eredita le opzioni dalla configurazione principale:
export default defineConfig({
test: {
setupFile: ['./root-setup-file.js'],
browser: {
enabled: true,
testerHtmlPath: './custom-path.html',
instances: [
{
// avrà entrambi i file di setup: "root" e "browser"
setupFile: ['./browser-setup-file.js'],
// eredita implicitamente "testerHtmlPath" dalla configurazione radice
// testerHtmlPath: './custom-path.html',
},
],
},
},
})
Durante lo sviluppo, Vitest supporta solo una configurazione non-headless. È possibile specificare quale progetto eseguire con interfaccia grafica impostando headless: false
nella configurazione, fornendo il flag --browser.headless=false
, o filtrando i progetti con il flag --project=chromium
.
Per ulteriori esempi, consultare la guida "Configurazioni Multiple".
Elenco delle opzioni browser
disponibili:
browser.headless
browser.locators
browser.viewport
browser.testerHtmlPath
browser.screenshotDirectory
browser.screenshotFailures
Per impostazione predefinita, Vitest crea un array contenente un solo elemento che utilizza il campo browser.name
come browser
. Si noti che questo comportamento verrà rimosso a partire da Vitest 4.
Internamente, Vitest trasforma queste istanze in progetti di test separati che condividono un singolo server Vite per migliori prestazioni di caching.
browser.name deprecato
- Tipo:
string
- CLI:
--browser=safari
DEPRECATO
Questa API è deprecata e verrà rimossa a partire da Vitest 4. Si prega di utilizzare l'opzione browser.instances
invece.
Esegue i test in un browser specifico. Opzioni disponibili nei vari provider:
webdriverio
:firefox
,chrome
,edge
,safari
playwright
:firefox
,webkit
,chromium
- personalizzato: qualsiasi stringa che verrà passata al provider
browser.headless
- Tipo:
boolean
- Predefinito:
process.env.CI
- CLI:
--browser.headless
,--browser.headless=false
Esegue il browser in modalità headless
. Se Vitest viene eseguito in un ambiente CI, questa modalità sarà abilitata per impostazione predefinita.
browser.isolate
- Tipo:
boolean
- Predefinito:
true
- CLI:
--browser.isolate
,--browser.isolate=false
Esegue ogni test in un iframe separato.
browser.testerHtmlPath
- Tipo:
string
Il percorso al punto di ingresso HTML. Può essere relativo alla radice del progetto. Questo file sarà elaborato con l'hook transformIndexHtml
.
browser.api
- Tipo:
number | { port?, strictPort?, host? }
- Predefinito:
63315
- CLI:
--browser.api=63315
,--browser.api.port=1234, --browser.api.host=example.com
Configura le opzioni per il server Vite che fornisce il codice nel browser. Non ha effetto sull'opzione test.api
. Per impostazione predefinita, Vitest assegna la porta 63315
per evitare conflitti con il server di sviluppo, permettendo l'esecuzione parallela di entrambi.
browser.provider
- Tipo:
'webdriverio' | 'playwright' | 'preview' | string
- Predefinito:
'preview'
- CLI:
--browser.provider=playwright
Il percorso del provider che verrà utilizzato durante l'esecuzione dei test del browser. Vitest fornisce tre provider: preview
(predefinito), webdriverio
e playwright
. I provider personalizzati devono essere esportati utilizzando l'esportazione default
e rispettare la seguente interfaccia:
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 AVANZATA
L'API del provider personalizzato è altamente sperimentale e può cambiare con gli aggiornamenti di patch. Se l'obiettivo è solo eseguire test in un browser, si consiglia di utilizzare l'opzione browser.instances
invece.
browser.providerOptions deprecato
- Tipo:
BrowserProviderOptions
DEPRECATO
Questa API è deprecata e verrà rimossa a partire da Vitest 4. Si prega di utilizzare l'opzione browser.instances
invece.
Opzioni che verranno passate al provider quando viene chiamato provider.initialize
.
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
browser: {
providerOptions: {
launch: {
devtools: true,
},
},
},
},
});
TIP
Per una maggiore sicurezza dei tipi quando si utilizzano i provider integrati, è consigliabile fare riferimento a uno di questi tipi (per il provider in uso) nel proprio file di configurazione:
/// <reference types="@vitest/browser/providers/playwright" />
/// <reference types="@vitest/browser/providers/webdriverio" />
browser.ui
- Tipo:
boolean
- Predefinito:
!isCI
- CLI:
--browser.ui=false
Indica se la Vitest UI debba essere iniettata nella pagina. Per impostazione predefinita, l'iframe UI viene iniettato durante lo sviluppo.
browser.viewport
- Tipo:
{ width, height }
- Predefinito:
414x896
Il viewport predefinito dell'iframe.
browser.locators
Configura le opzioni per i localizzatori del browser integrati.
browser.locators.testIdAttribute
- Tipo:
string
- Predefinito:
data-testid
L'attributo utilizzato per trovare elementi con il localizzatore getByTestId
.
browser.screenshotDirectory
- Tipo:
string
- Predefinito:
__screenshots__
nella directory del file di test
Il percorso della directory degli screenshot relativo alla root
.
browser.screenshotFailures
- Tipo:
boolean
- Predefinito:
!browser.ui
Indica se Vitest debba acquisire screenshot in caso di fallimento del test.
browser.orchestratorScripts
- Tipo:
BrowserScript[]
- Predefinito:
[]
Script personalizzati da iniettare nell'HTML dell'orchestratore prima che gli iframe di test vengano avviati. Questo documento HTML imposta solo gli iframe e non include il codice dell'applicazione.
Gli attributi src
e content
dello script verranno elaborati dai plugin Vite. Lo script deve essere fornito nella seguente forma:
export interface BrowserScript {
/**
* Se "content" è fornito e il tipo è "module", questo sarà utilizzato come suo identificatore.
*
* Se si utilizza TypeScript, è possibile aggiungere l'estensione `.ts` qui, ad esempio.
* @default `injected-${index}.js`
*/
id?: string;
/**
* Contenuto JavaScript da iniettare. Il contenuto di questa stringa viene elaborato dai plugin Vite se il tipo è "module".
*
* È possibile usare `id` per fornire a Vite un suggerimento sull'estensione del file.
*/
content?: string;
/**
* Percorso dello script. Questo valore viene risolto da Vite, quindi può essere un modulo Node.js o un percorso di file.
*/
src?: string;
/**
* Indica se lo script debba essere caricato in modo asincrono.
*/
async?: boolean;
/**
* Tipo di script.
* @default 'module'
*/
type?: string;
}
browser.testerScripts
- Tipo:
BrowserScript[]
- Predefinito:
[]
DEPRECATO
Questa API è deprecata e verrà rimossa a partire da Vitest 4. Si prega di utilizzare il campo browser.testerHtmlPath
invece.
Script personalizzati da iniettare nell'HTML del tester prima che l'ambiente di test venga avviato. Questo è utile per iniettare polyfill necessari per l'implementazione del browser Vitest. Si raccomanda di utilizzare setupFiles
nella maggior parte dei casi, anziché questa opzione.
Gli attributi src
e content
dello script verranno elaborati dai plugin Vite.
browser.commands
- Tipo:
Record<string, BrowserCommand>
- Predefinito:
{ readFile, writeFile, ... }
Definisce comandi personalizzati che possono essere importati durante i test del browser da @vitest/browser/commands
.
browser.connectTimeout
- Tipo:
number
- Predefinito:
60_000
Il valore di timeout in millisecondi. Se la connessione al browser impiega più tempo, la suite di test fallirà.
INFO
Questo rappresenta il tempo che il browser dovrebbe impiegare per stabilire la connessione WebSocket con il server Vitest. In circostanze normali, questo timeout non dovrebbe mai essere superato.