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

Apidog CLI API testlerini Drone CI'da, bir Node imajı kullanan, apidog-cli yükleyen ve bir ortama karşı apidog run komutunu çalıştıran bir Docker pipeline adımı ekleyerek çalıştırırsınız. Apidog erişim token'ınız bir Drone sırrında saklanır ve from_secret aracılığıyla enjekte edilir. Bu kılavuz, kopyala-yapıştır yapılabilecek bir .drone.yml dosyasını, sır yönetimi, dal kısıtlaması ve Drone'un yerleşik bir yapıt deposu olmadığı için test raporunu nasıl göstereceğinizi anlatır.

Drone CI Nedir ve Nasıl Çalışır?

Drone, artık Harness'ın bir parçası olan açık kaynaklı, konteyner tabanlı bir CI/CD platformudur. CI/CD, sürekli entegrasyon ve sürekli teslimat anlamına gelir; bu, her değişiklikte kodu otomatik olarak oluşturma ve test etme pratiğidir. Kavramın kendisi hakkında bir hatırlatma isterseniz, CI/CD nedir başlıklı makaleye bakınız.

Drone'un belirleyici özelliği basittir: her pipeline adımı kendi Docker konteyneri içinde çalışır. Önceden yüklenmiş araçların dağınık bir şekilde bulunduğu ortak bir derleme aracısı yoktur. Her adım için bir imaj seçersiniz ve Drone komutlarınızı onun içinde çalıştırır. Bu, derlemeleri tekrarlanabilir ve anlaşılması kolay hale getirir.

Bir pipeline'ı deponuzun kök dizinindeki bir .drone.yml dosyasında tanımlarsınız. Bir Docker pipeline'ı üç üst düzey anahtara sahiptir: kind, type ve name. İş, her adımın bir name, bir image ve bir commands listesi bildirdiği steps altında gerçekleşir.

kind: pipeline
type: docker
name: api-tests

steps:
  - name: greeting
    image: alpine
    commands:
      - echo hello
      - echo world

Drone, commands'ı set -e ve set -x ile bir kabuk betiği olarak çalıştırır, böylece derleme ilk sıfır olmayan çıkış kodunda hızla başarısız olur ve her komutu çalıştırmadan önce yansıtır. Komutlar, konteyner giriş noktasını geçersiz kılar ve çalışma dizini deponuzun köküdür.

API Testlerini Konteyner Adımında Neden Çalıştırmalısınız?

API testleri, sözleşme kaymasına karşı koruma sağlar. Bir yanıt şeklini veya durum kodunu sessizce değiştiren bir arka uç değişikliği, aşağı akıştaki her istemciyi bozabilir. Bu testleri her gönderimde çalıştırmak, regresyonu gönderilmeden önce yakalar.

Apidog bu modele çok iyi uyar. Testlerinizi görsel olarak Apidog uygulamasında oluşturur ve sürdürür, ardından Apidog CLI ile aynı test senaryolarını komut satırından çalıştırırsınız. Betik yeniden yazmaya veya ayrı bir test donanımına gerek yoktur. API testlerini pipeline'lara entegre etme konusunda daha geniş rehberlik için, API testi için CI/CD en iyi uygulamaları başlıklı makaleyi okuyun.

Apidog, tasarım, hata ayıklama, test etme, taklit etme ve dokümantasyon için hepsi bir arada bir API platformudur. CLI, kaydettiğiniz test senaryolarını tek ve tekrarlanabilir bir komuta dönüştüren parçadır ve tam olarak bir Drone adımının ihtiyacı olan şey budur.

Çalıştıracağınız Apidog CLI Komutu

CLI'yı npm ile yükleyin, ardından bir test senaryosu çalıştırın. CI'da, çalışmayı bayraklarla kaydedilmiş bir senaryoya yönlendirirsiniz, bu nedenle yönetilecek yerel bir koleksiyon dosyası yoktur.

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli

Her bayrağın ne işe yaradığı aşağıdadır:

--access-token Apidog erişim token'ınızı iletir. Kısa bir biçimi yoktur.
-t çalıştırmak istediğiniz test senaryosu kimliğidir.
-e ortam kimliğidir ve gereklidir. Bu, çalıştırmanın hangi temel URL'yi ve değişkenleri kullanacağını seçer.
-r raporlayıcıları listeler. Geçerli değerler cli, html, json ve junit'tir.

İhtiyaç duyuldukça daha fazla bayrak ekleyebilirsiniz:

-n veya --iteration-count çalıştırmayı belirli sayıda tekrarlar.
-d veya --iteration-data, veri odaklı çalıştırmalar için bir CSV veya JSON dosya yolu ya da sayısal depolanmış bir veri kümesi kimliği alır.
--out-dir rapor çıktı dizinini ayarlar.
--upload-report bir rapor özetini Apidog bulutuna gönderir ve bu rapordan uygulamada görüntülenebilir. Çıplak bir bayrak olarak kullanabilirsiniz.
--on-error, continue, end veya ignore ile hata davranışını kontrol eder.
--project <id> ve --branch <name> belirli bir proje dalını hedefler.

Komut ve seçeneklerinin tam bir turu için, Apidog CLI tam kılavuzuna ve komut satırından bir REST API'yi test etme konulu rehbere bakınız.

Apidog Testleri İçin Eksiksiz Bir .drone.yml

İşte çalışan bir pipeline. Bir Node imajı kullanır, CLI'yı yükler ve senaryonuzu çalıştırır. Token, hardcoded olmak yerine bir Drone sırrından gelir.

kind: pipeline
type: docker
name: apidog-api-tests

steps:
  - name: run-api-tests
    image: node:20-alpine
    environment:
      APIDOG_ACCESS_TOKEN:
        from_secret: apidog_access_token
    commands:
      - npm install -g apidog-cli
      - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli

trigger:
  branch:
    - main
  event:
    - push
    - pull_request

1234567'yi test senaryosu kimliğinizle ve 89012'yi ortam kimliğinizle değiştirin. Her ikisi de Apidog uygulamasında görünür. Adım cli raporlayıcısını kullandığı için, tam geçme/kalma dökümü doğrudan Drone derleme günlüğüne basılır ve derlemeyi inceleyen herkes bunu okuyabilir.

Drone CI'da Sırları Saklama

Asla bir API token'ını deponuza kaydetmeyin. Drone, sırları YAML'den uzak tutar ve çalışma zamanında enjekte eder.

Bir sırrı, bir adımın environment bloğu (veya bir eklentinin settings bloğu) içinde from_secret ile referans alırsınız. Yazdığınız değer, sırrın adı olmalı, token'ın kendisi değil.

environment:
  APIDOG_ACCESS_TOKEN:
    from_secret: apidog_access_token

Sırı oluşturmanın iki yaygın yolu vardır. Birincisi Drone UI'dır: deponuzu açın, Ayarlar'a, ardından Sırlar'a gidin ve değer olarak token'ınızı içeren apidog_access_token adında bir sır ekleyin. İkincisi ise Drone komut satırı aracıdır.

drone secret add \
  --repository your-org/your-repo \
  --name apidog_access_token \
  --data your-apidog-token

CLI bayrakları sürümler arasında değişebileceğinden, kesin bayrak adlarını sürümünüze ait Drone CLI belgelerinden doğrulayın. Drone ayrıca, drone encrypt komutunun ayrı bir kind: secret YAML belgesi olarak gömdüğünüz şifreli bir blok ürettiği bir depo içi şifreli sır varyantını da destekler. Çoğu ekip için, UI aracılığıyla veya drone secret add ile eklenen depo sırları daha basittir ve önerilen başlangıç noktasıdır.

Token'ı bir sırda tutmak, başka herhangi bir yerde uygulayacağınız aynı disiplindir. CLI'ın kimlik bilgilerini nasıl işlediği hakkında daha fazla bilgi için, Apidog CLI kimlik doğrulama kılavuzuna bakın.

Çalıştırmaları Dal ve Etkinliğe Göre Sınırlama

Drone, işin ne zaman çalışacağını kontrol etmek için size iki kaldıraç sunar: pipeline düzeyinde trigger ve adım düzeyinde when.

Bir trigger bloğu, tüm pipeline'ın çalışıp çalışmayacağına karar verir. Tüm koşulların doğru değerlendirilmesi gerekir, bu nedenle aşağıdaki örnek yalnızca main'i hedefleyen push ve pull isteklerinde çalışır.

trigger:
  branch:
    - main
  event:
    - push
    - pull_request

Bir when bloğu, tek bir adımın içinde yer alır ve sadece o adımı sınırlar. Bu, pipeline'ın çoğunun her yerde çalışmasını istediğiniz ancak daha ağır bir test geçişini tek bir dal için ayırdığınız durumlarda kullanışlıdır.

steps:
  - name: run-api-tests
    image: node:20-alpine
    commands:
      - npm install -g apidog-cli
      - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
    when:
      branch:
        - main
      event:
        - push

Her iki blok da glob desenlerini ve include/exclude alt anahtarlarını destekler. Desteklenen olay türleri arasında push, pull_request, tag, promote, rollback, cron ve custom bulunur.

Yapıt Deposu Olmadan Test Raporlarını Gösterme

Drone'un yerel bir yapıt barındırma özelliği yoktur. Bu, raporları ele alış şeklinizi değiştirir, ancak iki temiz seçeneğiniz vardır.

Birincisi en basitidir: sonuçların derleme günlüğüne yazılması için cli raporlayıcısını kullanın. Çoğu ekip için bu yeterlidir, çünkü günlük hangi iddiaların geçtiğini ve hangilerinin başarısız olduğunu zaten gösterir.

İkinci seçenek, bir HTML raporu oluşturmak ve onu kalıcı bir yere yüklemektir. Drone, dosyaları S3'e veya herhangi bir S3 uyumlu depolama alanına yükleyen resmi bir S3 eklentisi olan plugins/s3'ü yayınlar. Raporu html raporlayıcısı ve --out-dir ile oluşturun, ardından bir yükleme adımı ekleyin.

steps:
  - name: run-api-tests
    image: node:20-alpine
    environment:
      APIDOG_ACCESS_TOKEN:
        from_secret: apidog_access_token
    commands:
      - npm install -g apidog-cli
      - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli,html --out-dir reports

  - name: upload-report
    image: plugins/s3
    settings:
      bucket: my-bucket
      region: us-east-1
      source: reports/**/*
      target: /apidog-reports
      access_key:
        from_secret: aws_access_key
      secret_key:
        from_secret: aws_secret_key

Eklenti, AWS kimlik bilgilerini Apidog token'ı için kullandığınız mekanizma olan from_secret aracılığıyla sırrılardan okur. source anahtarı yüklenecek dosyaların bir glob'udur ve target, kovadaki hedef ön ektir.

Raporun ne içerdiği ve nasıl okunacağı hakkında daha derinlemesine bilgi almak isterseniz, Apidog CLI test raporlarının dökümüne bakın.

Veri Odaklı Çalıştırmalar Ekleme

Bazen bir senaryonun birçok giriş satırına karşı çalıştırılması gerekir: on kullanıcı kimliği, bir düzine payload, bir dizi uç durum. CLI bunu, bir CSV veya JSON dosya yolunu veya depolanmış bir veri kümesi kimliğini kabul eden -d ile ele alır.

commands:
  - npm install -g apidog-cli
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -d ./data.csv -r cli

data.csv dosyasındaki her satır, sütun değerleri senaryo değişkenlerinize bağlı olarak bir yineleme haline gelir. Tam desen, Apidog CLI veri odaklı test makalesinde ele alınmıştır.

Bunun Diğer CI Araçlarıyla Karşılaştırılması

Drone deseni, CLI'yı temiz bir konteynere kurup tek bir komut çalıştırmak, neredeyse her CI sistemine aktarılabilir. Sarmalayıcı sözdizimi farklılık gösterir, ancak Apidog adımı aynıdır.

Eğer pipeline'ları başka yerlerde de çalıştırıyorsanız, Apidog'un GitHub Actions ve Azure Pipelines için eşleşen rehberleri vardır. Ortak fikir, testlerinizin Apidog'da yaşaması ve CI aracının onları sadece tetiklemesidir.

Kapsam hakkında dürüst bir not: Apidog CLI, işlevsel ve sözleşme testleri yapar, yüksek ölçekli yük testi yapmaz. Bir uç noktayı zorlamak için binlerce eşzamanlı sanal kullanıcıya ihtiyacınız varsa, özel bir yük testi aracına başvurun. API'nizin her commit'te doğru davrandığını doğrulamak için, bir Drone adımındaki CLI işi iyi yapar.

Testleri Görsel Olarak Oluşturun, Tek Bir Komutla Çalıştırın

Bu süreci keyifli kılan iş akışı, yazma ve yürütme arasındaki ayrımdır. Uç noktaları tasarlar ve Apidog'da görsel olarak test senaryolarını bir araya getirirsiniz; istekleri zincirleme, durum kodları ve yanıt alanları üzerinde iddialarda bulunma ve ortam değişkenlerini yeniden kullanma gibi. Paketi oluşturmak için kod gerekmez.

Ardından CI, aynı paketi bir konteyner adımının içinde tek bir CLI komutuyla çalıştırır. Bir ekip üyesi Apidog uygulamasında bir testi güncellediğinde, bir sonraki Drone derlemesi bunu otomatik olarak alır. Senkronize tutulacak ikinci bir test kopyası yoktur.

İlk test senaryonuzu oluşturmak için Apidog'u ücretsiz indirin, ardından her push'ta çalıştırmak için yukarıdaki .drone.yml dosyasını deponuza bırakın.

Sıkça Sorulan Sorular

Drone CI Nedir?

Drone, artık Harness'ın bir parçası olan açık kaynaklı, konteyner tabanlı bir CI/CD platformudur. Her pipeline adımını kendi Docker konteyneri içinde çalıştırır ve pipeline'lar bir .drone.yml dosyasında tanımlanır. Bu, derlemeleri tekrarlanabilir tutar ve geleneksel derleme aracılarının önceden yüklenmiş araç dağınıklığını önler.

Drone CI Ücretsiz mi?

Drone projesinin çekirdeği açık kaynaklıdır ve kendi kendine barındırmak ücretsizdir. Harness satın alımından sonra Drone, ücretli kurumsal katmanları bulunan Harness CI Community Edition oldu. Çoğu ekip için, bu kılavuzdaki gibi API testlerini çalıştırmak için kendi kendine barındırılan açık kaynak sürümü yeterlidir.

Drone CI Açık Kaynak mı?

Evet. Drone, orijinal konteyner tabanlı CI araçlarından biridir ve açık kaynak olarak kalmaya devam etmektedir. Harness, 2020'de onu satın aldığında, şirket projeyi açık kaynak olarak tutma taahhüdünde bulundu ve hala kendi kendine barındırabilirsiniz.

Drone CI Nasıl Kullanılır?

Ekipler, her push veya pull request'te kodu otomatik olarak oluşturmak, test etmek ve teslim etmek için Drone'u kullanır. Deponuza bir .drone.yml kaydettiğinizde, Drone bunu okur ve her adımı bir konteynerde çalıştırır. Yaygın adımlar arasında kod derleme, birim testleri çalıştırma, API testleri çalıştırma ve yapıtları harici depolama alanına yükleme bulunur.

Drone CI'da Sırları Nasıl Saklarsınız?

Sırları, deponun Ayarlarından sonra Drone UI'daki Sırlar ekranı aracılığıyla veya CLI'dan drone secret add ile eklersiniz. Daha sonra her bir sırrı, bir adımın environment bloğu veya bir eklentinin settings bloğu içinde from_secret kullanarak referans alırsınız, burada değer sırrın adıdır. Token'ın kendisi asla YAML'inizde görünmez.

Apidog Testlerini Betik Yazmadan CI'da Çalıştırabilir miyim?

Evet. Test senaryolarını Apidog uygulamasında görsel olarak oluşturur, ardından CI'da tek bir apidog run komutuyla çalıştırırsınız. Drone adımı sadece bir Node imajına, bir npm install -g apidog-cli satırına ve senaryo ve ortam kimliklerinizi hedefleyen çalıştırma komutuna ihtiyaç duyar.