Node.js Test Runner: node:test ve node --test ile Test Yazma

node:test nedir ve ne kadar olgun?

node:test, JavaScript testleri oluşturmayı sağlayan yerleşik modüldür. Belgelerde kararlılık düzeyi 2 - Stable olarak geçer; modülün YAML kaydına göre test çalıştırıcısı v20.0.0 ile kararlı hâle geldi. Modül yalnızca node: önekiyle yüklenebilir, yani import test from 'test' yazarsanız npm'deki aynı adlı başka bir paketi aramaya başlarsınız. Doğru kullanım import { test, describe, it } from 'node:test' biçimidir.

Bir test, tek bir fonksiyondan oluşur ve bu fonksiyon üç şekilde değerlendirilir. Senkron bir fonksiyon hata fırlatırsa test başarısız, fırlatmazsa başarılı sayılır. Promise döndüren (örneğin async) bir fonksiyonda Promise reddedilirse test başarısız olur. Üçüncü yol geri çağırma fonksiyonudur: test fonksiyonunun ikinci parametresi olan done doğru (truthy) bir değerle çağrılırsa test başarısız sayılır. Aynı fonksiyonun hem done parametresi alması hem de Promise döndürmesi testi başarısız yapar; bu iki stili karıştırmayın. Promise ve async/await dil özelliklerinin kendisi için async/await rehberine bakabilirsiniz.

Herhangi bir test başarısız olursa sürecin çıkış kodu 1 olur. CI sistemleri bu kodu okuyarak derlemeyi kırar; çıkış kodlarının genel anlamı process.argv ve çıkış kodları yazısında anlatılıyor.

İlk test dosyası

Küçük bir sepet modülüyle başlayalım. Modül toplamı hesaplıyor, indirim uyguluyor ve kısa bir beklemeden sonra kargo ücretini döndürüyor:

// sepet.mjs
export function toplam(urunler) {
  return urunler.reduce((t, u) => t + u.fiyat * u.adet, 0);
}

export function indirim(tutar, oran) {
  if (oran < 0 || oran > 100) {
    throw new RangeError('oran 0-100 arasında olmalı');
  }
  return tutar - (tutar * oran) / 100;
}

export async function kargoUcreti(tutar) {
  await new Promise((r) => setTimeout(r, 10));
  return tutar >= 500 ? 0 : 49.9;
}

Test dosyasının adı .test.mjs ile bitiyor; böylece node --test onu kendiliğinden bulur. describe() bir grup (suite) açar, it() tek bir test tanımlar. Doğrulamalar için node:assert/strict kullanıyoruz:

// sepet.test.mjs
import { describe, it } from 'node:test';
import assert from 'node:assert/strict';
import { toplam, indirim, kargoUcreti } from './sepet.mjs';

describe('sepet', () => {
  it('toplamı adet ile çarparak hesaplar', () => {
    const urunler = [{ fiyat: 100, adet: 2 }, { fiyat: 50, adet: 1 }];
    assert.equal(toplam(urunler), 250);
  });

  it('boş sepet 0 döner', () => {
    assert.equal(toplam([]), 0);
  });

  describe('indirim', () => {
    it('yüzde 10 indirim uygular', () => {
      assert.equal(indirim(200, 10), 180);
    });

    it('geçersiz oranda RangeError fırlatır', () => {
      assert.throws(() => indirim(200, 150), RangeError);
    });
  });

  it('500 TL ve üstünde kargo ücretsizdir', async () => {
    assert.equal(await kargoUcreti(500), 0);
    assert.equal(await kargoUcreti(120), 49.9);
  });
});

Proje klasöründe node --test çalıştırdığınızda varsayılan spec raporlayıcısı şu çıktıyı verir:

$ node --test
▶ sepet
  ✔ toplamı adet ile çarparak hesaplar (0.5082ms)
  ✔ boş sepet 0 döner (0.0844ms)
  ▶ indirim
    ✔ yüzde 10 indirim uygular (0.1234ms)
    ✔ geçersiz oranda RangeError fırlatır (0.3539ms)
  ✔ indirim (0.6857ms)
  ✔ 500 TL ve üstünde kargo ücretsizdir (38.4026ms)
✔ sepet (41.3023ms)
ℹ tests 5
ℹ suites 2
ℹ pass 5
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 135.265

Özet satırları ayrı sayar: beş test, iki grup. Test dosyasını node sepet.test.mjs diye doğrudan da çalıştırabilirsiniz; o zaman yalnızca o dosya, ayrı bir alt süreç açılmadan çalışır. Komut satırı seçeneklerinin genel kullanımı için node komutuyla betik çalıştırma yazısına bakabilirsiniz.

node --test hangi dosyaları bulur?

Argüman vermeden node --test çalıştırırsanız Node.js çalışma dizininde şu kalıplara uyan dosyaları test dosyası sayar:

• **/*.test.{cjs,mjs,js}, **/*-test.{cjs,mjs,js} ve **/*_test.{cjs,mjs,js}
• **/test-*.{cjs,mjs,js} ve **/test.{cjs,mjs,js}
• **/test/**/*.{cjs,mjs,js}, yani test klasörü altındaki her JavaScript dosyası
• --no-strip-types verilmediği sürece aynı kalıpların .ts, .mts ve .cts karşılıkları

TypeScript dosyalarının nasıl çalıştığı bu yazının konusu değil; tip ayıklama ve ayarlar için TypeScript ile Node.js rehberine bakın. Kendi kalıplarınızı da komutun sonuna ekleyebilirsiniz. Belgeler, kalıpların kabuk tarafından genişletilmemesi için çift tırnak içinde yazılmasını önerir:

node --test "**/*.test.js" "**/*.spec.js"

Eşleşen her dosya varsayılan olarak ayrı bir alt süreçte çalışır; bu, belgelerdeki adıyla süreç düzeyinde yalıtımdır. Aynı anda en fazla kaç dosyanın çalışacağını --test-concurrency belirler, varsayılanı os.availableParallelism() - 1 değeridir. Alt süreç 0 koduyla biterse dosya başarılı sayılır, bu yüzden test dosyasının node:test kullanması bile zorunlu değildir. --test-isolation=none verdiğinizde ise bütün dosyalar test çalıştırıcısının kendi sürecine yüklenir; bu daha az süreç açar ama bir dosyanın değiştirdiği global durum başka bir dosyadaki testi etkileyebilir. İşlemci çekirdeklerini nasıl öğrendiğinizi merak ediyorsanız os modülü yazısı availableParallelism() fonksiyonunu anlatıyor.

test, describe, it ve alt testler

describe(), suite() fonksiyonunun; it() de test() fonksiyonunun takma adıdır. Hangisini seçeceğiniz zevk meselesidir, davranış aynıdır. Önemli fark alt testlerdedir: bir test() içinde t.test() ile alt test açtığınızda üst test, alt testlerin bitmesini kendiliğinden beklemez. Üst test bittiği anda hâlâ çalışan alt testler iptal edilir ve başarısız sayılır. Bu yüzden alt testleri await ile çağırmanız gerekir. describe() içindeki it() çağrıları için böyle bir bekleme gerekmez, çünkü grup içinde tanımlanan testler sıraya alınır.

Aşağıdaki dosyada üç durum var: t.plan() ile beklenen doğrulama sayısını sabitlemek, alt testleri beklemek ve tutmayan bir plan:

// plan.test.mjs
import { test } from 'node:test';
import { EventEmitter } from 'node:events';

test('olay iki kez tetiklenir', (t) => {
  t.plan(2);
  const e = new EventEmitter();
  e.on('veri', (x) => t.assert.ok(x > 0));
  e.emit('veri', 1);
  e.emit('veri', 2);
});

test('alt testler', async (t) => {
  await t.test('alt 1', () => {});
  await t.test('alt 2', () => {});
});

test('plan tutmazsa', (t) => {
  t.plan(3);
  t.assert.equal(1, 1);
});

$ node --test plan.test.mjs
✔ olay iki kez tetiklenir (0.6196ms)
▶ alt testler
  ✔ alt 1 (16.2617ms)
  ✔ alt 2 (0.1233ms)
✔ alt testler (16.765ms)
✖ plan tutmazsa (0.1992ms)
ℹ tests 5
ℹ suites 0
ℹ pass 4
ℹ fail 1
...
✖ failing tests:

test at plan.test.mjs:17:1
✖ plan tutmazsa (0.1992ms)
  'plan expected 3 assertions but received 1'

Planın sayabilmesi için doğrulamaların assert modülünden değil t.assert üzerinden yapılması gerekir; belgeler bunu özellikle not düşer. t.plan() olay tabanlı kodda çok işe yarar: dinleyici hiç çağrılmazsa test sessizce geçmek yerine başarısız olur. Olay yayıcıların kendisi için EventEmitter rehberine bakabilirsiniz. Planın asenkron doğrulamaları beklemesi gerekiyorsa t.plan(1, { wait: 2000 }) gibi bir wait süresi verilebilir; süre, test fonksiyonu bittikten sonra işlemeye başlar.

Başarısız bir test neye benzer?

Hata ayıklarken en çok okuyacağınız şey başarısız testin çıktısıdır. Aşağıdaki test kasıtlı olarak yanlış bir yaş bekliyor:

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

test('yanlış beklenti', () => {
  assert.deepEqual({ ad: 'Ayşe', yas: 30 }, { ad: 'Ayşe', yas: 31 });
});

$ node --test hata.test.mjs
✖ yanlış beklenti (1.4424ms)
...
ℹ fail 1
...
✖ failing tests:

test at hata.test.mjs:4:1
✖ yanlış beklenti (1.4424ms)
  AssertionError [ERR_ASSERTION]: Expected values to be strictly deep-equal:
  + actual - expected

    {
      ad: 'Ayşe',
  +   yas: 30
  -   yas: 31
    }

      at TestContext.<anonymous> (file:///home/kullanici/proje/hata.test.mjs:5:10)
      ... {
    generatedMessage: true,
    code: 'ERR_ASSERTION',
    actual: { ad: 'Ayşe', yas: 30 },
    expected: { ad: 'Ayşe', yas: 31 },
    operator: 'deepStrictEqual',
    diff: 'simple'
  }
$ echo $?
1

Çıktı kısaltıldı ve yerel yol /home/kullanici/proje ile değiştirildi. Hatanın sınıfı AssertionError, kodu ERR_ASSERTION; + actual - expected satırları farkı satır satır gösterir. node:assert/strict içe aktarıldığı için deepEqual aslında deepStrictEqual gibi davranır; operator alanı da bunu doğrular. Gevşek karşılaştırmanın neden sürpriz ürettiğini eşitlik operatörleri yazısında görebilirsiniz. Sık kullanılan doğrulamalar şunlardır:

Kancalar: before, after, beforeEach, afterEach

Veritabanı bağlantısı açmak, geçici klasör oluşturmak ya da her testten önce durumu sıfırlamak için kancaları kullanırsınız. before() grup başlamadan bir kez, after() grup bittikten sonra bir kez çalışır; beforeEach() ve afterEach() ise o gruptaki her testin önünde ve arkasında çalışır. Sırayı görmek için:

// kancalar.test.mjs
import { describe, it, before, after, beforeEach, afterEach } from 'node:test';

describe('kanca sırası', () => {
  before(() => console.log('before: bir kez, en başta'));
  beforeEach(() => console.log('beforeEach'));
  afterEach(() => console.log('afterEach'));
  after(() => console.log('after: bir kez, en sonda'));

  it('birinci', () => console.log('  test 1'));
  it('ikinci', () => console.log('  test 2'));
});

$ node kancalar.test.mjs
before: bir kez, en başta
beforeEach
  test 1
afterEach
beforeEach
  test 2
afterEach
after: bir kez, en sonda
▶ kanca sırası
  ✔ birinci (5.5555ms)
  ✔ ikinci (0.3246ms)
✔ kanca sırası (7.7244ms)
ℹ tests 2
...

Dikkat edin: console.log satırları rapordan önce göründü. Raporlayıcı sonuçları kendi düzeninde yazdığı için test içinden basılan çıktının rapordaki test satırının hemen yanında görüneceğini varsaymayın. Belgelere göre after() kancası gruptaki testler başarısız olsa bile çalışır, afterEach() de başarısız testten sonra yine çağrılır; temizlik kodunu bu yüzden gönül rahatlığıyla oraya koyabilirsiniz. Her kanca timeout ve signal seçeneklerini alır. Bütün test dosyalarından önce bir kez çalışacak hazırlık için --test-global-setup=modul.mjs bayrağı ve globalSetup/globalTeardown dışa aktarımları vardır; bu özellik v24.0.0 ile geldi ve kararlılığı 1.0 - Early development düzeyindedir.

skip, todo, only ve zaman aşımı

Her test bir seçenek nesnesi alabilir. Aşağıdaki dosya en sık kullanılan dört seçeneği gösteriyor:

// secim.test.mjs
import { test } from 'node:test';

test('giriş yapılır', () => {});
test('çıkış yapılır', () => {});
test('ödeme servisi', { skip: 'sandbox anahtarı yok' }, () => {});
test('e-posta doğrulaması', { todo: 'henüz yazılmadı' }, () => {
  throw new Error('başarısız ama todo');
});
test('yavaş rapor', { timeout: 50 }, async () => {
  await new Promise((r) => setTimeout(r, 200));
});

$ node --test secim.test.mjs
✔ giriş yapılır (0.4424ms)
✔ çıkış yapılır (0.0694ms)
﹣ ödeme servisi (0.6075ms) # sandbox anahtarı yok
⚠ e-posta doğrulaması (0.1322ms) # henüz yazılmadı
✖ yavaş rapor (52.4744ms)
ℹ tests 5
ℹ suites 0
ℹ pass 2
ℹ fail 0
ℹ cancelled 1
ℹ skipped 1
ℹ todo 1
...
test at secim.test.mjs:9:1
✖ yavaş rapor (52.4744ms)
  'test timed out after 50ms'
$ echo $?
1

skip verilen test hiç çalışmaz, verilen metin rapora gerekçe olarak yazılır. todo testleri ise çalışır ama başarısız olsalar bile çıkış kodunu etkilemez; yarım kalmış ya da bilinen bir hatayı izleyen testler için uygundur. Zaman aşımına uğrayan test, özet satırında cancelled olarak sayıldı ve çıkış kodunu 1 yaptı. Belgeler timeout seçeneğinin güvenilir bir iptal mekanizması olmadığını da hatırlatır: iş parçacığını bloklayan senkron bir döngü, planlanan iptalin çalışmasını engelleyebilir. Neden bloklama olduğunu anlamak için Node.js olay döngüsü fazları yazısına göz atabilirsiniz.

only seçeneği tek başına bir şey yapmaz: Node.js'i --test-only ile başlatmanız gerekir (yalıtım kapalıysa bu bayrak gerekmez). Alt test kullanıyorsanız seçili alt teste giden yoldaki bütün üst testleri de only ile işaretlemelisiniz. Bir de t.skip() yöntemi var; bu çağrı testi atlandı olarak işaretler ama fonksiyonun geri kalanını durdurmaz, ardından return yazmanız gerekir. v25.5.0 ile gelen expectFailure seçeneği ise sonucu tersine çevirir: işaretli test ancak hata fırlatırsa geçer.

İsme göre test seçmek

Büyük bir projede yalnızca birkaç testi çalıştırmak istediğinizde --test-name-pattern ve --test-skip-pattern bayraklarını kullanırsınız. İkisi de JavaScript düzenli ifadesi olarak yorumlanır ve birden fazla kez verilebilir. İkisini birlikte verirseniz test her iki koşulu da sağlamalıdır:

$ node --test --test-name-pattern="giriş|çıkış" secim.test.mjs
✔ giriş yapılır (0.4637ms)
✔ çıkış yapılır (0.0671ms)
ℹ tests 2
...
$ node --test --test-skip-pattern="yavaş" secim.test.mjs

Eşleşmeyen testler rapordan tamamen çıkarılır. Büyük-küçük harf duyarsız eşleşme için --test-name-pattern="/test [4-5]/i" gibi düzenli ifade sözdizimi yazılabilir. Aynı adlı iki testi ayırmak için desenin başına üst grupların adlarını boşlukla ekleyebilirsiniz. Önemli bir ayrıntı: bu desenler hangi dosyaların çalıştırılacağını değiştirmez, yalnızca dosyaların içindeki testleri süzer. v26.2.0 ile gelen ve 1.0 - Early development düzeyinde olan etiket desteği ise testlere tags: ['db'] gibi etiketler verip --experimental-test-tag-filter='db && !flaky' ile seçim yapmayı sağlar.

Raporlayıcılar: spec, tap, dot, junit, lcov

--test-reporter bayrağı çıktının biçimini seçer. Varsayılan spec insan okuması içindir; v23.0.0 ile TTY olmayan çıktıda da varsayılan oldu. tap TAP biçimini, dot her başarılı test için bir nokta basan kısa biçimi, junit CI araçlarının sevdiği jUnit XML biçimini üretir. lcov ise yalnızca kapsam verisi yazar ve test sonucu bildirmez. Aynı sepet testleriyle:

$ node --test --test-reporter=dot
.......
$ node --test --test-reporter=tap
TAP version 13
# Subtest: sepet
    # Subtest: toplamı adet ile çarparak hesaplar
    ok 1 - toplamı adet ile çarparak hesaplar
      ---
      duration_ms: 0.452
      type: 'test'
      ...

dot çıktısındaki yedi nokta, beş test ile iki grubun toplamıdır. Birden fazla raporlayıcıyı aynı anda kullanmak için her birine sırasıyla --test-reporter-destination vermeniz gerekir; hedef stdout, stderr ya da bir dosya yolu olabilir:

node --test --test-reporter=spec --test-reporter=junit --test-reporter-destination=stdout --test-reporter-destination=rapor.xml

Belgeler raporlayıcı çıktısının biçiminin sürümler arasında değişebileceğini, programla işlenmemesi gerektiğini açıkça söyler. Sonuçları kodla okumak istiyorsanız run() fonksiyonunun döndürdüğü TestsStream olaylarını (test:pass, test:fail gibi) dinleyin. Bu nesne bir stream olduğu için stream temelleri yazısı burada da işinize yarar.

Diğer yararlı bayraklar

--test-randomize sıraya bağımlı testleri yakalamak için iyi bir araçtır; ancak alt testleri tek tek await ile çalıştırdığınız döngülerde bildirim sırası korunur. Bu bayrak --watch ve --test-rerun-failures ile birlikte kullanılamaz. --test bayrağı da --watch-path, --check, --eval, --interactive ve inspector ile birleştirilemez. Komut satırı bayraklarının hepsini NODE_OPTIONS ve yapılandırma dosyasıyla nasıl yöneteceğinizi NODE_OPTIONS ve CLI bayrakları yazısında bulabilirsiniz.

Jest gibi bir çatıdan geliyorsanız describe/it yapısı tanıdık gelecektir. Jest'in kendi özellikleri için Jest unit testing rehberimize bakabilirsiniz; bu yazı yalnızca Node.js'in yerleşik çalıştırıcısını anlatıyor.

Sık yapılan hatalar

• Alt testleri beklememek: t.test() çağrısının önüne await yazmazsanız üst test önce biter ve alt test iptal edilir.
• Glob kalıbını tırnaksız yazmak: kabuk kalıbı kendisi genişletebilir; Node.js belgeleri kalıpları çift tırnak içinde vermeyi önerir.
• Gevşek assert kullanmak: node:assert içindeki eski gevşek karşılaştırmalar yerine node:assert/strict içe aktarın.
• t.skip() sonrasında return unutmak: çağrı testi yalnızca işaretler, kodun geri kalanı çalışmaya devam eder.
• only bayrağını unutmak: { only: true } tek başına etkisizdir, --test-only ile başlatmalısınız.
• Rapor metnini ayrıştırmak: spec veya tap çıktısı sürümler arasında değişebilir; programla okumak için TestsStream olaylarını kullanın.
• Testten sonra çalışan asenkron iş bırakmak: test bittikten sonra oluşan alt testler başarısız sayılır, yakalanmamış hatalar da üst düzey uyarı olarak raporlanır.

Sık Sorulan Sorular

node:test kullanmak için bir şey kurmam gerekir mi?

Hayır. Modül Node.js ile birlikte gelir ve node: önekiyle içe aktarılır. Belgelerde kararlı olarak işaretlidir; yine de watch modu, kapsam ve etiketler gibi bazı alt özellikler deneysel ya da erken geliştirme aşamasındadır.

describe/it mi, test() mi kullanmalıyım?

İkisi de aynı motoru kullanır. Gruplamak istediğiniz çok sayıda test varsa describe/it okunaklıdır. Testleri bir döngüyle dinamik olarak üretecekseniz Learn rehberi test() ile t.test() kullanmanızı söyler.

Testler paralel mi çalışır?

Dosyalar varsayılan olarak ayrı süreçlerde ve aynı anda birden fazla çalışır. Bir dosyanın içindeki testler ise tek iş parçacığında çalışır; aynı dosyadaki asenkron testlerin eş zamanlılığını concurrency seçeneği belirler, varsayılanı false değeridir.

Test çıktısını CI aracına nasıl veririm?

--test-reporter=junit ve --test-reporter-destination=rapor.xml ile jUnit XML üretebilirsiniz. Kapsam için lcov raporlayıcısı vardır; ayrıntıları mock ve coverage yazısında anlattık.

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 · Mock ve coverage · Node.js debug · Çıkış kodları · Jest rehberi · JavaScript öğrenme rehberi