Vitest API

Instance Vitest vyžaduje aktuální testovací režim. Může to být buď:

• test při spouštění testů
• benchmark při spouštění benchmarků experimentální

Novinky ve Vitest 3

Vitest 3 se posouvá blíže ke stabilizaci veřejného API. K dosažení tohoto cíle jsme některé dříve veřejné metody třídy Vitest označili jako zastaralé a odstranili je. Následující API byla nastavena jako soukromá:

• configOverride (použijte setGlobalTestNamePattern nebo enableSnapshotUpdate)
• coverageProvider
• filenamePattern
• runningPromise
• closingPromise
• isCancelling
• coreWorkspaceProject
• resolvedProjects
• _browserLastPort
• _options
• reporters
• vitenode
• runner
• pool
• setServer
• _initBrowserServers
• rerunTask
• changeProjectName
• changeNamePattern
• changeFilenamePattern
• rerunFailed
• _createRootProject (přejmenováno na _ensureRootProject, ale stále soukromé)
• filterTestsBySource (toto bylo přesunuto do nové interní instance vitest.specifications)
• runFiles (místo toho použijte runTestSpecifications)
• onAfterSetServer

Následující API byla označena jako zastaralá:

• invalidates
• changedTests (místo toho použijte onFilterWatchedSpecification)
• server (místo toho použijte vite)
• getProjectsByTestFile (místo toho použijte getModuleSpecifications)
• getFileWorkspaceSpecs (místo toho použijte getModuleSpecifications)
• getModuleProjects (filtrujte sami pomocí this.projects)
• updateLastChanged (přejmenováno na invalidateFile)
• globTestSpecs (místo toho použijte globTestSpecifications)
• globTestFiles (místo toho použijte globTestSpecifications)
• listFile (místo toho použijte getRelevantTestSpecifications)

mode

test

Testovací režim volá pouze funkce definované v test nebo it a vyhodí chybu, když narazí na bench. Tento režim používá možnosti include a exclude v konfiguraci k nalezení testovacích souborů.

benchmark experimentální

Režim benchmark spouští funkce bench a vyhodí chybu, když narazí na test nebo it. Tento režim používá možnosti benchmark.include a benchmark.exclude v konfiguraci k nalezení souborů benchmarků.

config

Kořenová (nebo globální) konfigurace. Pokud jsou definovány projekty, budou na ni odkazovat jako na globalConfig.

WARNING

Toto je konfigurace Vitest, nerozšiřuje konfiguraci Vite. Obsahuje pouze vyřešené hodnoty z vlastnosti test.

vite

Toto je globální ViteDevServer.

state experimental

WARNING

Veřejné API state je experimentální (s výjimkou vitest.state.getReportedEntity). Změny, které narušují zpětnou kompatibilitu, nemusí dodržovat SemVer, proto prosím při jeho používání zafixujte verzi Vitest.

Globální stav uchovává informace o aktuálních testech. Ve výchozím nastavení používá stejné API z @vitest/runner, ale doporučujeme místo toho použít Reported Tasks API voláním state.getReportedEntity() na API @vitest/runner:

const task = vitest.state.idMap.get(taskId); // staré API
const testCase = vitest.state.getReportedEntity(task); // nové API

V budoucnu již staré API nebude dostupné.

snapshot

Globální správce snímků. Vitest sleduje všechny snímky pomocí metody snapshot.add.

Nejnovější souhrn snímků můžete získat prostřednictvím vlastnosti vitest.snapshot.summary.

cache

Správce mezipaměti, který uchovává informace o nejnovějších výsledcích testů a statistikách testovacích souborů. V samotném Vitest je toto používáno pouze výchozím sekvencerem pro řazení testů.

projects

Pole testovacích projektů, které patří k uživatelským projektům. Pokud je uživatel nespecifikoval, toto pole bude obsahovat pouze kořenový projekt.

Vitest zajistí, že v tomto poli bude vždy alespoň jeden projekt. Pokud uživatel zadá neexistující název --project, Vitest vyhodí chybu ještě před definováním tohoto pole.

getRootProject

function getRootProject(): TestProject;

Tato metoda vrací kořenový testovací projekt. Kořenový projekt obecně nespouští žádné testy a není zahrnut v vitest.projects, pokud uživatel explicitně nezahrne kořenovou konfiguraci do své konfigurace, nebo pokud projekty nejsou vůbec definovány.

Hlavním cílem kořenového projektu je nastavit globální konfiguraci. Ve skutečnosti rootProject.config odkazuje přímo na rootProject.globalConfig a vitest.config:

(rootProject.config === rootProject.globalConfig) === rootProject.vitest.config;

provide

function provide<T extends keyof ProvidedContext & string>(
  key: T,
  value: ProvidedContext[T]
): void;

Vitest vystavuje metodu provide, která je zkratkou pro vitest.getRootProject().provide. Pomocí této metody můžete předávat hodnoty z hlavního vlákna do testů. Všechny hodnoty jsou před uložením zkontrolovány pomocí structuredClone, ale samotné hodnoty nejsou klonovány.

Pro příjem hodnot v testu je nutné importovat metodu inject z vstupního bodu vitest:

import { inject } from 'vitest';
const port = inject('wsPort'); // 3000

Pro lepší typovou bezpečnost doporučujeme rozšířit typ ProvidedContext:

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

Technicky je provide metodou TestProject, takže je omezena na konkrétní projekt. Všechny projekty však dědí hodnoty z kořenového projektu, což činí vitest.provide univerzálním způsobem předávání hodnot do testů.

getProvidedContext

function getProvidedContext(): ProvidedContext;

Toto vrací kořenový kontextový objekt. Toto je zkratka pro vitest.getRootProject().getProvidedContext.

getProjectByName

function getProjectByName(name: string): TestProject;

Tato metoda vrací projekt na základě jeho názvu. Podobné volání vitest.projects.find.

WARNING

V případě, že projekt neexistuje, tato metoda vrátí kořenový projekt – ujistěte se, že jste znovu zkontrolovali názvy, pokud hledaný projekt je ten vrácený.

Pokud uživatel název nepřizpůsobil, Vitest přiřadí prázdný řetězec jako název projektu.

globTestSpecifications

function globTestSpecifications(
  filters?: string[]
): Promise<TestSpecification[]>;

Tato metoda vytváří nové testovací specifikace shromažďováním každého testu ve všech projektech pomocí project.globTestFiles. Přijímá řetězcové filtry pro shodu s testovacími soubory – jedná se o stejné filtry, které podporuje CLI.

Tato metoda automaticky ukládá všechny testovací specifikace do mezipaměti. Když příště zavoláte getModuleSpecifications, vrátí stejné specifikace, pokud předtím nebyla volána clearSpecificationsCache.

WARNING

Od Vitest 3 je možné mít více testovacích specifikací se stejným ID modulu (cestou k souboru), pokud poolMatchGlob obsahuje několik poolů nebo pokud je povolena typecheck. Tato možnost bude odstraněna ve Vitest 4.

const specifications = await vitest.globTestSpecifications(['my-filter']);
// [TestSpecification{ moduleId: '/tests/my-filter.test.ts' }]
console.log(specifications);

getRelevantTestSpecifications

function getRelevantTestSpecifications(
  filters?: string[]
): Promise<TestSpecification[]>;

Tato metoda zpracovává každou testovací specifikaci voláním project.globTestFiles. Přijímá řetězcové filtry pro shodu s testovacími soubory – jedná se o stejné filtry, které podporuje CLI. Pokud byl zadán příznak --changed, seznam bude filtrován tak, aby zahrnoval pouze soubory, které byly změněny. getRelevantTestSpecifications nespouští žádné testovací soubory.

WARNING

Tato metoda může být pomalá, protože musí filtrovat příznaky --changed. Nepoužívejte ji, pokud potřebujete pouze seznam testovacích souborů.

• Pokud potřebujete získat seznam specifikací pro známé testovací soubory, použijte místo toho getModuleSpecifications.
• Pokud potřebujete získat seznam všech možných testovacích souborů, použijte globTestSpecifications.

mergeReports

function mergeReports(directory?: string): Promise<TestRunResult>;

Sloučí zprávy z více spuštění umístěných v zadaném adresáři (hodnota z --merge-reports, pokud není specifikováno). Tuto hodnotu lze také nastavit v config.mergeReports (ve výchozím nastavení bude číst složku .vitest-reports).

Všimněte si, že directory bude vždy vyřešen relativně k pracovnímu adresáři.

Tato metoda je volána automaticky startVitest, pokud je nastaveno config.mergeReports.

collect

function collect(filters?: string[]): Promise<TestRunResult>;

Spustí testovací soubory bez volání zpětných volání testů. collect vrací neošetřené chyby a pole testovacích modulů. Přijímá řetězcové filtry pro shodu s testovacími soubory – jedná se o stejné filtry, které podporuje CLI.

Tato metoda řeší specifikace testů na základě hodnot include, exclude a includeSource v konfiguraci. Více se dozvíte na project.globTestFiles. Pokud byl zadán příznak --changed, seznam bude filtrován tak, aby zahrnoval pouze soubory, které se změnily.

WARNING

Všimněte si, že Vitest nepoužívá statickou analýzu ke shromažďování testů. Vitest spustí každý testovací soubor izolovaně, stejně jako spouští běžné testy.

To činí tuto metodu velmi pomalou, pokud před shromažďováním testů nezakážete izolaci.

start

function start(filters?: string[]): Promise<TestRunResult>;

Inicializuje reportéry, poskytovatele pokrytí a spustí testy. Tato metoda přijímá řetězcové filtry pro shodu s testovacími soubory – jedná se o stejné filtry, které podporuje CLI.

WARNING

Tato metoda by neměla být volána, pokud je také vyvolána vitest.init(). Pokud potřebujete spustit testy po inicializaci Vitest, použijte místo toho runTestSpecifications nebo rerunTestSpecifications.

Tato metoda je volána automaticky startVitest, pokud nejsou nastaveny config.mergeReports a config.standalone.

init

function init(): Promise<void>;

Inicializuje reportéry a poskytovatele pokrytí. Tato metoda nespouští žádné testy. Pokud je zadán příznak --watch, Vitest bude stále spouštět změněné testy, i když tato metoda nebyla volána.

Interně je tato metoda volána pouze v případě, že je povolen příznak --standalone.

WARNING

Tato metoda by neměla být volána, pokud je také vyvolána vitest.start().

Tato metoda je volána automaticky startVitest, pokud je nastaveno config.standalone.

getModuleSpecifications

function getModuleSpecifications(moduleId: string): TestSpecification[];

Vrátí seznam testovacích specifikací souvisejících s ID modulu. ID by již mělo být vyřešeno na absolutní cestu k souboru. Pokud se ID neshoduje s vzory include nebo includeSource, vrácené pole bude prázdné.

Tato metoda může vrátit již uložené specifikace na základě moduleId a pool. Všimněte si však, že project.createSpecification vždy vrací novou instanci a není automaticky ukládána do mezipaměti. Specifikace jsou však automaticky ukládány do mezipaměti, když je volána runTestSpecifications.

WARNING

Od Vitest 3 tato metoda používá mezipaměť ke kontrole, zda je soubor testem. Abyste se ujistili, že mezipaměť není prázdná, zavolejte alespoň jednou globTestSpecifications.

clearSpecificationsCache

function clearSpecificationsCache(moduleId?: string): void;

Vitest automaticky ukládá testovací specifikace pro každý soubor, když je volána globTestSpecifications nebo runTestSpecifications. Tato metoda vymaže mezipaměť pro daný soubor nebo celou mezipaměť v závislosti na prvním argumentu.

runTestSpecifications

function runTestSpecifications(
  specifications: TestSpecification[],
  allTestsRun = false
): Promise<TestRunResult>;

Tato metoda spouští každý test na základě přijatých specifikací. Druhý argument, allTestsRun, je používán poskytovatelem pokrytí k určení, zda je třeba instrumentovat pokrytí na každém souboru v kořeni (to je důležité pouze, pokud je pokrytí povoleno a coverage.all je nastaveno na true).

WARNING

Tato metoda nespouští zpětná volání onWatcherRerun, onWatcherStart a onTestsRerun. Pokud spouštíte testy na základě změny souboru, zvažte místo toho použití rerunTestSpecifications.

rerunTestSpecifications

function rerunTestSpecifications(
  specifications: TestSpecification[],
  allTestsRun = false
): Promise<TestRunResult>;

Tato metoda vyvolá události reporter.onWatcherRerun a onTestsRerun, poté spustí testy pomocí runTestSpecifications. Pokud v hlavním procesu nebyly žádné chyby, vyvolá událost reporter.onWatcherStart.

updateSnapshot

function updateSnapshot(files?: string[]): Promise<TestRunResult>;

Aktualizuje snímky v zadaných souborech. Pokud nejsou zadány žádné soubory, aktualizuje soubory s neúspěšnými testy a zastaralými snímky.

collectTests

function collectTests(
  specifications: TestSpecification[]
): Promise<TestRunResult>;

Spustí testovací soubory bez volání zpětných volání testů. collectTests vrací neošetřené chyby a pole testovacích modulů.

Tato metoda funguje přesně stejně jako collect, ale testovací specifikace musíte poskytnout sami.

WARNING

Všimněte si, že Vitest nepoužívá statickou analýzu ke shromažďování testů. Vitest spustí každý testovací soubor izolovaně, stejně jako spouští běžné testy.

To činí tuto metodu velmi pomalou, pokud před shromažďováním testů nezakážete izolaci.

cancelCurrentRun

function cancelCurrentRun(reason: CancelReason): Promise<void>;

Tato metoda elegantně zruší všechny probíhající testy. Počká, až se spuštěné testy dokončí, a nespustí testy, které byly naplánovány ke spuštění, ale ještě nezačaly.

setGlobalTestNamePattern

function setGlobalTestNamePattern(pattern: string | RegExp): void;

Tato metoda přepíše globální vzor názvu testu.

WARNING

Tato metoda nespouští žádné testy. Chcete-li spustit testy s aktualizovaným vzorem, zavolejte runTestSpecifications.

resetGlobalTestNamePattern

function resetGlobalTestNamePattern(): void;

Tato metoda resetuje vzor názvu testu. To znamená, že Vitest nyní nebude přeskočit žádné testy.

WARNING

Tato metoda nespouští žádné testy. Chcete-li spustit testy bez vzoru, zavolejte runTestSpecifications.

enableSnapshotUpdate

function enableSnapshotUpdate(): void;

Povolí režim, který umožňuje aktualizaci snímků při spouštění testů. Každý test, který se spustí po volání této metody, aktualizuje snímky. Pro vypnutí režimu zavolejte resetSnapshotUpdate.

WARNING

Tato metoda nespouští žádné testy. Pro aktualizaci snímků spusťte testy pomocí runTestSpecifications.

resetSnapshotUpdate

function resetSnapshotUpdate(): void;

Zakáže režim, který umožňuje aktualizaci snímků při spouštění testů. Tato metoda nespouští žádné testy.

invalidateFile

function invalidateFile(filepath: string): void;

Tato metoda zneplatní soubor v mezipaměti každého projektu. Je to většinou užitečné, pokud se spoléháte na vlastní sledovač, protože mezipaměť Vite přetrvává v paměti.

DANGER

Pokud zakážete sledovač Vitest, ale necháte Vitest běžet, je důležité ručně vymazat mezipaměť touto metodou, protože neexistuje způsob, jak mezipaměť zakázat. Tato metoda také zneplatní importéry souboru.

import

function import<T>(moduleId: string): Promise<T>

Importuje soubor pomocí spouštěče modulů Vite. Soubor bude transformován Vite s globální konfigurací a spuštěn v samostatném kontextu. Všimněte si, že moduleId bude relativní k config.root.

DANGER

project.import znovu používá graf modulů Vite, takže import stejného modulu pomocí běžného importu vrátí jiný modul:

import * as staticExample from './example.js';
const dynamicExample = await vitest.import('./example.js');

dynamicExample !== staticExample; // ✅

INFO

Interně Vitest používá tuto metodu k importu globálních nastavení, vlastních poskytovatelů pokrytí a vlastních reportérů, což znamená, že všichni sdílejí stejný graf modulů, pokud patří ke stejnému serveru Vite.

close

function close(): Promise<void>;

Uzavře všechny projekty a s nimi spojené zdroje. Toto lze volat pouze jednou; slib uzavření je uložen do mezipaměti, dokud se server nespustí znovu.

exit

function exit(force = false): Promise<void>;

Uzavře všechny projekty a ukončí proces. Pokud je force nastaveno na true, proces se ukončí ihned po uzavření projektů.

Tato metoda také vynuceně zavolá process.exit(), pokud je proces stále aktivní po config.teardownTimeout milisekundách.

shouldKeepServer

function shouldKeepServer(): boolean;

Tato metoda vrátí true, pokud by měl server zůstat spuštěný po dokončení testů. To obvykle znamená, že byl povolen režim watch.

onServerRestart

function onServerRestart(fn: OnServerRestartHandler): void;

Zaregistrujte obslužnou rutinu, která bude volána při restartu serveru z důvodu změny konfigurace.

onCancel

function onCancel(fn: (reason: CancelReason) => Awaitable<void>): void;

Zaregistrujte obslužnou rutinu, která bude volána, když je spuštění testu zrušeno pomocí vitest.cancelCurrentRun.

onClose

function onClose(fn: () => Awaitable<void>): void;

Zaregistrujte obslužnou rutinu, která bude volána při uzavření serveru.

onTestsRerun

function onTestsRerun(fn: OnTestsRerunHandler): void;

Zaregistrujte obslužnou rutinu, která bude volána při opětovném spuštění testů. Testy se mohou spustit znovu, když je ručně volána rerunTestSpecifications nebo když se změní soubor a vestavěný sledovač naplánuje opětovné spuštění.

onFilterWatchedSpecification

function onFilterWatchedSpecification(
  fn: (specification: TestSpecification) => boolean
): void;

Zaregistrujte obslužnou rutinu, která bude volána při změně souboru. Toto zpětné volání by mělo vrátit true nebo false, což indikuje, zda je třeba testovací soubor znovu spustit.

Pomocí této metody se můžete připojit k výchozí logice sledovače a zpozdit nebo zahodit testy, které uživatel v danou chvíli nechce sledovat:

const continuesTests: string[] = [];

myCustomWrapper.onContinuesRunEnabled(testItem =>
  continuesTests.push(item.fsPath)
);

vitest.onFilterWatchedSpecification(specification =>
  continuesTests.includes(specification.moduleId)
);

Vitest může vytvářet různé specifikace pro stejný soubor v závislosti na možnostech pool nebo locations, takže se nespoléhejte na referenci. Vitest může také vrátit uloženou specifikaci z vitest.getModuleSpecifications – mezipaměť je založena na moduleId a pool. Všimněte si, že project.createSpecification vždy vrací novou instanci.

matchesProjectFilter 3.1.0+

function matchesProjectFilter(name: string): boolean;

Zkontroluje, zda se název shoduje s aktuálním filtrem projektu. Pokud není žádný filtr projektu, vrátí vždy true.

Programově nelze změnit možnost CLI --project.