Kapsam

Vitest, v8 aracılığıyla yerel kod kapsamını ve istanbul aracılığıyla enstrümantasyonlu kod kapsamını destekler.

Kapsam Sağlayıcıları

v8 ve istanbul desteği isteğe bağlıdır. Varsayılan olarak v8 kullanılır.

Kapsam aracını test.coverage.provider ayarını v8 veya istanbul olarak belirleyerek seçebilirsiniz:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    coverage: {
      provider: 'istanbul', // veya 'v8'
    },
  },
});

Vitest sürecini başlattığınızda, ilgili destek paketini otomatik olarak yüklemeniz istenir.

Ya da bunları manuel olarak yüklemeyi tercih ederseniz:

v8

npm i -D @vitest/coverage-v8

istanbul

npm i -D @vitest/coverage-istanbul

V8 Sağlayıcısı

INFO

Aşağıdaki V8 kapsamı açıklaması Vitest'e özgüdür ve diğer test çalıştırıcıları için geçerli değildir. v3.2.0 sürümünden bu yana Vitest, V8 kapsamı için AST tabanlı kapsam yeniden eşlemesi kullanır ve bu da Istanbul ile aynı kapsam raporlarını üretir.

Bu, kullanıcıların V8 kapsamının hızından Istanbul kapsamının doğruluğuyla faydalanmasını sağlar.

Vitest varsayılan olarak 'v8' kapsam sağlayıcısını kullanır. Bu sağlayıcı, NodeJS, Deno veya Google Chrome gibi Chromium tabanlı tarayıcılar gibi V8 motoru üzerinde çalışan bir Javascript çalışma zamanı gerektirir.

Kapsam toplama, çalışma zamanında node:inspector ve tarayıcılarda Chrome DevTools Protokolü kullanılarak V8'e talimat verilmesiyle gerçekleştirilir. Kullanıcının kaynak dosyaları, herhangi bir ön enstrümantasyon adımı olmaksızın olduğu gibi yürütülebilir.

• ✅ Kullanılması önerilen seçenek
• ✅ Ön dönüştürme adımı yok. Test dosyaları olduğu gibi yürütülebilir.
• ✅ Istanbul'dan daha hızlı yürütme.
• ✅ Istanbul'dan daha düşük bellek tüketimi.
• ✅ Kapsam raporu doğruluğu Istanbul ile aynı derecede iyidir (Vitest v3.2.0 sürümünden beri).
• ⚠️ Bazı durumlarda Istanbul'dan daha yavaş olabilir, örneğin çok sayıda farklı modül yüklenmesi durumunda. V8, kapsam toplamasını belirli modüllerle sınırlama desteği sunmaz.
• ⚠️ V8 motoru tarafından belirlenen bazı küçük sınırlamalar vardır. Bkz. ast-v8-to-istanbl | Sınırlamalar.
• ❌ Firefox veya Bun gibi V8 kullanmayan ortamlarda ya da Cloudflare Workers gibi V8 kapsamını profiler aracılığıyla açığa çıkarmayan ortamlarda çalışmaz.

Istanbul Sağlayıcısı

Istanbul kod kapsamı araçları 2012'den beri mevcuttur ve yoğun şekilde test edilmiştir. Bu sağlayıcı, kapsam takibi kullanıcının kaynak dosyalarını enstrümanlayarak yapıldığı için herhangi bir Javascript çalışma zamanında kullanılabilir.

Uygulamada, kaynak dosyalarını enstrümanlamak, kullanıcının dosyalarına ek Javascript eklemek anlamına gelir:

// Dal ve fonksiyon kapsam sayaçlarının basitleştirilmiş bir örneği
const coverage = { 
  branches: { 1: [0, 0] }, 
  functions: { 1: 0 }, 
} 

export function getUsername(id) {
  // Bu çağrıldığında fonksiyon kapsamı artırılır.
  coverage.functions['1']++; 

  if (id == null) {
    // Bu çağrıldığında dal kapsamı artırılır.
    coverage.branches['1'][0]++; 

    throw new Error('User ID is required');
  }
  // If-deyimi koşulu karşılanmadığında örtük else kapsamı artırılır.
  coverage.branches['1'][1]++; 

  return database.getUser(id);
}

globalThis.__VITEST_COVERAGE__ ||= {}; 
globalThis.__VITEST_COVERAGE__[filename] = coverage; 

• ✅ Herhangi bir Javascript çalışma zamanında çalışır
• ✅ 13 yılı aşkın süredir yaygın olarak kullanılır ve test edilmiştir.
• ✅ Bazı durumlarda V8'den daha hızlıdır. Kapsam enstrümantasyonu belirli dosyalarla sınırlanabilir; V8'de ise tüm modüller enstrümanlanır.
• ❌ Ön enstrümantasyon adımı gereklidir.
• ❌ Enstrümantasyon yükü nedeniyle yürütme hızı V8'den daha yavaştır.
• ❌ Enstrümantasyon dosya boyutlarını artırır.
• ❌ Bellek kullanımı V8'den daha yüksektir.

Kapsam Kurulumu

TIP

Yapılandırma dosyanızda her zaman coverage.include belirtmeniz tavsiye edilir. Bu, Vitest'in coverage.all tarafından seçilen dosya sayısını azaltmasına yardımcı olur.

Kapsam etkinleştirilmiş olarak test etmek için CLI'da --coverage bayrağını kullanabilirsiniz. Varsayılan olarak, ['text', 'html', 'clover', 'json'] raporlayıcı kullanılır.

{
  "scripts": {
    "test": "vitest",
    "coverage": "vitest run --coverage"
  }
}

Yapılandırmak için, yapılandırma dosyanızdaki test.coverage seçeneklerini belirleyin:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    coverage: {
      reporter: ['text', 'json', 'html'],
    },
  },
});

Özel Kapsam Raporlayıcısı

test.coverage.reporter içinde paketin adını veya mutlak yolunu belirterek özel kapsam raporlayıcıları kullanabilirsiniz:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    coverage: {
      reporter: [
        // NPM paketinin adını kullanarak raporlayıcıyı belirtme
        ['@vitest/custom-coverage-reporter', { someOption: true }],

        // Yerel yolu kullanarak raporlayıcıyı belirtme
        '/absolute/path/to/custom-reporter.cjs',
      ],
    },
  },
});

Özel raporlayıcılar Istanbul tarafından yüklenir ve onun raporlayıcı arayüzüne uygun olmalıdır. Referans için yerleşik raporlayıcıların gerçekleştirimine göz atın.

const { ReportBase } = require('istanbul-lib-report');

module.exports = class CustomReporter extends ReportBase {
  constructor(opts) {
    super();

    // Yapılandırmadan geçirilen seçenekler burada kullanılabilir
    this.file = opts.file;
  }

  onStart(root, context) {
    this.contentWriter = context.writer.writeFile(this.file);
    this.contentWriter.println('Özel Kapsam Raporunun Başlangıcı');
  }

  onEnd() {
    this.contentWriter.println('Özel Kapsam Raporunun Sonu');
    this.contentWriter.close();
  }
};

Özel Kapsam Sağlayıcısı

test.coverage.provider içinde 'custom' belirterek kendi özel kapsam sağlayıcınızı sağlamak da mümkündür.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    coverage: {
      provider: 'custom',
      customProviderModule: 'my-custom-coverage-provider',
    },
  },
});

Özel sağlayıcılar, CoverageProviderModule'ün yükleneceği bir modül adı veya yolu olan bir customProviderModule seçeneği gerektirir. Varsayılan dışa aktarma olarak CoverageProviderModule'ü uygulayan bir nesneyi dışa aktarmalıdır.

import type {
  CoverageProvider,
  CoverageProviderModule,
  ResolvedCoverageOptions,
  Vitest,
} from 'vitest';

const CustomCoverageProviderModule: CoverageProviderModule = {
  getProvider(): CoverageProvider {
    return new CustomCoverageProvider();
  },

  // CoverageProviderModule'ün geri kalanını uygular.
};

class CustomCoverageProvider implements CoverageProvider {
  name = 'custom-coverage-provider';
  options!: ResolvedCoverageOptions;

  initialize(ctx: Vitest) {
    this.options = ctx.config.coverage;
  }

  // CoverageProvider'ın geri kalanını uygular.
}

export default CustomCoverageProviderModule;

Daha fazla ayrıntı için lütfen tür tanımına bakın.

Varsayılan Kapsam Klasör Konumunu Değiştirme

Bir kapsam raporu çalıştırıldığında, projenizin kök dizininde bir coverage klasörü oluşturulur. Bunu farklı bir dizine taşımak isterseniz, vitest.config.js dosyasındaki test.coverage.reportsDirectory özelliğini kullanabilirsiniz.

import { defineConfig } from 'vite';

export default defineConfig({
  test: {
    coverage: {
      reportsDirectory: './tests/unit/coverage',
    },
  },
});

Kodu Yoksayma

Her iki kapsam sağlayıcısının da kapsam raporlarından kodu yoksaymak için kendi yöntemleri bulunur:

• v8
• ìstanbul
• v8 ile experimentalAstAwareRemapping: true için ast-v8-to-istanbul | Kodu yoksayma bölümüne göz atın.

TypeScript kullanıldığında kaynak kodlar esbuild kullanılarak dönüştürülür, bu da tüm yorumları kaynak kodlardan kaldırır (esbuild#516). Yasal yorumlar olarak kabul edilen yorumlar korunur.

Yoksayma ipucuna @preserve anahtar kelimesini ekleyebilirsiniz. Bu yoksayma ipuçlarının artık nihai üretim derlemesine de dahil edilebileceğine dikkat edilmelidir.

-/* istanbul ignore if */
+/* istanbul ignore if -- @preserve */
if (condition) {

-/* v8 ignore if */
+/* v8 ignore if -- @preserve */
if (condition) {

Diğer Seçenekler

Kapsam için tüm yapılandırılabilir seçenekleri görmek üzere kapsam Yapılandırma Referansı bölümüne göz atın.

Kapsam Performansı

Projenizde kod kapsamı oluşturma yavaşsa, Test Performansını Profillendirme | Kod kapsamı bölümüne bakın.

Vitest UI

Kapsam raporunuzu Vitest UI üzerinden kontrol edebilirsiniz.

Vitest UI, kapsam raporu açıkça etkinleştirildiğinde ve HTML kapsam raporlayıcısı mevcut olduğunda kapsam raporunu etkinleştirir; aksi takdirde kullanılamaz:

• Yapılandırma dosyanızda coverage.enabled=true'yu etkinleştirin veya Vitest'i --coverage.enabled=true bayrağıyla çalıştırın.
• html'i coverage.reporter listesine ekleyin. Kapsam raporunu bir alt dizinde oluşturmak için subdir seçeneğini de etkinleştirebilirsiniz.