Newman ile Postman Koleksiyonlarını CI/CD Hattına Bağlama

Newman nedir ve neden CI/CD'de gerekir?

Newman, Postman koleksiyonlarını arayüz olmadan komut satırından çalıştıran araçtır. Postman'de elle gönderdiğiniz istekler ve yazdığınız test betikleri, Newman ile aynen çalışır; fark, çalıştırmanın bir sunucuda, bir ardışık düzenin (pipeline) adımı olarak otomatik yapılmasıdır.

CI/CD hattında amaç, kod her değiştiğinde API sözleşmesinin bozulmadığını insan müdahalesi olmadan görmektir. Newman, test başarısız olduğunda sıfır olmayan çıkış koduyla biter ve hat bu adımda kırılır. Yani koleksiyonunuz yalnız bir el aracı olmaktan çıkar, derlemeyi durdurabilen bir kalite kapısına dönüşür.

Adım adım: kurulum ve ilk çalıştırma

Newman, Node üzerinde çalışır ve npm ile kurulur:

npm install -g newman

Koleksiyonu Postman'den JSON olarak dışa aktarın (ya da bulut adresiyle çağırın) ve temel komutu çalıştırın:

newman run koleksiyon.json

Çoğu gerçek senaryoda ortam dosyası da verilir. Newman README'sine göre -e seçeneği ortam dosyasını, -g global değişken dosyasını, -d veri dosyasını (JSON ya da CSV) ve -n tekrar sayısını belirler:

newman run koleksiyon.json -e hazirlik.postman_environment.json

Newman'in hangi ortamda çalıştığını açıkça seçmek önemlidir; hattın üretime değil, hazırlık ortamına gitmesi sağlanmalıdır.

Sık kullanılan seçenekler

Resmî README'de sıralanan, günlük işte en çok işe yarayan seçenekler:

• -e, --environment: Ortam değişkenlerini dosyadan ya da adresten yükler.
• -g, --globals: Global değişkenleri yükler. Aynı adlı ortam değişkeni önceliklidir.
• -d, --iteration-data: Her satırı bir tekrar olan JSON ya da CSV veri dosyası.
• -n, --iteration-count: Koleksiyonun kaç kez çalışacağı; genelde veri dosyasıyla kullanılır.
• --folder: Yalnız belirtilen klasörü ya da isteği çalıştırır; bayrak tekrarlanarak birden fazla klasör seçilir. Hızlı duman testi için kullanışlıdır.
• --bail: İlk test betiği hatasında koleksiyonu durdurur; folder ve failure değiştiricileri alır.
• --env-var: Komut satırından anahtar=değer biçiminde ortam değişkeni verir; hattın gizli değer deposundaki parolayı dosyaya yazmadan aktarmak için idealdir.
• -r, --reporters: Raporlayıcıyı seçer: cli, json, junit, progress. Virgülle, boşluksuz yazılır.
• --reporter-junit-export: JUnit XML çıktısının yazılacağı yolu belirler.
• -x, --suppress-exit-code: Çıkış kodunu bastırır; hattın kırılmasını istemediğiniz keşif çalıştırmalarında kullanılır.

Rapor üretme ve hat sonucuna bağlama

Hat içinde konsol çıktısı yetmez; sonucun test raporu olarak görünmesi gerekir. En yaygın çözüm JUnit biçimidir, çünkü neredeyse tüm CI araçları bu XML'i okuyup test sonuçları sekmesinde gösterir:

newman run koleksiyon.json -e hazirlik.postman_environment.json -r cli,junit --reporter-junit-export sonuclar/api-testleri.xml

README'ye göre başka bir raporlayıcıyı etkinleştirince konsol çıktısı kapanır; cli'yi listede açıkça yazmazsanız satır satır sonucu görmezsiniz. Bu yüzden komutta cli ve junit birlikte verilir.

Parolayı dosyaya yazmak yerine hattın gizli değer deposundan --env-var ile geçirin:

newman run koleksiyon.json -e hazirlik.postman_environment.json --env-var "parola=$API_PAROLA"

Hat adımı, Newman sıfır olmayan çıkış koduyla bitince kırılır. Bu varsayılan davranış, kalite kapısının kendisidir; bastırmayın.

Hat yerleşimi: hangi aşamada, hangi ortama?

Newman testlerini her aşamaya koymayın. Mantıklı bir yerleşim şöyledir:

• Kod birleştirme isteğinde: hızlı bir duman testi koleksiyonu (--folder ile seçilen kritik uç noktalar). Amaç, geliştiriciye hızlı geri bildirim vermek.
• Hazırlık ortamına dağıtımdan sonra: tam koleksiyon, veri dosyalarıyla. Amaç, yayın öncesi sözleşme güvencesi.
• Üretime dağıtımdan sonra: yalnız okuma yapan, yan etkisiz küçük bir sağlık kontrolü koleksiyonu. Üretimde veri oluşturan test çalıştırmayın.
• Zamanlanmış çalıştırma: gece, harici bağımlılıkları da kapsayan geniş koleksiyon.

Bu hattın çalışması için koleksiyonun ortamdan bağımsız yazılmış olması gerekir: temel adres ve kimlik bilgileri ortam değişkenlerinden okunmalı, testler birbirinden bağımsız ya da sırası açık biçimde kurulmalıdır. Aksi halde yerelde geçen test hatta düşer.

Bir hazırlık ortamı işi tipik olarak şu adımlardan oluşur: kodu çek, bağımlılıkları kur, Newman'i kur, hizmetin ayağa kalkmasını bekle, koleksiyonu ortam dosyasıyla çalıştır, JUnit raporunu hattın test sekmesine yayınla, hata varsa adımı kır ve ekibi bilgilendir. Hizmetin hazır olmasını beklemek, dağıtımdan hemen sonra çalışan testlerin rastlantısal düşmesini önleyen küçük ama önemli bir adımdır. Raporu ve konsol çıktısını saklamak, sonradan hata araştırmasında zaman kazandırır.

Sık karşılaşılan sorunlar ve çözümleri

• Test yerelde geçiyor, hatta düşüyor: Hattın erişebildiği bir adres kullanıldığından, ortam dosyasının güncel olduğundan ve gizli değerlerin hatta tanımlı olduğundan emin olun.
• Sertifika ve ağ hataları: Hazırlık ortamının sertifikası, hat çalıştırıcısının ağı ve güvenlik duvarı kuralları kontrol edilmelidir; sertifika doğrulamasını kapatmak yerine sertifikayı hatta tanıtın.
• Veri çakışması: Paralel çalışan hatlar aynı kayıtla oluşturma yapıyorsa testler birbirini bozar. Her çalıştırmada benzersiz veri üretin, sonunda temizleyin.
• Kararsız (flaky) testler: Gecikmeli yanıta bağımlı doğrulamalar rastlantısal düşer. Zaman aşımı değerlerini ortamdan ayarlayın, yeniden deneme mantığını koleksiyona değil hat politikasına koyun.
• Rapor görünmüyor: JUnit dosyasının yolunu ve hattın rapor toplama adımını kontrol edin; cli raporlayıcısını yazmayı unutmayın.
• Büyük koleksiyon yavaş: Klasörleri ayırıp paralel işlere bölün; duman ve tam koleksiyon ayrımını koruyun.

Bu becerinin Mindset programlarındaki yeri

Postman ile API Testi programındaki Newman ile CI/CD Entegrasyonu modülü bu bağlamayı işler; Postman Koleksiyonu ve Ortam Yönetimi ile Test Betimleri ve Doğrulama modülleri ise onun gerektirdiği altyapıyı sağlar. Mock Server ve API Simülasyonu modülü, bağımlı servis hazır olmadığında hattın düşmesini önleyen sahte yanıtları kapsar.

Program, test otomasyonu ve DevOps sorumluluğu taşıyan mühendisler, API geliştiren ekipler ve manuel kontrolden sürekli entegrasyona geçmek isteyen kurumsal kalite birimleri için uygundur.