Vitest API

Vitest örneği için mevcut test modu gereklidir. Bu modlar şunlardır:

• Çalışma zamanı testleri çalıştırıldığında test
• Kıyaslamalar çalıştırıldığında benchmark deneysel

Vitest 3'teki Yenilikler

Vitest 3, genel API'yi stabilize etmeye bir adım daha yaklaştı. Bunu başarmak için, Vitest sınıfındaki daha önce genel olan bazı yöntemleri kullanımdan kaldırdık ve kaldırdık. Bu API'ler özel (private) hale getirildi:

• configOverride (setGlobalTestNamePattern veya enableSnapshotUpdate kullanın)
• coverageProvider
• filenamePattern
• runningPromise
• closingPromise
• isCancelling
• coreWorkspaceProject
• resolvedProjects
• _browserLastPort
• _options
• reporters
• vitenode
• runner
• pool
• setServer
• _initBrowserServers
• rerunTask
• changeProjectName
• changeNamePattern
• changeFilenamePattern
• rerunFailed
• _createRootProject (_ensureRootProject olarak yeniden adlandırıldı, ancak hala özel)
• filterTestsBySource (bu, yeni dahili vitest.specifications örneğine taşındı)
• runFiles (bunun yerine runTestSpecifications kullanın)
• onAfterSetServer

Bu API'ler kullanımdan kaldırıldı (deprecated):

• invalidates
• changedTests (bunun yerine onFilterWatchedSpecification kullanın)
• server (bunun yerine vite kullanın)
• getProjectsByTestFile (bunun yerine getModuleSpecifications kullanın)
• getFileWorkspaceSpecs (bunun yerine getModuleSpecifications kullanın)
• getModuleProjects (kendiniz this.projects ile filtreleyin)
• updateLastChanged (invalidateFile olarak yeniden adlandırıldı)
• globTestSpecs (bunun yerine globTestSpecifications kullanın)
• globTestFiles (bunun yerine globTestSpecifications kullanın)
• listFile (bunun yerine getRelevantTestSpecifications kullanın)

mode

test

Test modu yalnızca test veya it içindeki fonksiyonları çağırır ve bench ile karşılaşıldığında hata verir. Bu mod, test dosyalarını bulmak için yapılandırmanın include ve exclude seçeneklerini kullanır.

benchmark deneysel

Benchmark modu bench fonksiyonlarını çağırır ve test veya it ile karşılaştığında hata verir. Bu mod, kıyaslama dosyalarını bulmak için yapılandırmanın benchmark.include ve benchmark.exclude seçeneklerini kullanır.

config

Kök (veya global) yapılandırma. Projeler tanımlanmışsa, bunu globalConfig olarak referans göstereceklerdir.

WARNING

Bu Vitest yapılandırmasıdır, Vite yapılandırmasını genişletmez. Yalnızca test özelliğinden çözümlenmiş değerleri içerir.

vite

Bu, genel bir ViteDevServer'dır.

state deneysel

WARNING

Global state deneysel bir API'dir (vitest.state.getReportedEntity hariç). Kırıcı değişiklikler SemVer'i takip etmeyebilir, lütfen kullanırken Vitest'in sürümünü sabitleyin.

Global state, mevcut testler hakkındaki bilgileri saklar. Varsayılan olarak @vitest/runner'dan aynı API'yi kullanır, ancak bunun yerine @vitest/runner API'sinde state.getReportedEntity() çağırarak Raporlanan Görevler API'sini kullanmanızı öneririz:

const task = vitest.state.idMap.get(taskId); // eski API
const testCase = vitest.state.getReportedEntity(task); // yeni API

Gelecekte, eski API artık erişilebilir olmayacaktır.

snapshot

Global snapshot yöneticisi. Vitest, snapshot.add yöntemini kullanarak tüm anlık görüntüleri izler.

vitest.snapshot.summary özelliği aracılığıyla anlık görüntülerin en son özetini alabilirsiniz.

cache

Son test sonuçları ve test dosyası istatistikleri hakkında bilgi saklayan önbellek yöneticisi. Vitest'in kendisinde bu, testleri sıralamak için yalnızca varsayılan sıralayıcı tarafından kullanılır.

projects

Kullanıcının projelerine ait test projeleri dizisi. Kullanıcı bunları belirtmediği takdirde, bu dizi yalnızca bir kök proje içerecektir.

Vitest, bu dizide her zaman en az bir proje olmasını sağlayacaktır. Kullanıcı var olmayan bir --project adı belirtirse, Vitest bu dizi tanımlanmadan önce hata verecektir.

getRootProject

function getRootProject(): TestProject;

Bu, kök test projesini döndürür. Kök proje genellikle herhangi bir test çalıştırmaz ve kullanıcı kök yapılandırmayı açıkça yapılandırmasına dahil etmedikçe veya projeler hiç tanımlanmadıkça vitest.projects'e dahil edilmez.

Kök projenin birincil amacı, genel yapılandırmayı ayarlamaktır. Aslında, rootProject.config, rootProject.globalConfig ve vitest.config'i doğrudan referans gösterir:

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

provide

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

Vitest, vitest.getRootProject().provide için bir kısayol olan provide yöntemini sunar. Bu yöntemle ana iş parçacığından (main thread) testlere değerler aktarabilirsiniz. Tüm değerler depolanmadan önce structuredClone ile kontrol edilir, ancak değerlerin kendileri klonlanmaz.

Testlerde değerleri almak için vitest giriş noktasından inject yöntemini içe aktarmanız gerekir:

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

Daha iyi tip güvenliği için, ProvidedContext tipini genişletmeniz önerilir:

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

Teknik olarak, provide bir TestProject yöntemidir, bu nedenle belirli bir projeyle sınırlıdır. Ancak, tüm projeler kök projeden değerleri miras alır, bu da vitest.provide'ı testlere değer aktarımında evrensel bir yöntem haline getirir.

getProvidedContext

function getProvidedContext(): ProvidedContext;

Bu, vitest.getRootProject().getProvidedContext için bir kısayol olan kök bağlam nesnesini döndürür.

getProjectByName

function getProjectByName(name: string): TestProject;

Bu yöntem, projeyi adına göre döndürür. vitest.projects.find çağrısı gibidir.

WARNING

Proje mevcut değilse, bu yöntem kök projeyi döndürecektir. Aradığınız projenin döndürülen proje olduğundan emin olmak için adları tekrar kontrol edin.

Kullanıcı bir ad özelleştirmediyse, Vitest boş bir dizeyi ad olarak belirleyecektir.

globTestSpecifications

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

Bu yöntem, project.globTestFiles ile tüm projelerdeki her testi toplayarak yeni test spesifikasyonları oluşturur. Test dosyalarını eşleştirmek için dize filtreleri kabul eder; bunlar CLI'nin desteklediği aynı filtrelerdir.

Bu yöntem, tüm test spesifikasyonlarını otomatik olarak önbelleğe alır. getModuleSpecifications bir sonraki çağrıldığında, clearSpecificationsCache daha önce çağrılmadıkça aynı spesifikasyonları döndürecektir.

WARNING

Vitest 3'ten itibaren, poolMatchGlob'un birden fazla havuzu varsa veya typecheck etkinse, aynı modül kimliğine (dosya yolu) sahip birden fazla test spesifikasyonu olması mümkündür. Bu olasılık Vitest 4'te kaldırılacaktır.

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

getRelevantTestSpecifications

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

Bu yöntem, project.globTestFiles çağrısıyla her test spesifikasyonunu çözer. Test dosyalarını eşleştirmek için dize filtreleri kabul eder; bunlar CLI'nin desteklediği aynı filtrelerdir. --changed bayrağı belirtilmişse, liste yalnızca değişen dosyaları içerecek şekilde filtrelenecektir. getRelevantTestSpecifications herhangi bir test dosyası çalıştırmaz.

WARNING

Bu yöntem, --changed bayraklarını filtrelemesi gerektiğinden dolayı yavaş olabilir. Yalnızca test dosyalarının bir listesine ihtiyacınız varsa kullanmayın.

• Bilinen test dosyaları için spesifikasyonların listesini almanız gerekiyorsa, getModuleSpecifications kullanın.
• Tüm olası test dosyalarının listesini almanız gerekiyorsa, globTestSpecifications kullanın.

mergeReports

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

Belirtilen dizinde bulunan birden çok çalıştırmadan gelen raporları birleştirir (belirtilmezse --merge-reports değeri kullanılır). Bu değer config.mergeReports üzerinde de ayarlanabilir (varsayılan olarak .vitest-reports klasörünü okuyacaktır).

directory'nin her zaman çalışma dizinine göre çözümleneceğini unutmayın.

Bu yöntem, config.mergeReports ayarlandığında startVitest tarafından otomatik olarak çağrılır.

collect

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

Test geri çağrılarını çalıştırmadan test dosyalarını yürütür. collect işlenmeyen hataları ve bir test modülleri dizisini döndürür. Test dosyalarını eşleştirmek için dize filtreleri kabul eder; bunlar CLI'nin desteklediği aynı filtrelerdir.

Bu yöntem, yapılandırmadaki include, exclude ve includeSource değerlerine göre test spesifikasyonlarını çözer. Daha fazla bilgi için project.globTestFiles adresine bakın. --changed bayrağı belirtilmişse, liste yalnızca değişen dosyaları içerecek şekilde filtrelenecektir.

WARNING

Vitest'in testleri toplamak için statik analiz kullanmadığını belirtmek gerekir. Vitest, her test dosyasını yalıtılmış olarak, tıpkı normal testleri çalıştırdığı gibi çalıştıracaktır.

Bu, testleri toplamadan önce izolasyonu devre dışı bırakmazsanız bu yöntemi çok yavaş hale getirir.

start

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

Raporlayıcıları ve kapsama sağlayıcısını başlatır ve testleri çalıştırır. Bu yöntem, test dosyalarını eşleştirmek için dize filtreleri kabul eder; bunlar CLI'nin desteklediği aynı filtrelerdir.

WARNING

Bu yöntem, vitest.init() de çağrılırsa çağrılmamalıdır. Vitest başlatıldıktan sonra testleri çalıştırmanız gerekiyorsa bunun yerine runTestSpecifications veya rerunTestSpecifications kullanın.

Bu yöntem, config.mergeReports ve config.standalone ayarlı değilse startVitest tarafından otomatik olarak çağrılır.

init

function init(): Promise<void>;

Raporlayıcıları ve kapsama sağlayıcısını başlatır. Bu yöntem herhangi bir test çalıştırmaz. --watch bayrağı sağlanırsa, bu yöntem çağrılmasa bile Vitest değişen testleri yine de çalıştıracaktır.

Dahili olarak, bu yöntem yalnızca --standalone bayrağı etkinse çağrılır.

WARNING

Bu yöntem, vitest.start() de çağrılırsa çağrılmamalıdır.

Bu yöntem, config.standalone ayarlıysa startVitest tarafından otomatik olarak çağrılır.

getModuleSpecifications

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

Modül kimliğiyle ilgili test spesifikasyonlarının bir listesini döndürür. Kimlik zaten mutlak bir dosya yoluna çözümlenmiş olması gerekir. Kimlik include veya includeSource desenleriyle eşleşmezse, döndürülen dizi boş olacaktır.

Bu yöntem, moduleId ve pool'a göre zaten önbelleğe alınmış spesifikasyonları döndürebilir. Ancak project.createSpecification her zaman yeni bir örnek döndürür ve otomatik olarak önbelleğe alınmaz. Ancak, runTestSpecifications çağrıldığında spesifikasyonlar otomatik olarak önbelleğe alınır.

WARNING

Vitest 3'ten itibaren, bu yöntem dosyanın bir test olup olmadığını kontrol etmek için bir önbellek kullanır. Önbelleğin boş olmadığından emin olmak için, globTestSpecifications en az bir kez çağrılmalıdır.

clearSpecificationsCache

function clearSpecificationsCache(moduleId?: string): void;

Vitest, globTestSpecifications veya runTestSpecifications çağrıldığında her dosya için test spesifikasyonlarını otomatik olarak önbelleğe alır. Bu yöntem, ilk argümana bağlı olarak verilen dosya için önbelleği veya tüm önbelleği temizler.

runTestSpecifications

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

Bu yöntem, alınan spesifikasyonlara göre her testi çalıştırır. İkinci argüman olan allTestsRun, kapsama sağlayıcısı tarafından kökteki her dosyada kapsama enstrümanı yapılıp yapılmayacağını belirlemek için kullanılır (bu yalnızca kapsama etkinleştirilmişse ve coverage.all true olarak ayarlanmışsa önemlidir).

WARNING

Bu yöntem onWatcherRerun, onWatcherStart ve onTestsRerun geri çağrılarını tetiklemez. Dosya değişikliğine göre testleri yeniden çalıştırıyorsanız, rerunTestSpecifications kullanmayı düşünün.

rerunTestSpecifications

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

Bu yöntem reporter.onWatcherRerun ve onTestsRerun olaylarını tetikler, ardından runTestSpecifications ile testleri çalıştırır. Ana süreçte hata yoksa, reporter.onWatcherStart olayını tetikler.

updateSnapshot

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

Belirtilen dosyalardaki anlık görüntüleri günceller. Dosya sağlanmazsa, başarısız testleri ve eski anlık görüntüleri olan dosyaları güncelleyecektir.

collectTests

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

Test geri çağrılarını çalıştırmadan test dosyalarını yürütür. collectTests işlenmeyen hataları ve bir test modülleri dizisini döndürür.

Bu yöntem, collect ile tamamen aynı şekilde çalışır, ancak test spesifikasyonlarını kendiniz sağlamalısınız.

WARNING

Vitest'in testleri toplamak için statik analiz kullanmadığını belirtmek gerekir. Vitest, her test dosyasını yalıtılmış olarak, tıpkı normal testleri çalıştırdığı gibi çalıştıracaktır.

Bu, testleri toplamadan önce izolasyonu devre dışı bırakmazsanız bu yöntemi çok yavaş hale getirir.

cancelCurrentRun

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

Bu yöntem, devam eden tüm testleri düzgün bir şekilde iptal edecektir. Başlayan testlerin bitmesini bekleyecek ve çalıştırılması planlanan ancak henüz başlamamış testleri çalıştırmayacaktır.

setGlobalTestNamePattern

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

Bu yöntem, genel test adı desenini geçersiz kılar.

WARNING

Bu yöntem herhangi bir test çalıştırmaz. Güncellenmiş desenle testleri çalıştırmak için runTestSpecifications çağrılmalıdır.

resetGlobalTestNamePattern

function resetGlobalTestNamePattern(): void;

Bu yöntem, test adı desenini sıfırlar. Bu, Vitest'in artık hiçbir testi atlamayacağı anlamına gelir.

WARNING

Bu yöntem herhangi bir test çalıştırmaz. Desen olmadan testleri çalıştırmak için runTestSpecifications çağrılmalıdır.

enableSnapshotUpdate

function enableSnapshotUpdate(): void;

Testler çalıştırılırken snapshot'ların güncellenmesine izin veren modu etkinleştirir. Bu yöntem çağrıldıktan sonra çalışan her test anlık görüntüleri güncelleyecektir. Modu devre dışı bırakmak için resetSnapshotUpdate çağrılmalıdır.

WARNING

Bu yöntem herhangi bir test çalıştırmaz. Anlık görüntüleri güncellemek için testler runTestSpecifications ile çalıştırılmalıdır.

resetSnapshotUpdate

function resetSnapshotUpdate(): void;

Testler çalıştırılırken anlık görüntülerin güncellenmesine izin veren modu devre dışı bırakır. Bu yöntem herhangi bir test çalıştırmaz.

invalidateFile

function invalidateFile(filepath: string): void;

Bu yöntem, her projenin önbelleğindeki dosyayı geçersiz hale getirir. Bu, Vite'nin önbelleği bellekte kaldığı için kendi izleyicinize güveniyorsanız çoğunlukla kullanışlıdır.

DANGER

Vitest'in izleyicisini devre dışı bırakıp Vitest'i çalışır durumda tutarsanız, önbelleği devre dışı bırakmanın bir yolu olmadığı için önbelleği bu yöntemle manuel olarak temizlemek önemlidir. Bu yöntem ayrıca dosyanın içe aktarıcılarını da geçersiz kılacaktır.

import

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

Vite modül çalıştırıcısını kullanarak bir dosyayı içe aktarır. Dosya, genel yapılandırma ile Vite tarafından dönüştürülecek ve ayrı bir bağlamda yürütülecektir. moduleId'nin config.root'a göre olacağını belirtmek gerekir.

DANGER

project.import Vite'nin modül grafiğini tekrar kullanır, bu nedenle aynı modülü normal bir içe aktarma kullanarak içe aktarmak farklı bir modül döndürecektir:

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

dynamicExample !== staticExample; // ✅

INFO

Dahili olarak, Vitest bu yöntemi genel kurulumları, özel kapsama sağlayıcılarını ve özel raporlayıcıları içe aktarmak için kullanır; bu da hepsi aynı Vite sunucusuna ait oldukları sürece aynı modül grafiğini paylaştıkları anlamına gelir.

close

function close(): Promise<void>;

Tüm projeleri ve ilişkili kaynaklarını kapatır. Bu yalnızca bir kez çağrılabilir; kapatma vaadi sunucu yeniden başlayana kadar önbelleğe alınır.

exit

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

Tüm projeleri kapatır ve işlemi sonlandırır. force true olarak ayarlanırsa, işlem projeler kapatıldıktan hemen sonra sonlandırılacaktır.

Bu yöntem, config.teardownTimeout milisaniye sonra işlem hala aktifse process.exit()'i zorla çağırır.

shouldKeepServer

function shouldKeepServer(): boolean;

Bu yöntem, testler bittikten sonra sunucunun çalışır durumda kalması gerekiyorsa true döndürecektir. Bu genellikle watch modunun etkinleştirildiği anlamına gelir.

onServerRestart

function onServerRestart(fn: OnServerRestartHandler): void;

Yapılandırma değişikliği nedeniyle sunucu yeniden başlatıldığında çağrılacak bir işleyici kaydeder.

onCancel

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

Test çalıştırması iptal edildiğinde çağrılacak bir işleyici kaydeder.

onClose

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

Sunucu kapatıldığında çağrılacak bir işleyici kaydeder.

onTestsRerun

function onTestsRerun(fn: OnTestsRerunHandler): void;

Testler yeniden çalıştırıldığında çağrılacak bir işleyici kaydeder. Testler, rerunTestSpecifications manuel olarak çağrıldığında veya bir dosya değiştirildiğinde ve yerleşik izleyici yeniden çalıştırma planladığında yeniden çalıştırılabilir.

onFilterWatchedSpecification

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

Bir dosya değiştirildiğinde çağrılacak bir işleyici kaydeder. Bu geri çağrı true veya false döndürmelidir, test dosyasının yeniden çalıştırılması gerekip gerekmediğini belirtir.

Bu yöntemle, kullanıcının şu anda takip etmek istemediği testleri geciktirmek veya atmak için varsayılan izleyici mantığına müdahale edebilirsiniz:

const continuesTests: string[] = [];

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

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

Vitest, pool veya locations seçeneklerine bağlı olarak aynı dosya için farklı spesifikasyonlar oluşturabilir, bu nedenle referansa güvenilmemelidir. Vitest ayrıca vitest.getModuleSpecifications adresinden önbelleğe alınmış spesifikasyonları da döndürebilir - önbellek moduleId ve pool'a dayanır. project.createSpecification her zaman yeni bir örnek döndürdüğünü belirtmek gerekir.

matchesProjectFilter 3.1.0+

function matchesProjectFilter(name: string): boolean;

Adın mevcut proje filtresiyle eşleşip eşleşmediğini kontrol eder. Proje filtresi yoksa, bu her zaman true döndürecektir.

--project CLI seçeneğini programlı olarak değiştirmek mümkün değildir.