Apidog CLI API Testleri CircleCI'da Nasıl Çalıştırılır

CircleCI'da Apidog CLI API testlerini çalıştırmak için deponuza .circleci/config.yml ekleyin, cimg/node Docker yürütücüsünü kullanın, apidog-cli paketini npm ile yükleyin ve apidog run komutunu erişim token'ı, test senaryosu kimliği ve ortam kimliği ile çalıştırın. Token ve kimlikleri CircleCI ortam değişkenlerinde saklayın; JUnit ve HTML raporlarını store_test_results ve store_artifacts ile yayınlayın.

Apidog'u bugün deneyin

Bu rehber CI platformu seçimiyle değil, Apidog API testlerini CircleCI içinde çalıştırmakla ilgilidir. Hâlâ araçlar arasında karar veriyorsanız, CircleCI vs Jenkins karşılaştırması bu konuyu ele alır. Burada CircleCI'ı seçtiğinizi ve her push'ta API test süitinizin çalışmasını istediğinizi varsayıyoruz.

CircleCI Nedir ve Nasıl Çalışır?

CircleCI, Git deponuza bağlanan bulut tabanlı bir CI/CD platformudur. Bir commit gönderildiğinde deponuzdaki .circleci/config.yml dosyasını okur ve tanımladığınız işleri çalıştırır.

Temel yapı şu üç parçadan oluşur:

• Jobs: Test, derleme veya dağıtım gibi iş birimleri.
• Steps: Bir job içinde sırasıyla çalışan komutlar.
• Executors: Job'ın çalışacağı ortam. Bu rehberde Node.js için cimg/node Docker imajını kullanacağız.
• Workflows: Job'ların hangi sırayla ve hangi koşullarda çalışacağını belirler.

API testi için yapı basittir: Apidog CLI'yi yükleyen bir job tanımlarsınız, bu job içinde test senaryosunu çalıştırırsınız ve raporları CircleCI'a yüklersiniz.

Neden CircleCI'da API Testleri Çalıştırmalısınız?

API testlerini CI pipeline'ına eklemek, sözleşme bozulmalarını üretime gitmeden önce yakalamanızı sağlar. Örneğin:

• Yanıt şeması değiştiyse,
• Bir alan adı değiştirildiyse,
• Kimlik doğrulama akışı bozulduysa,
• Beklenen status code dönmüyorsa,

CircleCI build'i başarısız olur ve problem erken görünür hale gelir.

Apidog CLI, Apidog içinde oluşturduğunuz test senaryolarını CI ortamında komut satırından çalıştırmak için kullanılır. Testleri Apidog arayüzünde tasarlar, assertion'ları tanımlar ve aynı senaryoyu CircleCI'da headless olarak çalıştırırsınız.

CI/CD içinde API testlerinin nasıl konumlanacağını daha geniş görmek için API testi için 12 CI/CD en iyi uygulamaları rehberine bakabilirsiniz.

Ön Koşullar

Başlamadan önce Apidog ve CircleCI tarafında şu bilgileri hazırlayın:

• Apidog erişim token'ı: Apidog hesap ayarlarınızdan oluşturun. CLI bu token ile kimlik doğrulaması yapar. Ayrıntılar için Apidog CLI kimlik doğrulama rehberi.
• Test senaryosu kimliği: Çalıştırmak istediğiniz test senaryosunun ID'si.
• Ortam kimliği: CLI'nin hangi base URL ve değişken setiyle çalışacağını belirler.
• CircleCI projesi: GitHub, GitLab veya Bitbucket deponuz CircleCI'a bağlanmış olmalı.

Gizli Değerleri CircleCI Ortam Değişkenlerinde Saklayın

Apidog token'ınızı asla .circleci/config.yml içine yazmayın. Bu dosya Git'e commit edildiği için token sızabilir.

CircleCI'da üç değişken tanımlayın:

APIDOG_ACCESS_TOKEN
APIDOG_TEST_SCENARIO_ID
APIDOG_ENVIRONMENT_ID

Bunları eklemek için:

1. CircleCI panelinde projenizi açın.
2. Project Settings bölümüne gidin.
3. Environment Variables sekmesini açın.
4. Yukarıdaki değişkenleri ekleyin.

Birden fazla depo aynı token'ı kullanıyorsa, proje değişkenleri yerine Contexts kullanabilirsiniz. Context'ler organizasyon seviyesinde paylaşılan güvenli değişken gruplarıdır.

Tam .circleci/config.yml

Aşağıdaki yapılandırmayı .circleci/config.yml dosyasına ekleyin:

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

Bu config şunları yapar:

1. Node.js içeren cimg/node:20.11 imajını başlatır.
2. Depoyu checkout eder.
3. apidog-cli paketini global olarak yükler.
4. Apidog test senaryosunu çalıştırır.
5. JUnit ve HTML raporlarını ./reports dizinine yazar.
6. Test sonuçlarını ve artifact'leri CircleCI arayüzünde yayınlar.

Config Parçaları Nasıl Çalışır?

Docker yürütücüsü

docker:
  - image: cimg/node:20.11

cimg/node, CircleCI'ın Node.js için sağladığı hazır Docker imajıdır. Node, npm ve yaygın build araçları yüklü gelir. Bu sayede ek kurulum yapmadan şunu çalıştırabilirsiniz:

npm install -g apidog-cli

20.11 etiketi Node sürümünü sabitler. Ekibiniz farklı bir Node sürümünü standartlaştırdıysa etiketi buna göre değiştirin.

Apidog CLI kurulumu

- run:
    name: Install Apidog CLI
    command: npm install -g apidog-cli

Bu adım Apidog CLI'yi job ortamına yükler. CircleCI job'ları izole çalıştığı için bu kurulum her pipeline çalışmasında yeniden yapılır.

API testlerini çalıştırma

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  -r cli,junit,html \
  --out-dir ./reports

Bayrakların görevi:

• --access-token: Apidog CLI kimlik doğrulaması için kullanılır.
• -t: Çalıştırılacak test senaryosu ID'sini belirtir.
• -e: Kullanılacak ortam ID'sini belirtir.
• -r: Rapor formatlarını seçer.
  • cli: Sonuçları CircleCI log'una yazar.
  • junit: CircleCI'ın test sonucu olarak okuyabileceği XML üretir.
  • html: İncelenebilir HTML raporu üretir.
• --out-dir: Raporların yazılacağı dizini belirtir.

Raporları CircleCI'da Yayınlama

- store_test_results:
    path: ./reports

- store_artifacts:
    path: ./reports

store_test_results, CircleCI'a ./reports içindeki JUnit XML dosyalarını okumasını söyler. Böylece build sayfasında test sonuçlarını yapılandırılmış şekilde görebilirsiniz.

store_artifacts, aynı dizindeki HTML raporlarını indirilebilir artifact olarak yükler. Build tamamlandıktan sonra Artifacts sekmesinden HTML raporunu açabilirsiniz.

Apidog rapor formatları hakkında daha fazla bilgi için Apidog CLI test raporları rehberi kullanılabilir.

Testleri Sadece Belirli Branch'lerde Çalıştırma

Her feature branch için tam API testi çalıştırmak istemeyebilirsiniz. Örneğin sadece main ve develop branch'lerinde çalıştırmak için workflow'a branch filtresi ekleyin:

workflows:
  test-api:
    jobs:
      - api-tests:
          filters:
            branches:
              only:
                - main
                - develop

Bu yapılandırmadan sonra api-tests job'ı sadece main ve develop branch'lerine yapılan push'larda çalışır.

Project Variables Yerine Context Kullanma

Birden fazla depo aynı Apidog token'ını kullanıyorsa, değişkenleri her projeye ayrı ayrı eklemek yerine CircleCI Context kullanabilirsiniz.

Örnek:

workflows:
  test-api:
    jobs:
      - api-tests:
          context:
            - apidog-secrets

Bu durumda APIDOG_ACCESS_TOKEN, APIDOG_TEST_SCENARIO_ID ve APIDOG_ENVIRONMENT_ID değişkenleri apidog-secrets context'i içinden okunur.

Token rotasyonu gerektiğinde tek bir context'i güncellemeniz yeterlidir.

Veri Odaklı Test Çalıştırma

Apidog CLI, test senaryosunu CSV veya JSON verileriyle birden fazla kez çalıştırabilir.

Örnek:

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

Burada -d bayrağı veri dosyasını belirtir. CSV veya JSON dosyası kullanabilirsiniz. Ayrıca sayısal bir depolanmış veri kümesi ID'si de verilebilir.

Veri dosyalarının nasıl hazırlanacağını görmek için veri odaklı test rehberi incelenebilir.

Hata Davranışını Kontrol Etme

Apidog CLI çalıştırmasında hata olduğunda nasıl devam edileceğini --on-error ile belirleyebilirsiniz.

Örnek:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  --on-error end \
  -r cli,junit,html \
  --out-dir ./reports

Desteklenen değerler:

• continue
• end
• ignore

Apidog branch kullanan projelerde belirli bir branch'i hedeflemek için şu bayrakları da ekleyebilirsiniz:

--project <id> --branch <name>

Rapor özetini Apidog bulutuna göndermek için:

--upload-report

Apidog ve CircleCI İş Akışı Nasıl Ayrılır?

Bu kurulumda sorumluluklar nettir:

• Apidog: Test senaryolarını, assertion'ları, ortamları ve değişkenleri yönetir.
• CircleCI: Testlerin ne zaman ve hangi ortamda çalışacağını yönetir.

Bir test senaryosunu Apidog içinde görsel test oluşturucuyla veya komut satırından hazırlarsınız. CircleCI yalnızca bu senaryoyu apidog run ile tetikler.

Bu yaklaşımın avantajı, CI config dosyasının sık değişmemesidir. Bir assertion eklendiğinde veya test adımı güncellendiğinde, bu değişiklik Apidog projesinde yapılır ve bir sonraki CircleCI çalışması otomatik olarak güncel senaryoyu kullanır.

CircleCI'ı diğer CI araçlarıyla karşılaştırmak isterseniz, API ekipleri için sürekli entegrasyon araçları özeti faydalı olabilir.

API testlerinizi her push'ta çalıştırmaya başlamak için Apidog'u indirin, bir test senaryosu oluşturun ve yukarıdaki CircleCI config'ini deponuza ekleyin.

Sıkça Sorulan Sorular

CircleCI Nedir?

CircleCI, Git deponuza bağlanan bulut tabanlı bir sürekli entegrasyon ve dağıtım platformudur. .circleci/config.yml dosyasını okuyarak build, test ve dağıtım adımlarını otomatik çalıştırır.

CircleCI Ne İçin Kullanılır?

CircleCI; kod derleme, test çalıştırma, API sözleşmelerini kontrol etme, Docker imajı oluşturma ve dağıtım süreçlerini otomatikleştirmek için kullanılır. Bu rehberde CircleCI, her push'ta Apidog CLI API testlerini çalıştırmak için kullanıldı.

CircleCI Ücretsiz mi?

CircleCI, küçük projeler ve kişisel depolar için ücretsiz plan sunar. Daha fazla eşzamanlılık, daha uzun çalışma süresi veya daha büyük makineler için ücretli planlar gerekir. Güncel limitler için CircleCI fiyatlandırma sayfasını kontrol edin.

CircleCI Açık Kaynaklı mı?

Hayır. CircleCI ticari ve barındırılan bir CI/CD ürünüdür. YAML dosyasıyla yapılandırılır ve CircleCI altyapısında veya self-hosted runner üzerinde çalışabilir. Açık kaynaklı bir CI sunucusu arıyorsanız Jenkins yaygın bir alternatiftir.

CircleCI Nasıl Çalışır?

Bir commit gönderildiğinde CircleCI değişikliği algılar, .circleci/config.yml dosyasını okur, tanımlanan yürütücüyü başlatır ve job adımlarını sırasıyla çalıştırır. Sonuçları Git sağlayıcınıza geri bildirir. CI/CD kavramlarını daha genel görmek için CI/CD Nedir rehberine bakabilirsiniz.