Test Projesi 3.0.0+

WARNING

Bu kılavuz, Vitest'in gelişmiş Node.js API'sini açıklamaktadır. Yalnızca projeleri tanımlamak istiyorsanız, lütfen "Test Projeleri" kılavuzunu takip edin.

name

Ad, kullanıcı tarafından atanan veya Vitest tarafından belirlenen benzersiz bir dizedir. Kullanıcı bir ad sağlamazsa, Vitest projenin kök dizinindeki bir package.json dosyasını yüklemeye çalışır ve name özelliğini oradan alır. Bir package.json dosyası yoksa, Vitest varsayılan olarak klasör adını kullanır. Satır içi projeler, ad olarak sayıları (dizeye dönüştürülmüş haliyle) kullanır.

node.js

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
vitest.projects.map(p => p.name) === ['@pkg/server', 'utils', '2', 'custom'];

vitest.config.js

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      './packages/server', // "@pkg/server" içeren package.json dosyası var
      './utils', // package.json dosyası yok
      {
        // adı özelleştirmiyor
        test: {
          pool: 'threads',
        },
      },
      {
        // adı özelleştirildi
        test: {
          name: 'custom',
        },
      },
    ],
  },
});

INFO

Kök proje kullanıcı projelerinin bir parçası değilse, name çözümlenmeyecektir.

vitest

vitest, genel Vitest sürecini referans gösterir.

serializedConfig

Bu, test süreçlerinin aldığı yapılandırmadır. Vitest, serileştirilmesi mümkün olmayan tüm fonksiyonları ve özellikleri kaldırarak yapılandırmayı manuel olarak serileştirir. Bu değer hem testlerde hem de Node.js ortamında mevcut olduğundan, türü ana giriş noktasından dışa aktarılır.

import type { SerializedConfig } from 'vitest';

const config: SerializedConfig = vitest.projects[0].serializedConfig;

WARNING

serializedConfig özelliği bir getter'dır. Her erişildiğinde Vitest, yapılandırma değişmiş olma ihtimaline karşı tekrar serileştirir. Bu aynı zamanda her zaman farklı bir referans döndüreceği anlamına gelir:

project.serializedConfig === project.serializedConfig; // ❌

globalConfig

Vitest'in başlatıldığı test yapılandırması. Bu kök proje ise, globalConfig ve config aynı nesneyi referans alacaktır. Bu yapılandırma, proje düzeyinde ayarlanamayan değerler, örneğin coverage veya reporters için kullanışlıdır.

import type { ResolvedConfig } from 'vitest/node';

vitest.config === vitest.projects[0].globalConfig;

config

Bu, projenin çözümlenmiş test yapılandırmasıdır.

hash 3.2.0+

Bu projenin benzersiz karma değeri. Bu değer, yeniden çalıştırmalar arasında tutarlılık gösterir.

Projenin köküne ve adına dayanır. Kök yolunun farklı işletim sistemleri arasında tutarlı olmadığını, bu nedenle karma değerinin de farklı olacağını unutmayın.

vite

Bu, projenin ViteDevServer'ıdır. Tüm projelerin kendi Vite sunucuları vardır.

browser

Bu değer yalnızca testler tarayıcıda çalıştırılıyorsa ayarlanacaktır. browser etkinleştirilmişse, ancak testler henüz çalışmadıysa, bu undefined olacaktır. Projenin tarayıcı testlerini destekleyip desteklemediğini kontrol etmeniz gerekiyorsa, project.isBrowserEnabled() yöntemini kullanın.

WARNING

Tarayıcı API'si daha da deneyseldir ve SemVer (Semantik Sürümleme) kurallarına uymaz. Tarayıcı API'si, diğer API'lerden ayrı olarak standartlaştırılacaktır.

provide

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

config.provide alanına ek olarak testlere özel değerler sağlamanın bir yolu. Tüm değerler depolanmadan önce structuredClone ile doğrulanır, ancak providedContext üzerindeki değerlerin kendileri kopyalanmaz.

node.js

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
const project = vitest.projects.find(p => p.name === 'custom');
project.provide('key', 'value');
await vitest.start();

test.spec.js

import { inject } from 'vitest';
const value = inject('key');

Değerler dinamik olarak sağlanabilir. Testlerde sağlanan değer, bir sonraki çalıştırmalarında güncellenecektir.

TIP

Bu yöntem, genel kurulum dosyalarında (global setup files) genel API'nin kullanılamadığı durumlar için de kullanılabilir:

export default function setup({ provide }) {
  provide('wsPort', 3000);
}

getProvidedContext

function getProvidedContext(): ProvidedContext;

Bu fonksiyon, bağlam nesnesini döndürür. Her proje ayrıca vitest.provide tarafından ayarlanan genel bağlamı da devralır.

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
vitest.provide('global', true);
const project = vitest.projects.find(p => p.name === 'custom');
project.provide('key', 'value');

// { global: true, key: 'value' }
const context = project.getProvidedContext();

TIP

Proje bağlam değerleri her zaman kök projenin bağlamını geçersiz kılar.

createSpecification

function createSpecification(
  moduleId: string,
  locations?: number[]
): TestSpecification;

vitest.runTestSpecifications içinde kullanılabilecek bir test spesifikasyonu oluşturur. Spesifikasyon, test dosyasını belirli bir project ve isteğe bağlı olarak test locations ile sınırlar. Test konumları, testin kaynak kodunda tanımlandığı kod satırlarıdır. Konumlar sağlanırsa, Vitest yalnızca bu satırlarda tanımlanan testleri çalıştırır. testNamePattern tanımlanmışsa, o da uygulanır.

import { createVitest } from 'vitest/node';
import { resolve } from 'node:path/posix';

const vitest = await createVitest('test');
const project = vitest.projects[0];
const specification = project.createSpecification(
  resolve('./example.test.ts'),
  [20, 40] // isteğe bağlı test satırları
);
await vitest.runTestSpecifications([specification]);

WARNING

createSpecification çözümlenmiş bir modül kimliği bekler. Dosyayı otomatik olarak çözümlemez veya dosya sisteminde varlığını kontrol etmez.

Ayrıca project.createSpecification'ın her zaman yeni bir örnek döndürdüğünü unutmayın.

isRootProject

function isRootProject(): boolean;

Mevcut projenin kök proje olup olmadığını kontrol eder. Kök projeye vitest.getRootProject() çağrısı yaparak da erişebilirsiniz.

globTestFiles

function globTestFiles(filters?: string[]): {
  /**
   * Filtrelerle eşleşen test dosyaları.
   */
  testFiles: string[];
  /**
   * Filtrelerle eşleşen tür kontrolü test dosyaları. `typecheck.enabled` `true` olmadığı sürece bu boş olacaktır.
   */
  typecheckTestFiles: string[];
};

Tüm test dosyalarını glob desenine göre bulur. Bu fonksiyon, normal test dosyalarını ve tür kontrolü test dosyalarını içeren bir nesne döndürür.

Bu yöntem filters (filtreler) kabul eder. Filtreler, Vitest örneğindeki diğer yöntemlerden farklı olarak yalnızca dosya yolunun bir kısmını içerebilir:

project.globTestFiles(['foo']); // ✅
project.globTestFiles(['basic/foo.js:10']); // ❌

TIP

Vitest, test dosyalarını bulmak için fast-glob kullanır. test.dir, test.root, root veya process.cwd() cwd seçeneğini tanımlar.

Bu yöntem birkaç yapılandırma seçeneğine bakar:

• Normal test dosyalarını bulmak için test.include, test.exclude
• Kaynak içi testleri bulmak için test.includeSource, test.exclude
• Tür kontrolü testlerini bulmak için test.typecheck.include, test.typecheck.exclude

matchesTestGlob

function matchesTestGlob(moduleId: string, source?: () => string): boolean;

Bu yöntem, dosyanın normal bir test dosyası olup olmadığını kontrol eder. Doğrulama için globTestFiles'ın kullandığı aynı yapılandırma özelliklerini kullanır.

Bu yöntem ayrıca, kaynak kodu içeren ikinci bir parametre de kabul eder. Bu, dosyanın kaynak içi bir test olup olmadığını doğrulamak amacıyla kullanılır. Bu yöntemi birden fazla proje için birden fazla kez çağırıyorsanız, dosyayı bir kez okuyup doğrudan iletmeniz önerilir. Dosya bir test dosyası değilse, ancak includeSource glob deseniyle eşleşiyorsa, source sağlanmadığı sürece Vitest dosyayı eşzamanlı olarak okur.

import { createVitest } from 'vitest/node';
import { resolve } from 'node:path/posix';

const vitest = await createVitest('test');
const project = vitest.projects[0];

project.matchesTestGlob(resolve('./basic.test.ts')); // true
project.matchesTestGlob(resolve('./basic.ts')); // false
project.matchesTestGlob(
  resolve('./basic.ts'),
  () => `
if (import.meta.vitest) {
  // ...
}
`
); // `includeSource` ayarlanmışsa true

import

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

Vite modül çalıştırıcısı aracılığıyla bir dosya içe aktarın. Dosya, sağlanan projenin yapılandırmasıyla Vite tarafından dönüştürülür ve ayrı bir bağlamda yürütülür. moduleId'nin config.root'a göre göreceli olacağını unutmayın.

DANGER

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

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

dynamicExample !== staticExample; // ✅

INFO

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

onTestsRerun

function onTestsRerun(cb: OnTestsRerunHandler): void;

Bu, project.vitest.onTestsRerun için bir kısayoldur. Testlerin yeniden çalıştırılması planlandığında (genellikle bir dosya değişikliği nedeniyle) çağrılacak bir geri arama fonksiyonu kabul eder.

project.onTestsRerun(specs => {
  console.log(specs);
});

isBrowserEnabled

function isBrowserEnabled(): boolean;

Bu proje testleri tarayıcıda çalıştırıyorsa true döndürür.

close

function close(): Promise<void>;

Projeyi ve ilişkili tüm kaynaklarını kapatır. Bu yalnızca bir kez çağrılabilir; kapatma işlemi sunucu yeniden başlayana kadar önbelleğe alınır. Kaynaklara tekrar ihtiyaç duyulursa, yeni bir proje oluşturulmalıdır.

Ayrıntılı olarak, bu yöntem Vite sunucusunu kapatır, tür denetleyici hizmetini durdurur, tarayıcı çalışıyorsa onu kapatır, kaynak kodunu barındıran geçici dizini siler ve sağlanan bağlamı sıfırlar.