Vitest API

A Vitest példányhoz az aktuális tesztmód megadása szükséges. Ez lehet:

• test tesztek futtatásakor
• benchmark benchmarkok futtatásakor kísérleti

Újdonság a Vitest 3-ban

A Vitest 3 egy lépéssel közelebb került a nyilvános API stabilizálásához. Ennek érdekében bizonyos, korábban nyilvános metódusokat elavulttá nyilvánítottunk és eltávolítottunk a Vitest osztályból. Ezek az API-k privátak lettek:

• configOverride (használja a setGlobalTestNamePattern vagy enableSnapshotUpdate függvényt)
• coverageProvider
• filenamePattern
• runningPromise
• closingPromise
• isCancelling
• coreWorkspaceProject
• resolvedProjects
• _browserLastPort
• _options
• reporters
• vitenode
• runner
• pool
• setServer
• _initBrowserServers
• rerunTask
• changeProjectName
• changeNamePattern
• changeFilenamePattern
• rerunFailed
• _createRootProject (átnevezve _ensureRootProject-re, de továbbra is privát)
• filterTestsBySource (ez az új belső vitest.specifications példányba került)
• runFiles (használja helyette a runTestSpecifications metódust)
• onAfterSetServer

Ezek az API-k elavulttá váltak:

• invalidates
• changedTests (használja helyette az onFilterWatchedSpecification metódust)
• server (használja helyette a vite metódust)
• getProjectsByTestFile (használja helyette a getModuleSpecifications metódust)
• getFileWorkspaceSpecs (használja helyette a getModuleSpecifications metódust)
• getModuleProjects (szűrje a this.projects alapján)
• updateLastChanged (átnevezve invalidateFile-re)
• globTestSpecs (használja helyette a globTestSpecifications metódust)
• globTestFiles (használja helyette a globTestSpecifications metódust)
• listFile (használja helyette a getRelevantTestSpecifications metódust)

mode

test

A teszt mód csak a test vagy it függvényeket hívja meg, és hibát dob, ha bench-et talál. Ez a mód a konfiguráció include és exclude opcióit használja a tesztfájlok megtalálásához.

benchmark kísérleti

A benchmark mód a bench függvényeket hívja meg, és hibát dob, ha test vagy it függvényt talál. Ez a mód a konfiguráció benchmark.include és benchmark.exclude opcióit használja a benchmark fájlok megtalálásához.

config

A gyökér (vagy globális) konfiguráció. Ha projektek vannak definiálva, azok globalConfig-ként hivatkoznak erre.

WARNING

Ez a Vitest konfiguráció, nem bővíti a Vite konfigurációt. Csak a test tulajdonságból feloldott értékeket tartalmazza.

vite

Ez egy globális ViteDevServer példány.

state kísérleti

WARNING

A nyilvános state egy kísérleti API (kivéve a vitest.state.getReportedEntity). A változások nem feltétlenül követik a SemVer-t, kérjük, fixálja a Vitest verzióját a használat során.

A globális állapot az aktuális tesztekre vonatkozó információkat tárolja. Alapértelmezés szerint ugyanazt az API-t használja, mint a @vitest/runner, de javasoljuk, hogy ehelyett a Jelentett feladatok API-t használja a state.getReportedEntity() meghívásával a @vitest/runner API-n keresztül:

const task = vitest.state.idMap.get(taskId); // régi API
const testCase = vitest.state.getReportedEntity(task); // új API

A jövőben a régi API már nem lesz elérhető.

snapshot

Ez a globális pillanatkép-kezelő. A Vitest a snapshot.add metódus segítségével tartja nyilván az összes pillanatképet.

A pillanatképek legfrissebb összefoglalóját a vitest.snapshot.summary tulajdonságon keresztül érheti el.

cache

Ez egy gyorsítótár-kezelő, amely információkat tárol a legújabb teszteredményekről és tesztfájl-statisztikákról. Magában a Vitestben ezt csak az alapértelmezett szekvencer használja a tesztek rendezéséhez.

projects

Ez a felhasználó projektjeihez tartozó tesztprojektek tömbje. Ha a felhasználó nem adott meg projekteket, ez a tömb csak egy gyökérprojektet fog tartalmazni.

A Vitest biztosítja, hogy ebben a tömbben mindig legyen legalább egy projekt. Ha a felhasználó nem létező --project nevet ad meg, a Vitest hibát dob, mielőtt ez a tömb létrejönne.

getRootProject

function getRootProject(): TestProject;

Ez a gyökér tesztprojektet adja vissza. A gyökérprojekt rendszerint nem futtat teszteket, és nem szerepel a vitest.projects tömbben, kivéve, ha a felhasználó explicit módon belefoglalja a gyökérkonfigurációt a saját konfigurációjába, vagy ha egyáltalán nincsenek projektek definiálva.

A gyökérprojekt elsődleges célja a globális konfiguráció inicializálása. Valójában a rootProject.config közvetlenül hivatkozik a rootProject.globalConfig-ra és a vitest.config-ra:

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

provide

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

A Vitest provide metódusa elérhetővé teszi a vitest.getRootProject().provide rövidítést. Ezzel a metódussal értékeket adhat át a fő szálból a teszteknek. Minden érték ellenőrzésre kerül a structuredClone segítségével a tárolás előtt, de maguk az értékek nem klónozódnak.

Az értékek tesztben való fogadásához importálnia kell az inject metódust a vitest belépési pontból:

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

A jobb típusbiztonság érdekében javasoljuk a ProvidedContext típusának bővítését:

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

Technikailag a provide a TestProject metódusa, ezért az adott projektre korlátozódik. Azonban minden projekt örökli az értékeket a gyökérprojektből, ami a vitest.provide-ot univerzális módszerré teszi az értékek tesztekhez való átadására.

getProvidedContext

function getProvidedContext(): ProvidedContext;

Ez a gyökér kontextus objektumot adja vissza. Ez a vitest.getRootProject().getProvidedContext rövidítése.

getProjectByName

function getProjectByName(name: string): TestProject;

Ez a metódus a projektet a neve alapján adja vissza. Hasonló a vitest.projects.find hívásához.

WARNING

Ha a projekt nem létezik, ez a metódus a gyökérprojektet adja vissza – győződjön meg róla, hogy újra ellenőrzi a neveket, ha a visszaadott projekt az, amit keresett.

Ha a felhasználó nem szabott testre nevet, a Vitest üres sztringet rendel hozzá.

globTestSpecifications

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

Ez a metódus új teszt specifikációkat hoz létre azáltal, hogy minden projektben összegyűjti az összes tesztet a project.globTestFiles segítségével. Sztringszűrőket fogad el a tesztfájlok szűréséhez – ezek ugyanazok a szűrők, amelyeket a CLI támogat.

Ez a metódus automatikusan gyorsítótárba helyezi az összes teszt specifikációt. Amikor legközelebb meghívja a getModuleSpecifications metódust, ugyanazokat a specifikációkat adja vissza, kivéve, ha előtte meghívták a clearSpecificationsCache metódust.

WARNING

A Vitest 3-tól kezdve lehetséges, hogy több teszt specifikáció is ugyanazzal a modulazonosítóval (fájlútvonal) rendelkezik, ha a poolMatchGlob több poolt tartalmaz, vagy ha a typecheck engedélyezve van. Ez a lehetőség a Vitest 4-ben megszűnik.

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

getRelevantTestSpecifications

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

Ez a metódus minden teszt specifikációt felold a project.globTestFiles meghívásával. Sztringszűrőket fogad el a tesztfájlok illesztéséhez – ezek ugyanazok a szűrők, amelyeket a CLI támogat. Ha a --changed jelzőt megadták, a lista szűrve lesz, hogy csak a megváltozott fájlokat tartalmazza. A getRelevantTestSpecifications nem futtat tesztfájlokat.

WARNING

Ez a metódus lassú lehet, mert a --changed jelzők alapján kell szűrnie. Ne használja, ha csak a tesztfájlok listájára van szüksége.

• Ha ismert tesztfájlokhoz szeretné lekérni a specifikációk listáját, használja a getModuleSpecifications metódust.
• Ha az összes lehetséges tesztfájl listáját szeretné lekérni, használja a globTestSpecifications metódust.

mergeReports

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

Jelentések egyesítése több futtatásból, amelyek a megadott könyvtárban helyezkednek el (érték a --merge-reports paraméterből, ha nincs megadva). Ez az érték beállítható a config.mergeReports tulajdonságon is (alapértelmezés szerint a .vitest-reports mappát fogja olvasni).

Vegye figyelembe, hogy a directory mindig a munkakönyvtárhoz képest lesz értelmezve.

Ezt a metódust a startVitest automatikusan meghívja, ha a config.mergeReports be van állítva.

collect

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

Tesztfájlok végrehajtása teszt visszahívások meghívása nélkül. A collect kezeletlen hibákat és egy tesztmodulok tömbjét adja vissza. Sztringszűrőket fogad el a tesztfájlok illesztéséhez – ezek ugyanazok a szűrők, amelyeket a CLI támogat.

Ez a metódus a konfiguráció include, exclude, és includeSource értékei alapján határozza meg a teszt specifikációkat. További információkért olvassa el a project.globTestFiles részt. Ha a --changed jelzőt megadták, a lista szűrve lesz, hogy csak a megváltozott fájlokat tartalmazza.

WARNING

Vegye figyelembe, hogy a Vitest nem használ statikus elemzést a tesztek felderítésére. A Vitest minden tesztfájlt izoláltan futtat, akárcsak a hagyományos teszteket.

Ez a metódus nagyon lassúvá válhat, hacsak nem kapcsolja ki az izolációt a tesztek felderítése előtt.

start

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

Inicializálja a jelentéskészítőket, a lefedettség-szolgáltatót, és futtatja a teszteket. Ez a metódus sztringszűrőket fogad el a tesztfájlok illesztéséhez – ezek ugyanazok a szűrők, amelyeket a CLI támogat.

WARNING

Ezt a metódust nem szabad meghívni, ha a vitest.init() is meghívásra kerül. Használja a runTestSpecifications vagy rerunTestSpecifications metódust, ha a Vitest inicializálása után szeretne teszteket futtatni.

Ezt a metódust a startVitest automatikusan meghívja, ha a config.mergeReports és a config.standalone nincs konfigurálva.

init

function init(): Promise<void>;

Inicializálja a riportolókat és a lefedettség-szolgáltatót. Ez a metódus nem futtat teszteket. Ha a --watch jelzőt megadták, a Vitest akkor is futtatja a megváltozott teszteket, ha ezt a metódust nem hívták meg.

Belsőleg ezt a metódust csak akkor hívja meg a rendszer, ha a --standalone jelző engedélyezve van.

WARNING

Ezt a metódust nem szabad meghívni, ha a vitest.start() is meghívásra kerül.

Ezt a metódust a startVitest automatikusan meghívja, ha a config.standalone be van állítva.

getModuleSpecifications

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

Visszaadja a modulazonosítóhoz tartozó teszt specifikációk listáját. Az azonosítónak már abszolút fájlútvonalra kell mutatnia. Ha az azonosító nem illeszkedik az include vagy includeSource mintákhoz, a visszaadott tömb üres lesz.

Ez a metódus már gyorsítótárazott specifikációkat is visszaadhat a moduleId és pool alapján. De vegye figyelembe, hogy a project.createSpecification mindig új példányt ad vissza, és nem kerül automatikusan gyorsítótárba. Azonban a specifikációk automatikusan gyorsítótárba kerülnek, amikor a runTestSpecifications meghívásra kerül.

WARNING

A Vitest 3-tól kezdve ez a metódus gyorsítótárat használ annak ellenőrzésére, hogy a fájl teszt-e. Annak biztosításához, hogy a gyorsítótár ne legyen üres, hívja meg a globTestSpecifications metódust legalább egyszer.

clearSpecificationsCache

function clearSpecificationsCache(moduleId?: string): void;

A Vitest automatikusan gyorsítótárba helyezi a teszt specifikációkat minden fájlhoz, amikor a globTestSpecifications vagy runTestSpecifications meghívásra kerül. Ez a metódus törli a gyorsítótárat az adott fájlhoz, vagy az egész gyorsítótárat, az első argumentumtól függően.

runTestSpecifications

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

Ez a metódus minden tesztet futtat a kapott specifikációk alapján. A második argumentum, az allTestsRun, a lefedettség-szolgáltató által használatos annak meghatározására, hogy minden fájlon kell-e lefedettséget mérnie a gyökérben (ez csak akkor releváns, ha a lefedettség engedélyezve van, és a coverage.all true-ra van állítva).

WARNING

Ez a metódus nem váltja ki az onWatcherRerun, onWatcherStart és onTestsRerun visszahívásokat. Ha fájlváltozás miatt futtatja újra a teszteket, fontolja meg a rerunTestSpecifications használatát.

rerunTestSpecifications

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

Ez a metódus kibocsátja a reporter.onWatcherRerun és onTestsRerun eseményeket, majd futtatja a teszteket a runTestSpecifications segítségével. Ha nem volt hiba a fő folyamatban, akkor kiadja a reporter.onWatcherStart eseményt.

updateSnapshot

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

Pillanatképek frissítése a megadott fájlokban. Ha nincsenek fájlok megadva, akkor a sikertelen teszteket és az elavult pillanatképeket tartalmazó fájlokat frissíti.

collectTests

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

Tesztfájlok végrehajtása teszt visszahívások futtatása nélkül. A collectTests kezeletlen hibákat és tesztmodulok tömbjét adja vissza.

Ez a metódus pontosan ugyanúgy működik, mint a collect, de a teszt specifikációkat Önnek kell megadnia.

WARNING

Vegye figyelembe, hogy a Vitest nem használ statikus elemzést a tesztek gyűjtésére. A Vitest minden tesztfájlt izoláltan futtat, akárcsak a szokásos teszteket.

Ez a metódus nagyon lassúvá teszi, hacsak nem kapcsolja ki az izolációt a tesztek gyűjtése előtt.

cancelCurrentRun

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

Ez a metódus szabályosan megszakítja az összes folyamatban lévő tesztet. Megvárja a már elindított tesztek befejezését, és nem futtatja azokat a teszteket, amelyek futtatásra voltak ütemezve, de még nem kezdődtek el.

setGlobalTestNamePattern

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

Ez a metódus felülbírálja a globális tesztnév mintát.

WARNING

Ez a metódus nem indít el teszteket. A tesztek futtatásához a frissített mintával hívja meg a runTestSpecifications metódust.

resetGlobalTestNamePattern

function resetGlobalTestNamePattern(): void;

Ez a metódus alaphelyzetbe állítja a tesztnév mintát. Ez azt jelenti, hogy a Vitest mostantól nem hagy ki teszteket.

WARNING

Ez a metódus nem indít el teszteket. A tesztek minta nélküli futtatásához hívja meg a runTestSpecifications metódust.

enableSnapshotUpdate

function enableSnapshotUpdate(): void;

Engedélyezi azt a módot, amely lehetővé teszi a pillanatképek frissítését a tesztek futtatása közben. Minden teszt, amely e metódus meghívása után fut, frissíti a pillanatképeket. A mód letiltásához hívja meg a resetSnapshotUpdate metódust.

WARNING

Ez a metódus nem indít el teszteket. A pillanatképek frissítéséhez futtassa a teszteket a runTestSpecifications metódussal.

resetSnapshotUpdate

function resetSnapshotUpdate(): void;

Letiltja azt a módot, amely lehetővé teszi a pillanatképek frissítését a tesztek futtatásakor. Ez a metódus nem indít el teszteket.

invalidateFile

function invalidateFile(filepath: string): void;

Ez a metódus érvényteleníti a fájlt minden projekt gyorsítótárában. Ez leginkább akkor hasznos, ha saját figyelőre támaszkodik, mert a Vite gyorsítótára a memóriában tárolódik.

DANGER

Ha letiltja a Vitest figyelőjét, de a Vitestet futva hagyja, fontos, hogy manuálisan törölje a gyorsítótárat ezzel a metódussal, mivel nincs mód a gyorsítótár letiltására. Ez a metódus érvényteleníti a fájl importálóit is.

import

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

Fájl importálása a Vite modul futtatóval. A fájlt a Vite átalakítja a globális konfigurációval, és külön kontextusban futtatja. Vegye figyelembe, hogy a moduleId a config.root-hoz képest relatív útvonalat jelent.

DANGER

A project.import újra felhasználja a Vite modulgráfját, így ugyanazon modul hagyományos importálással történő importálása eltérő modult ad vissza:

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

dynamicExample !== staticExample; // ✅

INFO

Belsőleg a Vitest ezt a metódust használja a globális beállítások, egyéni lefedettség-szolgáltatók és egyéni jelentéskészítők importálására, ami azt jelenti, hogy mindegyik ugyanazt a modulgráfot osztja meg, amíg ugyanahhoz a Vite szerverhez tartoznak.

close

function close(): Promise<void>;

Bezárja az összes projektet és a kapcsolódó erőforrásokat. Ez csak egyszer hívható meg; a bezárási ígéret gyorsítótárban marad a szerver újraindításáig.

exit

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

Bezárja az összes projektet és kilép a folyamatból. Ha a force értéke true, a folyamat azonnal leáll a projektek bezárása után.

Ez a metódus akkor is kényszerítetten meghívja a process.exit()-et, ha a folyamat még aktív a config.teardownTimeout milliszekundum letelte után.

shouldKeepServer

function shouldKeepServer(): boolean;

Ez a metódus true értéket ad vissza, ha a szervert a tesztek befejezése után is futva kell hagyni. Ez általában azt jelenti, hogy a watch mód engedélyezve lett.

onServerRestart

function onServerRestart(fn: OnServerRestartHandler): void;

Regisztrál egy kezelőt, amely meghívásra kerül, amikor a szerver újraindul egy konfigurációs változás miatt.

onCancel

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

Regisztrál egy kezelőt, amely meghívásra kerül, amikor a tesztfuttatás megszakításra kerül a vitest.cancelCurrentRun segítségével.

onClose

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

Regisztrál egy kezelőt, amely meghívásra kerül, amikor a szerver leáll.

onTestsRerun

function onTestsRerun(fn: OnTestsRerunHandler): void;

Regisztrál egy kezelőt, amely meghívásra kerül, amikor a tesztek újraindulnak. A tesztek újraindulhatnak, ha a rerunTestSpecifications manuálisan meghívásra kerül, vagy ha egy fájl megváltozik, és a beépített figyelő újra futtatást ütemez.

onFilterWatchedSpecification

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

Regisztrál egy kezelőt, amely akkor hívódik meg, amikor egy fájl megváltozik. Ennek a visszahívásnak true vagy false értéket kell visszaadnia, jelezve, hogy a tesztfájlt újra kell-e futtatni.

Ezzel a metódussal beavatkozhat az alapértelmezett figyelő logikájába, hogy késleltesse vagy elvetje azokat a teszteket, amelyeket a felhasználó jelenleg nem szeretne nyomon követni:

const continuesTests: string[] = [];

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

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

A Vitest különböző specifikációkat hozhat létre ugyanahhoz a fájlhoz a pool vagy locations opcióktól függően, ezért ne hagyatkozzon a referenciára. A Vitest gyorsítótárazott specifikációt is visszaadhat a vitest.getModuleSpecifications metódusból – a gyorsítótár a moduleId és a pool alapján épül fel. Vegye figyelembe, hogy a project.createSpecification mindig új példányt ad vissza.

matchesProjectFilter 3.1.0+

function matchesProjectFilter(name: string): boolean;

Ellenőrzi, hogy a név megfelel-e az aktuális projekt szűrőnek. Ha nincs projekt szűrő beállítva, ez mindig true értéket ad vissza.

A --project CLI opciót programozottan nem lehet módosítani.