Test Çalıştırıcı

WARNING

Bu gelişmiş bir API'dir. Eğer sadece testleri çalıştırmak istiyorsanız, muhtemelen buna ihtiyacınız yok. Öncelikle kütüphane yazarları tarafından kullanılır.

Yapılandırma dosyanızdaki runner seçeneği ile test çalıştırıcınızın yolunu belirleyebilirsiniz. Bu dosya, aşağıdaki yöntemleri uygulayan bir sınıf kurucusuna sahip varsayılan bir dışa aktarıma sahip olmalıdır:

export interface VitestRunner {
  /**
   * Testleri toplamadan ve çalıştırmadan önce çağrılan ilk şey.
   */
  onBeforeCollect?: (paths: string[]) => unknown;
  /**
   * Testler toplandıktan ve "onBeforeRun"dan önce çağrılır.
   */
  onCollected?: (files: File[]) => unknown;

  /**
   * Test çalıştırıcısının sonraki test çalıştırmalarını iptal etmesi gerektiğinde çağrılır.
   * Çalıştırıcı bu metodu dinlemeli ve çağrıldığında testleri ve süitleri "onBeforeRunSuite" ve "onBeforeRunTask" içinde atlanmış olarak işaretlemelidir.
   */
  onCancel?: (reason: CancelReason) => unknown;

  /**
   * Tek bir testi çalıştırmadan önce çağrılır. Henüz "result" yoktur.
   */
  onBeforeRunTest?: (test: TaskPopulated) => unknown;
  /**
   * Test fonksiyonunu çalıştırmadan önce çağrılır. Zaten "state" ve "startTime" bilgileriyle birlikte "result" mevcuttur.
   */
  onBeforeTryTask?: (
    test: TaskPopulated,
    options: { retry: number; repeats: number }
  ) => unknown;
  /**
   * Sonuç ve durum ayarlandıktan sonra çağrılır.
   */
  onAfterRunTask?: (test: TaskPopulated) => unknown;
  /**
   * Test fonksiyonunu çalıştırdıktan hemen sonra çağrılır. Henüz yeni bir durum yoktur. Test fonksiyonu hata verirse çağrılmaz.
   */
  onAfterTryTask?: (
    test: TaskPopulated,
    options: { retry: number; repeats: number }
  ) => unknown;

  /**
   * Tek bir süiti çalıştırmadan önce çağrılır. Henüz "result" yoktur.
   */
  onBeforeRunSuite?: (suite: Suite) => unknown;
  /**
   * Tek bir süiti çalıştırdıktan sonra çağrılır. Durum ve sonuç mevcuttur.
   */
  onAfterRunSuite?: (suite: Suite) => unknown;

  /**
   * Tanımlanmışsa, olağan Vitest süit bölümlemesi ve işlenmesi yerine çağrılır.
   * "before" ve "after" kancaları göz ardı edilmeyecektir.
   */
  runSuite?: (suite: Suite) => Promise<void>;
  /**
   * Tanımlanmışsa, olağan Vitest işlenmesi yerine çağrılır. Kendi özel test fonksiyonunuz varsa yararlıdır.
   * "before" ve "after" kancaları göz ardı edilmeyecektir.
   */
  runTask?: (test: TaskPopulated) => Promise<void>;

  /**
   * Bir görev güncellendiğinde çağrılır. Raporlayıcıdaki "onTaskUpdate" ile aynıdır, ancak bu testlerle aynı iş parçacığında çalışır.
   */
  onTaskUpdate?: (task: [string, TaskResult | undefined][]) => Promise<void>;

  /**
   * Toplanan yollardaki tüm testleri çalıştırmadan önce çağrılır.
   */
  onBeforeRunFiles?: (files: File[]) => unknown;
  /**
   * Toplanan yollardaki tüm testleri çalıştırdıktan hemen sonra çağrılır.
   */
  onAfterRunFiles?: (files: File[]) => unknown;
  /**
   * Bir test için yeni context tanımlandığında çağrılır. Bağlama özel özellikler eklemek istiyorsanız kullanışlıdır.
   * Yalnızca bir çalıştırıcı ile özel bağlam tanımlamak istiyorsanız, bunun yerine "setupFiles" içinde "beforeAll" kullanmayı düşünün.
   *
   * Bu yöntem hem "test" hem de "custom" işleyicileri için çağrılır.
   *
   * @see https://www.getbook.com/en/book/vitest-2/advanced/runner#your-task-function
   */
  extendTaskContext?: <T extends Test | Custom>(
    context: TaskContext<T>
  ) => TaskContext<T>;
  /**
   * Belirli dosyalar içe aktarıldığında çağrılır. İki durumda çağrılabilir: testler toplanırken ve kurulum dosyaları içe aktarılırken.
   */
  importFile: (filepath: string, source: VitestRunnerImportSource) => unknown;
  /**
   * Genel erişilebilir yapılandırma.
   */
  config: VitestRunnerConfig;
}

Bu sınıfı başlatırken Vitest, Vitest yapılandırmasını iletir. Bunu bir config özelliği olarak açığa çıkarmalısınız.

WARNING

Vitest ayrıca ViteNodeRunner örneğini __vitest_executor özelliği olarak enjekte eder. importFile yönteminde dosyaları işlemek için kullanabilirsiniz (bu, TestRunner ve BenchmarkRunner'ın varsayılan davranışıdır).

ViteNodeRunner, Vite dostu bir ortamda test dosyalarını içe aktarmak için kullanılan executeId yöntemini kullanıma sunar. Yani, çalışma zamanında içe aktarmaları çözecek ve dosya içeriğini Node'un anlayabileceği şekilde dönüştürecektir.

TIP

Snapshot desteği ve diğer bazı özellikler runner'a bağlıdır. Bunları kaybetmek istemiyorsanız, çalıştırıcınızı vitest/runners'tan içe aktarılan VitestTestRunner'dan genişletebilirsiniz. Ayrıca, kıyaslama işlevselliğini genişletmek istiyorsanız BenchmarkNodeRunner'ı da kullanıma sunar.

Görevler

Suite'ler ve testler dahili olarak tasks olarak adlandırılır. Vitest çalıştırıcısı, herhangi bir test toplamadan önce bir File görevi başlatır - bu, Suitein bir üst kümesidir ve ek özellikler içerir. Her görevde ( File dahil) bir file özelliği olarak mevcuttur.

interface File extends Suite {
  /**
   * Dosyanın bağlı olduğu havuzun adı.
   * @default 'forks'
   */
  pool?: string;
  /**
   * Dosyanın UNIX formatında yolu.
   */
  filepath: string;
  /**
   * Dosyanın ait olduğu çalışma alanı projesinin adı.
   */
  projectName: string | undefined;
  /**
   * Dosyadaki tüm testlerin toplanması için geçen süre.
   * Bu süre, tüm dosya bağımlılıklarının import edilmesini de kapsar.
   */
  collectDuration?: number;
  /**
   * Kurulum dosyasını içe aktarmak için geçen süre.
   */
  setupDuration?: number;
  /**
   * Dosyanın test çalıştırılmadan başlatılıp başlatılmadığı.
   * Bu, Vitest tarafından sunucu tarafında durumu doldurmak için yapılır.
   */
  local?: boolean;
}

Her süitin, toplama aşamasında doldurulan bir tasks özelliği vardır. Görev ağacını yukarıdan aşağı gezmek için kullanışlıdır.

interface Suite extends TaskBase {
  type: 'suite';
  /**
   * Dosya görevi. Dosyanın kök görevidir.
   */
  file: File;
  /**
   * Süitin bir parçası olan görevlerin bir dizisi.
   */
  tasks: Task[];
}

Her görevin, bulunduğu süite başvuran bir suite özelliği vardır. Eğer 'test' veya 'describe' üst seviyede başlatılırsa, bir suite özelliği olmayacaktır ( file ile aynı olmayacaktır!). File'ın da asla bir suite özelliği yoktur. Görevleri aşağıdan yukarıya doğru dolaşmak için kullanışlıdır.

interface Test<ExtraContext = object> extends TaskBase {
  type: 'test';
  /**
   * Test fonksiyonuna geçirilecek test context'i.
   */
  context: TaskContext<Test> & ExtraContext & TestContext;
  /**
   * Dosya görevi. Dosyanın kök görevidir.
   */
  file: File;
  /**
   * Görevin 't.skip()' ile atlanıp atlanmadığı.
   */
  pending?: boolean;
  /**
   * Görevin başarısız olursa başarılı olup olmayacağı. Görev başarısız olursa, başarılı olarak işaretlenecektir.
   */
  fails?: boolean;
  /**
   * Görev başarısız olursa çalışacak kancalar. Sıra `sequence.hooks` seçeneğine bağlıdır.
   */
  onFailed?: OnTestFailedHandler[];
  /**
   * Görev bittikten sonra çalışacak kancalar. Sıra `sequence.hooks` seçeneğine bağlıdır.
   */
  onFinished?: OnTestFinishedHandler[];
  /**
   * Test tamamlanmadan önce beklemek için (async expect'lerden gelen) promise'leri saklayın
   */
  promises?: Promise<any>[];
}

Her görevin bir result alanı olabilir. Süitler, bu alana yalnızca bir süit geri çağırması veya beforeAll/afterAll geri çağırmaları içinde bir hata atılırsa ve bu durum testlerin toplanmasını engellerse sahip olabilir. Testler, geri çağırmaları çağrıldıktan sonra her zaman bu alana sahiptir - state ve errors alanları sonuca bağlı olarak mevcuttur. Eğer beforeEach veya afterEach geri çağırmalarında bir hata atılırsa, atılan hata task.result.errors içinde mevcut olacaktır.

export interface TaskResult {
  /**
   * Görevin durumu. Toplama sırasında `task.mode`'u devralır.
   * Görev bittiğinde, `pass` veya `fail` olarak değiştirilecektir.
   * - **pass**: görev başarıyla çalıştı
   * - **fail**: görev başarısız oldu
   */
  state: TaskState;
  /**
   * Görev yürütme sırasında oluşan hatalar. Birden fazla hata olması mümkündür
   * eğer `expect.soft()` birden çok kez başarısız olduysa.
   */
  errors?: ErrorWithDiff[];
  /**
   * Görevin çalışması için geçen süre milisaniye cinsinden.
   */
  duration?: number;
  /**
   * Görevin çalışmaya başladığı milisaniye cinsinden zaman.
   */
  startTime?: number;
  /**
   * Görev bittikten sonra yığın boyutu bayt cinsinden.
   * Yalnızca `logHeapUsage` seçeneği ayarlanmışsa ve `process.memoryUsage` tanımlanmışsa kullanılabilir.
   */
  heap?: number;
  /**
   * Bu görevle ilgili kancaların durumu. Raporlama sırasında kullanışlıdır.
   */
  hooks?: Partial<
    Record<'afterAll' | 'beforeAll' | 'beforeEach' | 'afterEach', TaskState>
  >;
  /**
   * Görevin yeniden denenme sayısı. Görev yalnızca
   * başarısız olursa ve `retry` seçeneği ayarlanmışsa yeniden denenir.
   */
  retryCount?: number;
  /**
   * Görevin tekrarlanma sayısı. Görev yalnızca
   * `repeats` seçeneği ayarlanmışsa tekrarlanır. Bu sayı 'retryCount'u da kapsar.
   */
  repeatCount?: number;
}

Görev Fonksiyonunuz

Vitest, yerleşik raporları yeniden kullanmayı sağlayan bir Custom görev türü sunar. Neredeyse Test ile aynıdır, ancak türü 'custom''dır.

Bir görev, bir süitin parçası olan bir nesnedir. suite.task yöntemiyle otomatik olarak mevcut süite eklenir:

// ./utils/custom.js
import { createTaskCollector, getCurrentSuite, setFn } from 'vitest/suite';

export { afterAll, beforeAll, describe } from 'vitest';

// bu fonksiyon toplama aşamasında çağrılacaktır:
// burada fonksiyon handler'ını çağırmayın, süit görevlerine ekleyin
// "getCurrentSuite().task()" yöntemiyle
// not: createTaskCollector "todo"/"each"/... desteği sağlar
export const myCustomTask = createTaskCollector(function (name, fn, timeout) {
  getCurrentSuite().task(name, {
    ...this, // böylece "todo"/"skip"/... doğru takip edilir
    meta: {
      customPropertyToDifferentiateTask: true,
    },
    handler: fn,
    timeout,
  });
});

// ./garden/tasks.test.js
import { afterAll, beforeAll, describe, myCustomTask } from '../custom.js';
import { gardener } from './gardener.js';

describe('take care of the garden', () => {
  beforeAll(() => {
    gardener.putWorkingClothes();
  });

  myCustomTask('weed the grass', () => {
    gardener.weedTheGrass();
  });
  myCustomTask.todo('mow the lawn', () => {
    gardener.mowerTheLawn();
  });
  myCustomTask('water flowers', () => {
    gardener.waterFlowers();
  });

  afterAll(() => {
    gardener.goHome();
  });
});

vitest ./garden/tasks.test.js

WARNING

Custom bir runner'ınız yoksa veya runTest yöntemini tanımlamadıysanız, Vitest bir görevi otomatik olarak almaya çalışacaktır. Eğer setFn ile bir fonksiyon eklemediyseniz, hata verecektir.