Node.js Test Mock ve Coverage: mock.fn, mock.timers ve mock.module

Neyi taklit etmeli, neyi etmemeli?

Learn rehberindeki tanıma göre stub, hiçbir şey yapmayan ama çağrılarını kaydeden bir yer tutucudur; mock ise buna sahte bir davranış ekler. Pratikte iki terim çoğu zaman aynı anlamda kullanılır. Asıl soru şudur: testin sonucunu belirleyen şey sizin kodunuz mu, yoksa kontrol etmediğiniz bir parça mı? Rehber, taklit adaylarını üçe ayırır ve her biri için farklı bir tutum önerir:

Rehberin uyarısı önemlidir: aynı veritabanını değiştiren iki test eşzamanlı çalışırsa birbirini bozabilir. Testlerin her sırayla ve her sayıda çalıştırıldığında aynı sonucu vermesi, yani deterministik olması hedeflenir. Uçtan uca testlerde ise hiçbir şey taklit edilmez; amaç gerçek sistemi denemektir.

mock.fn ile sahte fonksiyon

mock.fn() bir Proxy döndürür. Bu fonksiyonu çağırdığınızda her çağrı kaydedilir ve kayıtlara fn.mock üzerinden ulaşırsınız. Argüman vermezseniz hiçbir şey yapmayan bir fonksiyon elde edersiniz; bir fonksiyon verirseniz o fonksiyon gerçekten çalışır ama çağrıları izlenir. Bildirim gönderen bir fonksiyonu, gerçek e-posta atmadan test edelim:

// fn.test.mjs
import { test } from 'node:test';
import assert from 'node:assert/strict';

function bildirimGonder(kullanicilar, gonder) {
  for (const k of kullanicilar) {
    if (k.izin) gonder(k.eposta, 'Kampanya başladı');
  }
}

test('yalnızca izin verenlere gönderir', (t) => {
  const gonder = t.mock.fn();
  bildirimGonder(
    [{ eposta: 'a@ornek.com', izin: true }, { eposta: 'b@ornek.com', izin: false }],
    gonder,
  );
  assert.equal(gonder.mock.callCount(), 1);
  assert.deepEqual(gonder.mock.calls[0].arguments, ['a@ornek.com', 'Kampanya başladı']);
  t.assert.called(gonder);
  t.assert.callCount(gonder, 1);
});

test('times ile ilk çağrılarda farklı davranış', (t) => {
  const gercek = () => 'gerçek';
  const sahte = () => 'sahte';
  const f = t.mock.fn(gercek, sahte, { times: 2 });
  console.log(f(), f(), f()); // çıktı: sahte sahte gerçek
  f.mock.mockImplementationOnce(() => 'bir kerelik');
  console.log(f(), f()); // çıktı: bir kerelik gerçek
});

test('hata fırlatan mock', (t) => {
  const f = t.mock.fn(() => {
    throw new TypeError('bozuk');
  });
  assert.throws(() => f(5));
  const c = f.mock.calls[0];
  console.log(c.arguments, c.result, c.error.message); // çıktı: [ 5 ] undefined bozuk
});

mock.calls dizisindeki her kayıtta arguments, result, fonksiyon hata fırlattıysa error, çağrının yapıldığı yeri bulmak için stack, fonksiyon this değeri ve kurucu olarak çağrıldıysa target alanları bulunur. Belgelere göre calls her okunduğunda iç dizinin bir kopyasını üretir; yalnızca sayı lazımsa callCount() daha verimlidir. times seçeneği, ikinci argümandaki davranışın kaç çağrı boyunca geçerli olacağını belirtir; sayı dolunca asıl fonksiyonun davranışı geri gelir. v26.12.0 ile eklenen t.assert.called() ve t.assert.callCount() ise bu kontrolleri tek satırlık doğrulamaya çevirir.

Global mock mu, t.mock mu?

Modül, en üst düzeyde mock adlı bir MockTracker örneği dışa aktarır; her testin bağlamı da kendi t.mock örneğini taşır. Fark temizlikte ortaya çıkar. t.mock ile oluşturduğunuz her şey test bittiğinde test çalıştırıcısı tarafından kendiliğinden geri alınır. Global mock kullandığınızda ise geri almak sizin işinizdir: mock.reset() bütün taklitleri eski hâline getirir ve izleyiciyle bağlarını koparır, mock.restoreAll() eski hâline getirir ama bağı korur. Belgeler, global izleyiciyi yoğun kullanıyorsanız reset() çağrısını kendiniz yapmanızı önerir. Bu yüzden testlerin içinde t.mock tercih etmek, testler arasında sızan taklitlerden kaçınmanın en kolay yoludur.

mock.method ve mock.property ile var olan nesneyi değiştirmek

Bağımlılığı parametre olarak almayan kodda, nesnenin bir metodunu yerinde değiştirmek gerekir. mock.method(nesne, 'ad', uygulama) tam bunu yapar; uygulama vermezseniz asıl metot çalışır ama çağrılar izlenir. Metot yoksa ya da fonksiyon değilse hata fırlatılır. mock.getter() ve mock.setter() aynı işi erişimciler için yapar. v24.3.0 ile gelen mock.property() ise düz bir özelliğin değerini değiştirir ve okuma ile yazmaları ayrı ayrı sayar:

// method.test.mjs
import { test } from 'node:test';
import assert from 'node:assert/strict';

const depo = {
  async kullaniciGetir(id) {
    throw new Error('gerçek veritabanına bağlanmaya çalıştı');
  },
};

async function selamla(id) {
  const k = await depo.kullaniciGetir(id);
  return `Merhaba ${k.ad}`;
}

test('depo.kullaniciGetir sahte veri döner', async (t) => {
  t.mock.method(depo, 'kullaniciGetir', async (id) => ({ id, ad: 'Elif' }));
  assert.equal(await selamla(7), 'Merhaba Elif');
  assert.deepEqual(depo.kullaniciGetir.mock.calls[0].arguments, [7]);
});

test('önceki testin mock\'u geri alınmıştır', async () => {
  await assert.rejects(selamla(1), /gerçek veritabanına/);
});

test('Math.random sabitlenir', (t) => {
  t.mock.method(Math, 'random', () => 0.5);
  console.log(Math.random(), Math.floor(Math.random() * 6) + 1); // çıktı: 0.5 4
});

test('property mock', (t) => {
  const ayar = { mod: 'uretim' };
  const p = t.mock.property(ayar, 'mod', 'test');
  console.log(ayar.mod, p.mock.accessCount()); // çıktı: test 1
  p.mock.restore();
  console.log(ayar.mod); // çıktı: uretim
});

İkinci test, ilk testteki taklidin test bitince geri alındığını kanıtlıyor: aynı fonksiyon artık gerçek hatayı fırlatıyor. mock.property() çıktısındaki 1, console.log argümanı hazırlanırken yapılan tek okumadır. Belgelerdeki bir uyarıya dikkat edin: mockImplementationOnce() özelliklerde okuma ve yazmayı aynı sayaçta tuttuğu için, o sıradaki erişim bir yazma olursa "bir kerelik" değer yazma tarafından tüketilir.

fetch çağrısını ağa çıkmadan taklit etmek

Learn rehberi, fetch için undici paketinin MockAgent aracını gösterir; ancak rehberin de belirttiği gibi bu paketin ayrıca kurulması gerekir. Paket kurmadan basit bir yol, global fetch fonksiyonunu mock.method() ile değiştirmektir. Response.json() hazır bir yanıt nesnesi üretir:

// fetch.test.mjs
import { test } from 'node:test';
import assert from 'node:assert/strict';

async function havaDurumu(sehir) {
  const yanit = await fetch(`https://api.ornek.com/hava?sehir=${encodeURIComponent(sehir)}`);
  if (!yanit.ok) throw new Error(`HTTP ${yanit.status}`);
  const veri = await yanit.json();
  return `${sehir}: ${veri.derece} °C`;
}

test('fetch ağa çıkmadan taklit edilir', async (t) => {
  const sahteFetch = t.mock.method(globalThis, 'fetch', async () =>
    Response.json({ derece: 18 }),
  );
  assert.equal(await havaDurumu('İzmir'), 'İzmir: 18 °C');
  console.log(sahteFetch.mock.calls[0].arguments[0]);
  // çıktı: https://api.ornek.com/hava?sehir=%C4%B0zmir
});

test('hata durumu da denenebilir', async (t) => {
  t.mock.method(globalThis, 'fetch', async () => new Response('yok', { status: 503 }));
  await assert.rejects(havaDurumu('Van'), { message: 'HTTP 503' });
});

Böylece hem başarılı yanıtı hem de sunucu hatasını saniyeler içinde, internet bağlantısı olmadan deneyebilirsiniz. fetch API'sinin kendisi için Node.js fetch rehberine bakabilirsiniz.

Zamanı kontrol etmek: mock.timers

Otuz dakika sonra kapanan bir oturumu test etmek için gerçekten otuz dakika beklemek istemezsiniz. mock.timers.enable() seçilen zamanlayıcıları sahte bir saate bağlar; tick(ms) saati ileri sarar ve süresi dolan geri çağırmaları senkron olarak çalıştırır. MockTimers, YAML kaydına göre v23.1.0 ile kararlı hâle geldi. apis dizisi verilmezse setInterval, setTimeout, setImmediate, bunların clear karşılıkları ve Date birlikte taklit edilir; bir zamanlayıcıyı seçtiğinizde ona ait clear fonksiyonu da otomatik taklit edilir.

// zaman.test.mjs
import { test } from 'node:test';
import assert from 'node:assert/strict';

function oturumBaslat(sureMs, bitince) {
  const id = setTimeout(bitince, sureMs);
  return () => clearTimeout(id);
}

test('30 dakika sonra oturum kapanır', (t) => {
  t.mock.timers.enable({ apis: ['setTimeout'] });
  const bitti = t.mock.fn();
  oturumBaslat(30 * 60 * 1000, bitti);

  t.mock.timers.tick(29 * 60 * 1000);
  assert.equal(bitti.mock.callCount(), 0);
  t.mock.timers.tick(60 * 1000);
  assert.equal(bitti.mock.callCount(), 1);
});

test('iptal edilen zamanlayıcı çalışmaz', (t) => {
  t.mock.timers.enable({ apis: ['setTimeout'] });
  const bitti = t.mock.fn();
  const iptal = oturumBaslat(1000, bitti);
  iptal();
  t.mock.timers.runAll();
  assert.equal(bitti.mock.callCount(), 0);
});

test('Date sabit bir ana çekilir', (t) => {
  t.mock.timers.enable({ apis: ['Date'], now: new Date('2026-01-01T09:00:00Z') });
  console.log(new Date().toISOString()); // çıktı: 2026-01-01T09:00:00.000Z
  t.mock.timers.tick(90 * 60 * 1000);
  console.log(new Date().toISOString()); // çıktı: 2026-01-01T10:30:00.000Z
});

Üç test de birkaç milisaniyede geçti. runAll() kuyruktaki bütün zamanlayıcıları çalıştırır ve sahte saati son zamanlayıcının anına getirir. setTime(ms) saati doğrudan bir ana taşır ama belgelerin vurguladığı gibi geçmişte kalan zamanlayıcıları çalıştırmaz; onları tetiklemek için ardından tick(0) çağırmanız gerekir. Date ile zamanlayıcıları birlikte taklit ettiğinizde ikisi aynı iç saati paylaşır. now verilmezse başlangıç Unix epoch'un sıfır anıdır. Learn rehberi tarih karşılaştırmalarında saat dilimini açıkça yazmayı (örnekteki Z gibi) önerir; yoksa makineden makineye farklı sonuçlar alabilirsiniz. Tarih nesnesinin kendisi için Date ve Temporal yazısına göz atabilirsiniz.

mock.module ile modül değiştirmek

Bazen test ettiğiniz dosya, bağımlılığını kendisi içe aktarır ve ona dışarıdan erişemezsiniz. mock.module() bir ES modülünün, CommonJS modülünün, JSON modülünün ya da yerleşik bir modülün dışa aktarımlarını değiştirir. Kararlılık düzeyi 1.0 - Early development olup Node.js'in --experimental-test-module-mocks bayrağıyla başlatılmasını gerektirir. Kur bilgisini dosyadan okuyan bir modül ve onu kullanan bir fiyat modülü düşünelim:

// kur.mjs
import { readFile } from 'node:fs/promises';

export async function kurOku() {
  const metin = await readFile('/etc/kurlar.json', 'utf8');
  return JSON.parse(metin);
}

// fiyat.mjs
import { kurOku } from './kur.mjs';

export async function dolarFiyati(tl) {
  const { usd } = await kurOku();
  return Number((tl / usd).toFixed(2));
}

// modul.test.mjs
import { test } from 'node:test';
import assert from 'node:assert/strict';

test('kur modülü sahtesiyle değiştirilir', async (t) => {
  t.mock.module('./kur.mjs', {
    exports: { kurOku: async () => ({ usd: 40 }) },
  });
  // Mock kurulduktan SONRA dinamik import şart
  const { dolarFiyati } = await import('./fiyat.mjs');
  assert.equal(await dolarFiyati(1000), 25);
});

$ node --test modul.test.mjs
✖ kur modülü sahtesiyle değiştirilir (0.5484ms)
...
  TypeError [Error]: t.mock.module is not a function

$ node --test --experimental-test-module-mocks modul.test.mjs
(node:50804) ExperimentalWarning: Module mocking is an experimental feature and might change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
✔ kur modülü sahtesiyle değiştirilir (4.1294ms)

Bayrak olmadan t.mock.module bir fonksiyon bile değildir; aldığınız TypeError genellikle bayrağın unutulduğunu gösterir. Test dosyasının başında fiyat.mjs dosyasını statik olarak içe aktarsaydınız, modül taklit kurulmadan önce yüklenmiş olurdu ve belgelere göre taklitten önce alınmış referanslar etkilenmez. Bu yüzden Learn rehberi de dinamik import() kullanır. ES modüllerinin yükleme sırası için ES modülleri yazısına bakabilirsiniz.

Seçeneklerde exports nesnesinin default alanı varsayılan dışa aktarım, diğer alanları isimli dışa aktarımlar olur. Eski defaultExport ve namedExports seçenekleri kullanımdan kaldırılmış (deprecated) olarak işaretli ve exports ile birlikte kullanılamaz. cache: true verirseniz sonraki require() veya import() çağrıları aynı taklidi döndürür. İzin modeliyle birlikte çalışırken bu özellik --allow-worker ister; asenkron modül özelleştirme kancaları ise şimdilik yok sayılır.

Kod kapsamı: --experimental-test-coverage

Kapsam (coverage), testler çalışırken kaynak kodun ne kadarının çalıştığını ölçer. Node.js bunu --experimental-test-coverage bayrağıyla toplar; özellik belgelerde 1 - Experimental olarak işaretlidir. Hiç test çalışmazsa rapor üretilmez. Bir not hesaplama modülü ve yalnızca bir fonksiyonu deneyen bir test:

// not.mjs
export function harfNotu(puan) {
  if (puan >= 85) return 'A';
  if (puan >= 70) return 'B';
  if (puan >= 50) return 'C';
  return 'F';
}

export function ortalama(puanlar) {
  if (puanlar.length === 0) {
    return 0;
  }
  return puanlar.reduce((a, b) => a + b, 0) / puanlar.length;
}

// not.test.mjs
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { harfNotu } from './not.mjs';

test('harf notları', () => {
  assert.equal(harfNotu(90), 'A');
  assert.equal(harfNotu(40), 'F');
});

$ node --test --experimental-test-coverage
✔ harf notları (0.603ms)
...
ℹ start of coverage report
ℹ ----------------------------------------------------------
ℹ file      | line % | branch % | funcs % | uncovered lines
ℹ ----------------------------------------------------------
ℹ not.mjs   |  61.54 |    71.43 |   50.00 | 9-13
ℹ ----------------------------------------------------------
ℹ all files |  61.54 |    71.43 |   50.00 |
ℹ ----------------------------------------------------------
ℹ end of coverage report

Rapor üç ölçü verir: satır yüzdesi, dal (if/else gibi) yüzdesi ve çağrılan fonksiyon yüzdesi. ortalama() hiç çağrılmadığı için 9-13. satırlar kapsanmamış görünüyor ve fonksiyon oranı yüzde 50'de kalıyor. harfNotu() içindeki B ve C dalları da denenmediği için dal oranı düşük. Test dosyası rapora girmedi, çünkü belgelere göre eşleşen test dosyaları varsayılan olarak kapsamdan çıkarılır; Node.js çekirdek modülleri ve node_modules içindeki dosyalar da varsayılan olarak hariçtir.

Eşik vermek, CI'da kapsamın düşmesini engellemenin en basit yoludur. Aynı testi yüzde 90 satır eşiğiyle çalıştırdığımızda rapor aynı kalıyor ama çıktıya bir hata satırı ekleniyor ve süreç 1 koduyla bitiyor:

$ node --test --experimental-test-coverage --test-coverage-lines=90
...
ℹ Error: 61.54% line coverage does not meet threshold of 90%.
...
$ echo $?
1

Bazı satırları bilerek kapsam dışında bırakmak için yorumlar kullanılır: /* node:coverage disable */ ile /* node:coverage enable */ arasındaki satırlar, /* node:coverage ignore next */ sonrasındaki tek satır ya da ignore next 3 ile belirtilen sayıda satır yok sayılır. ortalama() fonksiyonunu disable/enable arasına aldığımızda satır ve fonksiyon oranı 100.00 oldu, harfNotu() içindeki denenmemiş dallar yüzünden dal oranı 71.43 olarak kaldı. Yorum, testleri yazmanın yerine geçmez; yalnızca gerçekten çalışmayacak kod için kullanın.

Ayrıntılı bir HTML raporu üreten araçlar genellikle lcov biçimini okur. lcov raporlayıcısı test sonucu yazmadığı için onu ikinci bir raporlayıcıyla birlikte kullanın:

node --test --experimental-test-coverage --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=lcov.info

NODE_V8_COVERAGE ortam değişkeniyle bir klasör belirtirseniz V8'in ham kapsam dosyaları da oraya yazılır.

Kapsamı run() ile programdan toplamak

Komut satırı yerine kendi betiğinizden test çalıştırmak istediğinizde run() fonksiyonunu kullanırsınız. Kapsam için coverage: true, eşik için lineCoverage, branchCoverage ve functionCoverage seçenekleri vardır. Bütün testler bittiğinde akış test:coverage olayını yayar; olayın summary.totals alanında toplam satır, dal ve fonksiyon yüzdeleri bulunur. Bu sayede kapsamı bir panoya yazmak ya da kendi kuralınıza göre derlemeyi durdurmak için rapor metnini ayrıştırmanız gerekmez:

// calistir.mjs
import { run } from 'node:test';
import { spec } from 'node:test/reporters';

const akis = run({ files: ['not.test.mjs'], coverage: true, lineCoverage: 90 });
akis.on('test:coverage', ({ summary }) => {
  console.log('satır yüzdesi:', summary.totals.coveredLinePercent.toFixed(2));
});
akis.on('test:fail', () => { process.exitCode = 1; });
akis.compose(spec).pipe(process.stdout);

$ node calistir.mjs
✔ harf notları (0.5899ms)
...
ℹ Error: 61.54% line coverage does not meet threshold of 90%.
satır yüzdesi: 61.54
...
$ echo $?
1

Testin kendisi geçtiği hâlde süreç 1 koduyla bitti; bunu eşik sağladı. Belgelerde run() için listelenen coverageIncludeGlobs ve coverageExcludeGlobs seçenekleri, komut satırındaki include ve exclude bayraklarının karşılığıdır. İkisini birlikte verdiğinizde bir dosyanın rapora girmesi için her iki koşulu da sağlaması gerekir.

Sık yapılan hatalar

• Modülü taklitten önce içe aktarmak: statik import modülü taklit kurulmadan yükler; mock.module() sonrasında dinamik import() kullanın.
• Bayrağı unutmak: t.mock.module is not a function hatası --experimental-test-module-mocks bayrağının eksik olduğunu gösterir.
• Global mock'u sıfırlamamak: en üstteki mock nesnesiyle yapılan taklitler test bitince kendiliğinden geri alınmaz; t.mock kullanın ya da mock.reset() çağırın.
• Parçalanmış zamanlayıcı importu: import { setTimeout } ile alınan fonksiyon mock.timers tarafından taklit edilmez.
• Saat dilimsiz tarih: now değerini Z gibi açık bir saat dilimiyle verin.
• Kapsamı doğrulukla karıştırmak: yüzde 100 satır kapsamı her dalın ve her girdinin denendiği anlamına gelmez; dal oranına da bakın.
• Yalnızca lcov kullanmak: lcov raporlayıcısı test sonuçlarını basmaz; başarısız testleri görmek için yanına spec ekleyin.

Sık Sorulan Sorular

mock.fn ile mock.method arasındaki fark nedir?

mock.fn() yeni, bağımsız bir sahte fonksiyon üretir ve genellikle parametre olarak geçirilir. mock.method() var olan bir nesnenin metodunu yerinde değiştirir; kod bağımlılığı doğrudan bir nesneden çağırıyorsa bunu kullanırsınız.

Taklitleri her testten sonra elle geri almam gerekir mi?

t.mock kullanıyorsanız hayır; test çalıştırıcısı test bitince taklitleri geri alır ve zamanlayıcıları sıfırlar. Global mock için mock.reset() çağrısını kendiniz yapmalısınız.

Kapsam raporu üretimde kullanılabilir mi?

Kapsam toplama özelliği deneyseldir ve test çalıştırıcısıyla birlikte çalışır; amacı geliştirme ve CI sırasında eksik testleri göstermektir. Bayrağın davranışı sürümler arasında değişebileceği için kullandığınız sürümün belgelerini kontrol edin.

setInterval ile çalışan kodu nasıl test ederim?

mock.timers.enable({ apis: ['setInterval'] }) ile taklidi açın ve her tick() çağrısından sonra geri çağırmanın kaç kez çalıştığını callCount() ile kontrol edin. clearInterval da otomatik olarak taklit edilir.

Gerçek veritabanını mı kullanmalıyım, taklit mi etmeliyim?

Learn rehberine göre harici sistemleri her test için yalıtılmış bir kopyayla çalıştırmak genellikle pahalıdır; bu durumda taklit en iyi seçenektir. Bununla birlikte birkaç entegrasyon testini gerçek bir veritabanına karşı çalıştırmak, taklitlerin gerçeği doğru yansıtıp yansıtmadığını gösterir. Yerleşik SQLite modülüyle bellek içinde çalışan bir veritabanı kurmak için node:sqlite rehberine bakabilirsiniz.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Node.js öğrenme rehberi · node:test temelleri · Node.js timers · Node.js fetch · Node.js debug · Jest rehberi