Çalıştırıcı API'si

WARNING

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

Yapılandırma dosyanızdaki runner seçeneğiyle özel test çalıştırıcınızın yolunu belirtebilirsiniz. Bu dosya, aşağıdaki yöntemleri uygulayan bir sınıf kurucusunu varsayılan olarak dışa aktarmalıdır:

export interface VitestRunner {
  /**
   * Testler toplanmadan ve çalıştırılmadan önce çağrılan ilk yöntemdir.
   */
  onBeforeCollect?: (paths: string[]) => unknown;
  /**
   * Testler toplandıktan ve "onBeforeRun" çağrılmadan ö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 yöntemi dinlemeli ve çağrıldığında, "onBeforeRunSuite" ve "onBeforeRunTask" içinde testleri ve süitleri atlanmış olarak işaretlemelidir.
   */
  onCancel?: (reason: CancelReason) => unknown;

  /**
   * Tek bir testi çalıştırmadan önce çağrılır. Henüz bir "result" değeri yoktur.
   */
  onBeforeRunTask?: (test: TaskPopulated) => unknown;
  /**
   * Test fonksiyonunu çalıştırmadan önce çağrılır. Zaten "state" ve "startTime" değerlerini içeren bir "result"a sahiptir.
   */
  onBeforeTryTask?: (
    test: TaskPopulated,
    options: { retry: number; repeats: number }
  ) => unknown;
  /**
   * Sonuç ve durum ayarlandıktan sonra çağrılır.
   */
  onAfterRunTask?: (test: TaskPopulated) => unknown;
  /**
   * Test fonksiyonu çalıştırıldıktan hemen sonra çağrılır. Henüz yeni bir duruma sahip değildir. Test fonksiyonu bir hata fırlatırsa ç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 bir "result" değeri yoktur.
   */
  onBeforeRunSuite?: (suite: Suite) => unknown;
  /**
   * Tek bir süiti çalıştırdıktan sonra çağrılır. Durum ve sonuç değerlerine sahiptir.
   */
  onAfterRunSuite?: (suite: Suite) => unknown;

  /**
   * Tanımlanmışsa, Vitest'in olağan süit bölümleme ve işleme mekanizması yerine çağrılır.
   * "before" ve "after" kancaları göz ardı edilmeyecektir.
   */
  runSuite?: (suite: Suite) => Promise<void>;
  /**
   * Tanımlanmışsa, Vitest'in olağan işleme mekanizması yerine çağrılır. Kendi özel test fonksiyonunuz varsa kullanışlı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. Bir raporlayıcıdaki "onTaskUpdate" ile aynı işlevi görür, ancak bu, testlerle aynı iş parçacığında çalışır.
   */
  onTaskUpdate?: (
    task: [string, TaskResult | undefined, TaskMeta | 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 bir bağlam tanımlandığında bu yöntem çağrılır. Bağlama özel özellikler eklemek istediğinizde kullanışlıdır.
   * Yalnızca bir çalıştırıcı ile özel bir bağlam tanımlamak istiyorsanız, bunun yerine "setupFiles" içinde "beforeAll" kullanmayı düşünebilirsiniz.
   */
  extendTaskContext?: (context: TestContext) => TestContext;
  /**
   * Belirli dosyalar içe aktarıldığında çağrılır. İki durumda çağrılabilir: testleri toplamak için ve kurulum dosyalarını içe aktarmak için.
   */
  importFile: (filepath: string, source: VitestRunnerImportSource) => unknown;
  /**
   * `test.extend` `{ injected: true }` ile kullanıldığında, çalıştırıcının değeri almaya çalıştığı zaman çağrılan fonksiyondur.
   */
  injectValue?: (key: string) => unknown;
  /**
   * Herkese açık yapılandırma ayarları.
   */
  config: VitestRunnerConfig;
  /**
   * Mevcut havuzun adı. Sunucu tarafında yığın izlemenin nasıl çıkarıldığını etkileyebilir.
   */
  pool?: string;
}

Bu sınıfı başlatırken, Vitest yapılandırmasını iletir; bunu bir config özelliği olarak göstermelisiniz:

import type { RunnerTestFile } from 'vitest';
import type { VitestRunner, VitestRunnerConfig } from 'vitest/suite';
import { VitestTestRunner } from 'vitest/runners';

class CustomRunner extends VitestTestRunner implements VitestRunner {
  public config: VitestRunnerConfig;

  constructor(config: VitestRunnerConfig) {
    this.config = config;
  }

  onAfterRunFiles(files: RunnerTestFile[]) {
    console.log('finished running', files);
  }
}

export default CustomRunner;

WARNING

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

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

export default class Runner {
  async importFile(filepath: string) {
    await this.__vitest_executor.executeId(filepath);
  }
}

WARNING

Özel bir çalıştırıcınız yoksa veya runTask yöntemini tanımlamadıysanız, Vitest görevi otomatik olarak çalıştırmaya çalışacaktır. setFn ile bir fonksiyon eklemediyseniz, işlem başarısız olacaktır.

TIP

Anlık görüntü desteği ve diğer bazı özellikler çalıştırıcıya bağlıdır. Bu özellikleri kaybetmek istemiyorsanız, çalıştırıcınızı vitest/runners'dan içe aktarılan VitestTestRunner'dan genişletebilirsiniz. Ayrıca, kıyaslama işlevselliğini genişletmek istiyorsanız BenchmarkNodeRunner'ı da sunar.

Görevler

WARNING

"Çalıştırıcı Görevleri API'si" deneyseldir ve öncelikli olarak yalnızca test çalışma zamanında kullanılmalıdır. Vitest ayrıca, ana iş parçacığında (örneğin, raporlayıcı içinde) çalışırken tercih edilmesi gereken "Raporlanan Görevler API'si"'ni de sunar.

Ekip şu anda "Çalıştırıcı Görevleri"nin gelecekte "Raporlanan Görevler" ile değiştirilip değiştirilmeyeceğini tartışmaktadır.

Süitler ve testler dahili olarak tasks olarak adlandırılır. Vitest çalıştırıcısı, herhangi bir testi toplamadan önce bir File görevi başlatır; bu, birkaç ek özelliğe sahip bir Suite üst kümesidir. Her görevde ( File dahil) bir file özelliği olarak mevcuttur.

interface File extends Suite {
  /**
   * Dosyanın ait olduğu havuzun adı.
   * @default 'forks'
   */
  pool?: string;
  /**
   * Dosyanın UNIX formatındaki yolu.
   */
  filepath: string;
  /**
   * Dosyanın ait olduğu test projesinin adı.
   */
  projectName: string | undefined;
  /**
   * Dosyadaki tüm testleri toplamak için geçen süre.
   * Bu süre, tüm dosya bağımlılıklarının içe aktarılmasını da içerir.
   */
  collectDuration?: number;
  /**
   * Kurulum dosyasının içe aktarılması için geçen süre.
   */
  setupDuration?: number;
}

Her süitin, toplama aşamasında doldurulan bir tasks özelliği bulunur. Görev ağacını yukarıdan aşağıya doğru dolaşmak 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 parçası olan görevlerin bir dizisidir.
   */
  tasks: Task[];
}

Her görevin, içinde bulunduğu süiti referans alan bir suite özelliği bulunur. test veya describe en üst düzeyde başlatılırsa, bir suite özelliğine sahip olmayacaklardır ( file'a eşit olmayacaktır!). File da asla bir suite özelliğine sahip değildir. 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 iletilecek test bağlamıdır.
   */
  context: TestContext & ExtraContext;
  /**
   * Dosya görevi. Dosyanın kök görevidir.
   */
  file: File;
  /**
   * Görevin `context.skip()` çağrısı ile atlanıp atlanmadığı.
   */
  pending?: boolean;
  /**
   * Görevin başarısız olması durumunda başarılı sayılıp sayılmayacağı. Görev başarısız olursa, başarılı olarak işaretlenecektir.
   */
  fails?: boolean;
  /**
   * Testi bitirmeden önce beklemek için vaatleri (eşzamansız beklentilerden gelenleri) saklayın.
   */
  promises?: Promise<any>[];
}

Her görevin bir result alanı olabilir. Süitler, bu alana yalnızca bir süit geri çağırmasında veya beforeAll/afterAll geri çağırmalarında fırlatılan bir hata, testleri toplamalarını engellediği takdirde sahip olabilirler. Testler, geri çağırmaları çağrıldıktan sonra her zaman bu alana sahiptir; state ve errors alanları ise sonuca bağlı olarak mevcuttur. beforeEach veya afterEach geri çağırmalarında bir hata fırlatılırsa, fırlatılan hata task.result.errors içinde mevcut olacaktır.

export interface TaskResult {
  /**
   * Görevin durumu. Toplama sırasında `task.mode` değerini miras alır.
   * Görev tamamlandığında, durumu `pass` veya `fail` olarak değişecektir.
   * - **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 meydana gelen hatalar. `expect.soft()` birden çok kez başarısız olursa,
   * birden fazla hata oluşması mümkündür.
   */
  errors?: ErrorWithDiff[];
  /**
   * Görevin çalışması için geçen süre (milisaniye cinsinden).
   */
  duration?: number;
  /**
   * Görevin başlangıç zamanı (milisaniye cinsinden).
   */
  startTime?: number;
  /**
   * Görev tamamlandıktan sonraki 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 kaç kez yeniden denendiği. Görev yalnızca başarısız olması ve
   * `retry` seçeneğinin ayarlanmış olması durumunda yeniden denenir.
   */
  retryCount?: number;
  /**
   * Görevin kaç kez tekrarlandığı. Görev yalnızca `repeats` seçeneği
   * ayarlanmışsa tekrarlanır. Bu sayı `retryCount` değerini de içerir.
   */
  repeatCount?: number;
}

Görev Fonksiyonunuz

Vitest, kendi test metodunuzu oluşturmak için createTaskCollector yardımcı programını sunar. Bir testle aynı şekilde davranır, ancak toplama sırasında özel bir yöntem çağırır.

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

import { createTaskCollector, getCurrentSuite } from 'vitest/suite';

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

// Bu fonksiyon toplama aşamasında çağrılacaktır:
// Burada fonksiyon işleyicisini çağırmayın, onu süit görevlerine ekleyin
// "getCurrentSuite().task()" yöntemi aracılığıyla.
// Not: createTaskCollector, "todo"/"each"/... için destek sağlar.
export const myCustomTask = createTaskCollector(function (name, fn, timeout) {
  getCurrentSuite().task(name, {
    ...this, // böylece "todo"/"skip"/... gibi özellikler doğru şekilde izlenir
    meta: {
      customPropertyToDifferentiateTask: true,
    },
    handler: fn,
    timeout,
  });
});

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

describe('bahçenin bakımı', () => {
  beforeAll(() => {
    gardener.putWorkingClothes();
  });

  myCustomTask('çimleri temizle', () => {
    gardener.weedTheGrass();
  });
  myCustomTask.todo('çimleri biçmek', () => {
    gardener.mowerTheLawn();
  });
  myCustomTask('çiçekleri sula', () => {
    gardener.waterFlowers();
  });

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

vitest ./garden/tasks.test.js