CircleCI'da Apidog CLI API testlerini çalıştırmak için, cimg/node Docker yürütücüsünü kullanan, apidog-cli'yi npm ile yükleyen ve erişim token'ınız, test senaryosu kimliğiniz ve ortam kimliğinizle apidog run komutunu çalıştıran bir .circleci/config.yml dosyası ekleyin. Token ve kimlikleri CircleCI ortam değişkenleri olarak saklayın, ardından JUnit ve HTML raporlarını store_test_results ve store_artifacts ile yayınlayın. Bu rehber, kopyalayıp yapıştırabileceğiniz ve kullanabileceğiniz her bir parçayı adım adım açıklar.
Bu makale, bir CI platformu seçmekten ziyade testleri çalıştırmakla ilgilidir. Hala araçlar arasında karar veriyorsanız, CircleCI vs Jenkins karşılaştırması bu konuyu ele alır. Burada, zaten CircleCI'ı seçtiğinizi ve her push'ta API süitinizin çalışmasını istediğinizi varsayıyoruz.
CircleCI Nedir ve Nasıl Çalışır?
CircleCI, bulut tabanlı bir sürekli entegrasyon ve dağıtım hizmetidir. Git deponuzu izler ve bir commit gönderdiğinizde, tanımladığınız derleme, test ve dağıtım adımlarını çalıştırır. Bu adımları tek bir YAML dosyasında açıklarsınız, böylece pipeline'ınız kodunuzla birlikte versiyon kontrolünde yaşar.
Her şey, deponuzun kökündeki .circleci/config.yml ile başlar. CircleCI, her push'ta bu dosyayı okur ve bir pipeline'a dönüştürür. Mevcut config formatı 2.1 sürümüdür, bu sürüm temel 2.0 motorunun üzerine orblar, komutlar ve parametreler gibi yeniden kullanılabilir yapı taşları ekler.
Bir CircleCI config'i üç temel kavrama sahiptir:
- İşler (Jobs) iş birimleridir. Her iş, kodu çekme, bağımlılıkları yükleme veya bir test komutu çalıştırma gibi bir dizi adım (steps) çalıştırır.
- Yürütücüler (Executors) bir işin nerede çalışacağını tanımlar. Bir Docker yürütücüsü, Node.js projeleri için
cimg/nodegibi seçtiğiniz bir container görüntüsü içinde adımlarınızı çalıştırır. - İş Akışları (Workflows) işleri düzenler. Bir iş akışı, hangi işlerin hangi sırayla çalışacağına ve paralel mi yoksa sıralı mı çalışacaklarına karar verir.
Bu ayrım, API testi için önemlidir. Apidog CLI'yi yükleyen ve senaryolarınızı çalıştıran bir iş tanımlarsınız, ardından önem verdiğiniz branch'lerde bu işi tetikleyen bir iş akışı oluşturursunuz.
Neden CircleCI'da API Testleri Çalıştırılmalı?
API süitinizi CI'da çalıştırmak, sözleşme ihlallerini üretime ulaşmadan önce yakalar. Bir şema değişikliği, yeniden adlandırılmış bir alan veya bozuk bir kimlik doğrulama akışı, bir destek bileti yerine kırmızı bir derleme olarak kendini gösterir.
Apidog CLI tam da bunun için yapılmıştır. Bir test senaryosunu Apidog uygulamasında tasarlar ve hata ayıklamasını yapar, ardından aynı senaryoyu CI'da tek bir komutla başsız (headless) olarak çalıştırırsınız. Kodda yeniden onay yazmaya gerek kalmaz ve ayrıca bir test donanımı sürdürmek zorunda kalmazsınız.
Otomatik kontrollerin bir pipeline'a nasıl uyduğuna dair daha geniş bir resim istiyorsanız, API testi için 12 CI/CD en iyi uygulamaları rehberi iyi bir ek okumadır.
Ön Koşullar
Yapılandırmayı yazmadan önce, Apidog uygulamasında şunları hazırlayın:
- Bir erişim token'ı. Apidog hesap ayarlarınızdan oluşturun. Bu, CLI'yi başsız ortamlarda doğrular. Apidog CLI kimlik doğrulama rehberi, token oluşturma ve CI gizli anahtar yönetimini ayrıntılı olarak açıklar.
- Bir test senaryosu kimliği. Çalıştırmak istediğiniz test senaryosunu açın ve URL'den veya senaryo ayarlarından kimliğini kopyalayın.
- Bir ortam kimliği. Bu, CLI'ye hangi temel URL'yi ve değişkenleri (örneğin hazırlık veya üretim) kullanacağını söyler.
Ayrıca, projenin CircleCI kontrol panelinde etkinleştirilmiş, Git sağlayıcınıza bağlı bir CircleCI hesabına ihtiyacınız olacaktır.
Gizli Anahtarları Ortam Değişkenleri Olarak Saklayın
Erişim token'ınızı asla config.yml'e sabit kodlamayın. Dosya Git'e commit edildiği için, oradaki bir token sızdırılmış bir token demektir.
CircleCI size iki güvenli seçenek sunar:
- Proje ortam değişkenleri. CircleCI UI'da Proje Ayarları'nı, ardından Ortam Değişkenleri'ni açın ve her değeri ekleyin. Bunlar şifrelenir ve işlere
$VARSolarak sunulur. - Bağlamlar (Contexts). Bir bağlam, projeler arasında paylaşılan adlandırılmış bir ortam değişkenleri grubudur. Bunu Organizasyon Ayarları'ndan, ardından Bağlamlar'dan oluşturur ve bir iş akışından referans verirsiniz. Bağlamlar, birden fazla deponun aynı Apidog token'ını paylaştığı durumlarda kullanışlıdır.
Bu rehber için üç değişken ekleyin: APIDOG_ACCESS_TOKEN, APIDOG_TEST_SCENARIO_ID ve APIDOG_ENVIRONMENT_ID. CLI bunları çalışma zamanında okur ve hiçbir hassas bilgi deponuzda yaşamaz.
Tam config.yml
İşte eksiksiz, kopyalayıp yapıştırabileceğiniz bir config. Bunu .circleci/config.yml adresine bırakın, üç ortam değişkeninizi ayarlayın ve push yapın.
version: 2.1
jobs:
api-tests:
docker:
- image: cimg/node:20.11
steps:
- checkout
- run:
name: Install Apidog CLI
command: npm install -g apidog-cli
- run:
name: Run Apidog API tests
command: |
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t $APIDOG_TEST_SCENARIO_ID \
-e $APIDOG_ENVIRONMENT_ID \
-r cli,junit,html \
--out-dir ./reports
- store_test_results:
path: ./reports
- store_artifacts:
path: ./reports
workflows:
test-api:
jobs:
- api-tests
Her bir parçanın ne işe yaradığını açıklayayım.
Yürütücü
docker:
- image: cimg/node:20.11
cimg/node, CircleCI'ın Node.js için kolaylık sağlayan görüntüsüdür. Node, npm ve yaygın derleme araçları önceden yüklü olarak gelir, böylece npm install -g apidog-cli ek kurulum olmadan çalışır. :20.11 etiketi bir Node sürümünü sabitler; ekibinizin standartlaştırdığı sürüme sabitleyin.
Adımlar
checkout, deponuzu işin çalışma dizinine çeker. İlk run adımı CLI'yi global olarak yükler. İkinci run adımı testlerinizi çalıştırır.
Test komutuna yakından bakalım:
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t $APIDOG_TEST_SCENARIO_ID \
-e $APIDOG_ENVIRONMENT_ID \
-r cli,junit,html \
--out-dir ./reports
Her bayrak tek bir iş yapar:
--access-tokençalıştırmayı doğrular. Kısa formu yoktur.-t, test senaryosunu kimliğine göre seçer.-eortamı seçer. Bu bayrak zorunludur; CLI hangi temel URL'yi ve değişkenleri kullanacağını bilmelidir.-rraporlayıcıları ayarlar. Burada üç tane istersiniz:clicanlı sonuçları derleme günlüğüne yazdırır,junitmakine tarafından okunabilen XML yazar vehtmlgezilebilir bir rapor yazar.--out-dir, CLI'ye rapor dosyalarını nereye yazacağını söyler.
Raporları Yayınlama
- store_test_results:
path: ./reports
- store_artifacts:
path: ./reports
store_test_results, CircleCI'yı ./reports içindeki JUnit XML'e yönlendirir. CircleCI bunu ayrıştırır ve derleme üzerinde bir Testler sekmesi gösterir, böylece hatalar zamanlama verileriyle birlikte adlarıyla listelenir. Bu, bir günlük metni duvarını yapılandırılmış bir geçiş/başarısız görünümüne dönüştüren şeydir.
store_artifacts, HTML raporu da dahil olmak üzere aynı dizini indirilebilir dosyalar olarak yükler. Bir derlemeden sonra, Artifacts sekmesini açar ve işlenmiş raporu tarayıcınızda görüntülersiniz. Apidog CLI test raporları rehberi, CLI, HTML ve JSON formatlarını daha ayrıntılı olarak açıklar.
İş Akışı
workflows:
test-api:
jobs:
- api-tests
Bu iş akışı, her push'ta api-tests işini çalıştırır. Belirli branch'lerle sınırlamak için filtreler ekleyebilir veya ondan önce veya sonra çalışan başka işler ekleyebilirsiniz. Tek bir test işi için bu minimal blok ihtiyacınız olan her şeydir.
Testleri Sadece Ana Branch'te Çalıştırın
Her özellik branch'inde tam bir API çalıştırması istemeyebilirsiniz. İş akışına bir branch filtresi ekleyin:
workflows:
test-api:
jobs:
- api-tests:
filters:
branches:
only:
- main
- develop
Artık iş sadece main ve develop branch'lerine yapılan push'larda çalışır. Diğer branch'ler bunu atlar, bu da derleme sürelerinizi yayınlanan branch'lere odaklanmış tutar.
Proje Değişkenleri Yerine Bir Bağlam Kullanın
Birden fazla depo tek bir Apidog token'ını paylaşıyorsa, bir Bağlam bunu tek bir yerde tutar. Bağlam'ı Organizasyon Ayarları'nda oluşturun, değişkenlerinizi oraya ekleyin, ardından ona referans verin:
workflows:
test-api:
jobs:
- api-tests:
context:
- apidog-secrets
İş artık APIDOG_ACCESS_TOKEN ve diğerlerini apidog-secrets Bağlamından okur. Token'ı bir kez döndürün ve her proje yeni değeri alır.
Veri Odaklı Çalıştırmalar ve Diğer Seçenekler
CLI'nin bu rehberde kullanılanlardan daha fazla bayrağı vardır. CI için bilinmesi gereken iki tanesi şunlardır:
Bir senaryoyu -d ve -n ile test verisi satırları arasında tekrarlayabilirsiniz:
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t $APIDOG_TEST_SCENARIO_ID \
-e $APIDOG_ENVIRONMENT_ID \
-d ./data/users.csv \
-r cli,junit \
--out-dir ./reports
-d bayrağı bir CSV veya JSON dosya yolu veya sayısal bir depolanmış veri kümesi kimliği alır ve senaryoyu her satır için bir kez çalıştırır. Veri odaklı test rehberi, bu dosyaların nasıl yapılandırılacağını gösterir.
Ayrıca, çalıştırmanın hataları nasıl ele aldığını continue, end veya ignore kabul eden --on-error ile kontrol edebilirsiniz. Ve Apidog branch'lerini kullanan projeler için --project <id> --branch <name> belirli bir branch'i hedefler. Bir rapor özetini Apidog bulutuna göndermek için, çıplak bir bayrak olarak --upload-report ekleyin.
Bunun Apidog İş Akışına Nasıl Uygun Olduğu
Apidog CLI'nin amacı, test kodu yazmamanız veya sürdürmemenizdir. Bir komut satırından veya görsel test oluşturucudan bir test senaryosu oluşturur, durum kodları ve yanıt gövdeleri üzerinde iddialar (assertions) ayarlar ve kaydedersiniz. CI daha sonra bu senaryoyu tam olarak çalıştırır.
Senaryo Apidog projenizde yaşadığı için, ekibiniz testleri tek bir yerde düzenler. CI config'i nadiren değişir; sadece apidog run komutunu çağırır. Birisi uygulamada bir assertion eklediğinde, bir sonraki CircleCI derlemesi hiçbir YAML düzenlemesi olmadan bunu alır.
Bu temiz bir ayrımı korur. Apidog neyin test edileceğini yönetir. CircleCI ne zaman ve nerede çalışacağını yönetir. Bu tür işler için CircleCI'yı diğer koşucularla karşılaştırmak isterseniz, API ekipleri için sürekli entegrasyon araçları özeti, avantajları ve dezavantajları ortaya koyar.
API süitinizi her push'ta çalıştırmaya hazır mısınız? Apidog'u indirin, bir test senaryosu oluşturun ve yukarıdaki config'i deponuza bırakın.
Sıkça Sorulan Sorular
CircleCI Nedir?
CircleCI, bir bulut tabanlı sürekli entegrasyon ve dağıtım platformudur. Git deponuza bağlanır, bir .circleci/config.yml dosyasını okur ve her kod gönderdiğinizde otomatik olarak derleme, test ve dağıtım adımlarını çalıştırır. Kendi makinenizde bu adımları elle çalıştırma ihtiyacını ortadan kaldırır.
CircleCI Ne İçin Kullanılır?
Ekipler CircleCI'yı test ve dağıtımı otomatikleştirmek için kullanır. Yaygın işler arasında kodu derlemek, birim ve entegrasyon testlerini çalıştırmak, API sözleşmelerini kontrol etmek, Docker görüntüleri oluşturmak ve yayınları hazırlık veya üretim ortamlarına göndermek yer alır. Bu rehberde, iş her push'ta Apidog CLI API testlerini çalıştırır.
CircleCI Ücretsiz mi?
CircleCI'nin küçük projeler ve kişisel depolar için yeterli olan aylık bir derleme kredisi tahsisi içeren ücretsiz bir planı vardır. Daha fazla eşzamanlılık, daha uzun derleme süreleri veya daha büyük makineler isteyen daha büyük ekipler, ücretli Performans ve Ölçek planlarına geçer. Tam limitler için CircleCI'ın güncel fiyatlandırma sayfasını kontrol edin.
CircleCI Açık Kaynaklı mı?
Hayır, CircleCI ticari, barındırılan bir üründür, açık kaynak değildir. Onu bir YAML dosyası aracılığıyla yapılandırırsınız ve CircleCI'ın altyapısında veya kendi barındırdığınız bir koşucuda çalıştırırsınız. Tamamen açık kaynaklı bir CI sunucusuna ihtiyacınız varsa, Jenkins yaygın bir alternatiftir, ki bu CircleCI vs Jenkins karşılaştırmasında tartışılmaktadır.
CircleCI Nasıl Çalışır?
Bir commit gönderdiğinizde, CircleCI değişikliği algılar, .circleci/config.yml dosyasını okur ve cimg/node Docker container'ı gibi tanımladığınız yürütücüyü başlatır. İşlerinizdeki her adımı sırasıyla çalıştırır, ardından sonuçları Git sağlayıcınıza geri bildirir. İş akışları, işleri zincirlemenizi ve paralel hale getirmenizi sağlar. Bunun bir dağıtım pipeline'ına nasıl uyduğuna dair daha geniş bir resim için, CI/CD Nedir rehberine bakın.