Postman'de Koleksiyon ve Ortam Değişkenleri Nasıl Yönetilir?

Koleksiyon ve ortam: iki ayrı sorumluluk

Postman'de koleksiyon, istekleri bir araya getiren düzenli bir pakettir; ortam ise o isteklerin hangi sunucuya ve hangi değerlerle gideceğini belirleyen değişken kümesidir. İki yapıyı ayrı tutmak temel kuraldır: koleksiyon ne yapılacağını, ortam nerede yapılacağını söyler.

Bu ayrım yapılırsa aynı koleksiyon geliştirme, test, hazırlık ve üretim ortamında hiçbir istek değiştirilmeden çalışır. Ayrım yapılmazsa adresler isteklerin içine gömülür, ortam değiştikçe onlarca isteği elle düzeltmek gerekir ve hatalı ortama istek gönderme riski doğar.

Koleksiyonu klasörlerle ve kurallarla düzenleyin

İyi bir koleksiyon, ilk bakışta ne içerdiğini ve hangi sırada çalışacağını anlatır. Şu düzeni kullanın:

• Kaynağa göre klasörler: Kimlik doğrulama, kullanıcılar, siparişler, ödemeler gibi. Her klasörde önce başarılı senaryolar, sonra hata senaryoları gelsin.
• İsimlendirme kuralı: İstek adına yöntemi ve amacı yazın (örneğin kullanıcı oluştur, kullanıcıyı getir). İsteği adından anlayamayan biri koleksiyonu devralamaz.
• Açıklama alanları: Koleksiyonun, klasörün ve isteğin açıklamasına amaç, ön koşul ve beklenen sonucu yazın. Bu metinler yayınlanan belgelendirmenin de kaynağı olur.
• Üst düzeyde ortak ayarlar: Kimlik doğrulama ve ortak başlıkları koleksiyon ya da klasör düzeyinde tanımlayın, isteklerin üst kaynaktan devralmasını (inherit) sağlayın. Bir token değişirse tek yerde güncellersiniz.
• Örnek yanıtlar (examples): Başarılı ve hatalı yanıt örneklerini kaydedin; bunlar hem belgelendirme hem sahte sunucu (mock) için kullanılır.

Değişken kapsamları ve öncelik sırası

Postman resmî belgelerine göre değişkenler genelden dara doğru şu kapsamlarda tanımlanır: global, koleksiyon, ortam, veri ve yerel. Aynı ad birden fazla kapsamda varsa en dar kapsamdaki değer kullanılır; yani öncelik yerel, veri, ortam, koleksiyon, global sırasındadır.

Bu sıra pratikte şunu söyler:

• Global: Çalışma alanı genelinde paylaşılan değerler. Az kullanın; bağımlılık yaratır.
• Koleksiyon: Ortamdan bağımsız sabitler, örneğin API yol öneki ya da istek başlığı adı.
• Ortam: Ortama göre değişen değerler: temel adres, kullanıcı adı, istemci kimliği.
• Veri: Koleksiyon çalıştırıcısına verilen CSV ya da JSON dosyasından gelen satır değerleri; kalıcı olarak saklanmaz.
• Yerel: Tek bir istek ya da çalıştırma süresince geçerli geçici değerler.

Değişkeni isteklerde çift süslü parantezle çağırırsınız. Örneğin temel adres değişkeni olarak tanımladığınız bir değer, istek adresinin başına yazılır ve ortam değişince hedef sunucu kendiliğinden değişir.

Adım adım: ortam kurma ve token taşıma

Tipik bir kurulum şu adımlardan oluşur:

• Her hedef sunucu için ayrı bir ortam oluşturun ve aynı değişken adlarını kullanın: temel adres, kullanıcı adı, parola gibi. Adlar aynı, değerler farklı olmalıdır; koleksiyon ancak böyle ortam bağımsız çalışır.
• İstek adresini temel adres değişkeniyle yazın ve sağ üstten doğru ortamı seçin. Etkin ortamın adı her zaman ekranın görünür yerinde durur; üretim ortamı seçiliyken yazma isteği göndermeden önce bir kez daha bakın.
• Giriş isteğinin test betiğinde yanıttan token'ı alıp değişkene yazın. Örnek:

const govde = pm.response.json(); pm.environment.set("erisimToken", govde.token);

• Diğer isteklerin kimlik doğrulama sekmesinde bu değişkeni kullanın. Böylece her istekte token'ı elle kopyalamak gerekmez.
• Token süresi dolduğunda yenilenmesi gerekiyorsa koleksiyon düzeyinde bir ön istek betiği (pre-request script) ile süre kontrolü yapıp gerekirse giriş isteğini tekrarlatın.

Sırları paylaşmadan ekiple çalışmak

Postman, değişkenler için yerel değer ve paylaşılan değer ayrımı yapar. Yerel değer yalnızca sizin makinenizde kalır ve bulutla eşitlenmez; paylaşılan değer çalışma alanında eşitlenir ve zamanlanmış çalıştırmalar, izleme (monitor) ve komut satırı aracı tarafından kullanılır. Sır niteliğindeki bir değeri (parola, API anahtarı, istemci gizli anahtarı) paylaşılan değere yazmayın.

Resmî belgelerde sırlar için ayrıca kasa (Vault) özelliği anlatılır: hassas veri kasada tutulur, koleksiyon ve ortamlardan ayrı yönetilir. Ekipteki herkes kendi sırrını yerel olarak girer; ortak dosyada yalnızca değişken adı ve boş değer kalır. Koleksiyonu dışa aktarırken de gizli değer taşıyıp taşımadığını kontrol edin; depoya yüklenen bir dışa aktarım dosyası, sızıntının en yaygın yoludur.

Koleksiyon çalıştırıcısı ve veri dosyalarıyla çoklu senaryo

Koleksiyon çalıştırıcısı (collection runner), istekleri sırayla çalıştırır ve test sonuçlarını toplar. Aynı koleksiyonu farklı girdilerle koşturmak için CSV ya da JSON veri dosyası verirsiniz; dosyadaki her satır bir tekrar (iteration) olur ve sütun adları veri kapsamında değişken olarak kullanılır. Örneğin bir kullanıcı oluşturma isteğini farklı geçerli ve geçersiz kullanıcı kayıtlarıyla çalıştırabilirsiniz.

Çalıştırma sırası klasör ve istek sırasından gelir. Birbirine bağımlı istekleri (oluştur, getir, sil) aynı klasörde ve doğru sırada tutun; her isteğin kendi test betiği, bir sonraki istek için gerekli kimliği değişkene yazsın. Bu zinciri kuran yapı, daha sonra komut satırında Newman ile otomatik çalıştırılacak koleksiyonun temelidir.

Sık yapılan hatalar

• Temel adresi isteklerin içine yazmak; ortam değişince hepsini düzeltmek gerekir.
• Ortamlarda farklı değişken adları kullanmak; koleksiyon bir ortamda çalışır, diğerinde hata verir.
• Gerçek parolayı paylaşılan değere yazıp dışa aktarma dosyasını depoya koymak.
• Çok sayıda global değişken kullanmak; hangi isteğin hangi değere bağlı olduğunu kimse bilmez.
• Test sonrası değişkenleri temizlememek; eski bir kimlik sonraki çalıştırmayı bozar. Betikte pm.environment.unset ya da koleksiyon sonu temizliği kullanın.
• Etkin ortamı kontrol etmeden silme isteği göndermek.
• Koleksiyonun açıklamasız bırakılması; çalışma alanına yeni katılan biri başlangıç noktasını bulamaz.

Bu becerinin Mindset programlarındaki yeri

Postman ile API Testi programında Postman Koleksiyonu ve Ortam Yönetimi bir modül başlığıdır; API Testi Temelleri ve HTTP Protokolü modülünün üzerine kurulur ve sonraki Test Betikleri ile Doğrulama, Newman ile CI/CD Entegrasyonu ve Kimlik Doğrulama ve Güvenlik Testi modüllerinin altyapısını sağlar.

Program, test mühendisleri, API geliştiren yazılımcılar ve manuel testten otomasyona geçen kalite ekipleri için uygundur. Kurumsal ekiplerde ortak bir koleksiyon yapısı ve değişken sözleşmesi kurmak, testlerin kişiden bağımsız çalışmasını sağlar.