Blog

Apidog CLI API Testleri GitHub Actions'ta Nasıl Çalıştırılır (Tam İş Akışı)

Apidog API test senaryolarınızı GitHub Actions'ta çalıştırın. Tam bir iş akışı: apidog-cli'yi kurun, erişim belirtecini gizli olarak saklayın, birleştirmeleri denetleyin ve raporları yayımlayın.

Ashley Innocent

Ashley Innocent

15 June 2026

Apidog CLI API Testleri GitHub Actions'ta Nasıl Çalıştırılır (Tam İş Akışı)

enterprise.banner.title

enterprise.banner.feature1

enterprise.banner.feature2

enterprise.banner.feature3

enterprise.banner.ctaB

API testleriniz kendi makinenizde geçiyor. Ardından bir ekip arkadaşı, oturum açma uç noktasını bozan bir değişikliği birleştirir ve bir müşteri destek talebi açana kadar kimse fark etmez. Testler vardı. Sadece önemli oldukları anda hiç çalışmadılar: çekme isteğinde, birleştirmeden önce.

Sürekli entegrasyon bu boşluğu kapatır. Testleri yerel terminalinizden çıkarıp, her bir göndermede, her bir değişikliğe karşı otomatik olarak çalıştıran bir işlem hattına taşırsınız. Özellikle API testleri için, bunu yapmanın en temiz yolu, zaten oluşturduğunuz senaryoları tam olarak yürüten, geçme/kalma çıkış kodu döndüren ve CI'ın derlemenin başarılı mı yoksa başarısız mı olacağına karar vermesini sağlayan bir komut satırı çalıştırıcısıdır.

Düğme

Özetle

API testlerini neden CI'da çalıştırmalıyız?

Sadece çalıştırmayı hatırladığınızda çalışan bir test, güvenemeyeceğiniz bir testtir. Senaryoyu yazarken yerel çalıştırmalar iyidir. Ancak bir ekip işin içine girdiğinde bozulurlar, çünkü her geliştiricinin makinesi biraz farklıdır ve kimse her göndermeden önce tüm paketi çalıştırmaz.

CI, çalıştırmayı otomatik ve tek tip hale getirerek güven sorununu çözer. Her çekme isteği, aynı temiz çalıştırıcıda, aynı ortama karşı aynı işi tetikler. Bir uç nokta 500 dönmeye başladığında veya bir yanıt şeması sapma gösterdiğinde, kontrol, buna neden olan çekme isteğinde, gönderen kişinin adıyla birlikte başarısız olur. Geri bildirim, günlerce sonra üretimde olmak yerine, değişiklik hala tazeyken dakikalar içinde gelir.

API testleri bu duruma çok uygundur çünkü hızlı ve belirlenimcidirler. Bir senaryo gerçek uç noktalara ulaşır, durum kodlarını ve yanıt gövdelerini doğrular ve ya geçer ya da kalır. Güvenilmez tarayıcılar, beklemeyi gerektiren bir renderlama yoktur. Bu da onları birleştirme kapısı olarak ideal kılar: her PR'da çalışacak kadar hızlı, kötü olanı engellemek için yeterince kararlı. CI/CD'nin ne olduğu ve parçaların nasıl bir araya geldiği hakkında daha geniş bir bilgi edinmek isterseniz, CI/CD nedir ve nasıl çalışır hakkındaki temel kılavuz, esasları kapsar.

Apidog CLI aslında ne işe yarar?

İşte size en çok zaman kazandıran kısım: CLI için test kodu yazmazsınız.

Test senaryolarınızı Apidog uygulamasında, ihtiyacınız olan istekler, iddialar, ortam değişkenleri ve verilerle görsel olarak oluşturursunuz. CLI bir çalıştırıcıdır. Bir senaryo kimliği ve bir erişim belirteci verildiğinde, bu senaryoyu Apidog projenizden alır ve her bir iddiayı tıpkı uygulamanın yapacağı gibi değerlendirerek istek üzerine istek yürütür. Sonuç bir rapor ve bir çıkış kodudur.

Bu tasarım CI için önemlidir. Çoğu test çalıştırıcısı, testlerinizin ayrı bir kod temsilini sürdürmenizi ister; işlem hattında çalıştırdığınız şey, tasarladığınız şeyden sapar. Apidog ile işlem hattı, ekibinizin uygulamada zaten sürdürdüğü senaryoyu çalıştırır. Görsel düzenleyicide bir iddiayı güncelleyin ve bir sonraki CI çalıştırması bunu alır. Senkronize tutulacak ikinci bir kopya yoktur.

İkili dosya apidog'dur ve apidog-cli npm paketi olarak dağıtılır. Her komut apidog run ile başlar. Çalıştırıcının daha kapsamlı bir otomasyon iş akışına nasıl entegre edildiğini görmek isterseniz, API test otomasyonu için Apidog CLI'yı Claude Skills ile entegre etme kılavuzu bu konuyu ele almaktadır; bu makale, bir GitHub Actions işlem hattı için ihtiyacınız olan bayraklara odaklanmaktadır.

Başlamadan önce: ihtiyacınız olan üç şey

İş akışı çalışmadan önce üç bilgiye ihtiyacınız var. İkisi Apidog projenizden kimliklerdir; biri bir belirteçtir.

  1. Bir test senaryosu. Henüz yapmadıysanız Apidog uygulamasında oluşturun. CLI'ın çalıştırdığı budur. Başlamak için tek bir giriş yapma ve profil alma senaryosu yeterlidir; daha sonra ölçeklendirebilirsiniz.
  2. Senaryo Kimliği ve Ortam Kimliği. Senaryo Kimliği, CLI'ye neyi çalıştıracağını söyler; ortam Kimliği ise nerede (geliştirme, hazırlık, üretim) çalıştıracağını söyler. Her ikisi de uygulamada görünür.
  3. Bir erişim belirteci. Bu, CLI'yi Apidog hesabınıza doğrular, böylece senaryoyu alıp çalıştırabilir.

Tüm bunları tek seferde almanın en temiz yolu senaryonun CI/CD sekmesidir. Otomatikleştirmek istediğiniz test senaryosunu açın, CI/CD sekmesine geçin ve komut satırı seçeneğini seçin. Bir erişim belirteci eklemek ve bir tane oluşturmak için tıklayın. Apidog, erişim belirteci, senaryo kimliği (-t) ve ortam kimliği (-e) zaten doldurulmuş olarak sizin için tam apidog run komutunu bir araya getirir. Bu komutu kopyalayın; CI adımınızın temelini oluşturacaktır.

Önceden belirtilmesi gereken bir kural: erişim belirtecine bir parola gibi davranın. Onu taahhüt edilmiş bir iş akışı dosyasına yapıştırmayın. Bir GitHub Actions sırrı olarak saklayın ve bir ortam değişkeni olarak referans alın. Aşağıdaki her örnek tam da bu nedenle $APIDOG_ACCESS_TOKEN kullanır.

Adım 1: Erişim belirtecini bir GitHub sırrı olarak saklayın

GitHub'daki deponuzu açın. Ayarlar'a, ardından Sırlar ve değişkenler'e, sonra Eylemler'e gidin ve Yeni depo sırrı'na tıklayın.

Kaydedin. Belirteç artık durağan halde şifrelenmiştir ve yalnızca iş akışı çalıştırmalarına açıktır, asla günlüklere yazdırılmaz. İş akışında onu ${{ secrets.APIDOG_ACCESS_TOKEN }} olarak referans alacak ve bir env: bloğu aracılığıyla CLI'ye vereceksiniz. Senaryo Kimliği ve ortam Kimliği gizli değildir; zararsız kimliklerdir, bu yüzden onları doğrudan iş akışı dosyasına yazabilirsiniz. Yalnızca belirtecin korunması gerekir.

Ekibiniz aynı Apidog projesini kullanan birkaç depoda çalışıyorsa, sırrı bunun yerine kuruluş düzeyinde bir kez tanımlayın ve ilgili depolara erişim izni verin. Aynı ad, döndürmek için tek bir yer.

Adım 2: Minimum iş akışı

Deponuzda .github/workflows/api-tests.yml dosyasını oluşturun. Bu, işe yarar bir şeyler yapan en küçük iş akışıdır: main dalını hedefleyen her çekme isteğinde senaryonuzu çalıştırır.

name: API tests

on:
  pull_request:
    branches: [main]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

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

      - name: Run API test scenario
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -r cli
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

605067 yerine senaryo kimliğinizi ve 1629989 yerine ortam kimliğinizi yazın. Bu dosyayı taahhüt edin, bir çekme isteği açın ve Kontroller sekmesini izleyin. İş, bir Ubuntu çalıştırıcısını başlatır, Node 20'yi kurar, CLI'yi kurar ve senaryonuzu çalıştırır. Her iddia geçerse, kontrol yeşile döner. Biri başarısız olursa, apidog run sıfır olmayan bir kodla çıkar, GitHub kontrolü başarısız sayar ve PR kırmızı bir X gösterir.

Bu kırmızı X, tüm meselenin özüdür. Bir şeyin bozulduğunu anlamak için kimsenin günlük okumasına gerek yoktur; başarısız kontrol doğrudan çekme isteğinde görünür.

Kurulum adımı hakkında bir not: genel npm install -g apidog-cli basittir ve çalışır. Çalıştırıcının genel paketlerini değiştirmek istemiyorsanız, kurulum adımını atlayabilir ve CLI'yi bunun yerine npx aracılığıyla çağırabilirsiniz:

      - name: Run API test scenario
        run: npx apidog-cli run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r cli
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

Her iki yaklaşım da aynı senaryoyu çalıştırır. npx geçici çalıştırıcılarda daha düzenlidir; genel kurulum, çalıştırmalar arasında node_modules'ı önbelleğe aldığınızda biraz daha hızlıdır. Ev stilinize uygun olanı seçin.

Adım 3: Gerçekten okuyabileceğiniz bir rapor yayınlayın

Yeşil veya kırmızı bir kontrol size sonucu söyler. Bir test başarısız olduğunda, nedenini bilmek istersiniz ve bunun için raporu istersiniz.

-r (veya --reporters) bayrağı rapor formatlarını kontrol eder. Virgülle ayrılmış olarak cli, html, json ve junit kabul eder. CI için iki format yerini alır:

Derleme günlüğünün kendisinde okunabilir çıktı istiyorsanız cli'yi de açık tutun. İşte hem rapor formatlarını üretmek hem de bunları bir dizine yazmak için yükseltilmiş çalıştırma adımı, ayrıca raporun çalıştırmadan sonra kalması için bir yükleme adımı:

      - name: Run API test scenario
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -n 1 \
            -r html,junit,cli \
            --out-dir ./apidog-reports
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - name: Upload test report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: apidog-report
          path: ./apidog-reports

İki ayrıntı bunu istediğiniz gibi çalıştırır. --out-dir bayrağı CLI'ye raporları nereye yazacağını söyler; burada ./apidog-reports'tur, bu da yükleme adımı tarafından alınır. Ve yükleme adımındaki if: always() önemli olandır: varsayılan olarak GitHub, bir adım başarısız olduğunda sonraki adımları atlar, ancak testler başarısız olduğunda raporu en çok istersiniz. if: always() test sonucundan bağımsız olarak yüklemeyi çalıştırmaya zorlar. İş bittikten sonra, rapor çalıştırma özet sayfasındaki Yapıtlar altında görünür ve indirilmeye hazır olur.

-n 1 bayrağı yineleme sayısını tek çalıştırmaya ayarlar; senaryonun arka arkaya birkaç kez yürütülmesini isterseniz bunu artırın.

GitHub'ın JUnit sonuçlarını indirilebilir bir dosya yerine açıklama eklenmiş bir kontrol olarak satır içinde göstermesini isterseniz, çalıştırma adımından sonra bir `published-test-results` eylemi ekleyin ve bunu ./apidog-reports/*.xml'e yönlendirin. Bu, XML'yi çalıştırmaya ekli bir geçme/kalma özeti haline getirir, bu da günlüğü kaydırmanın pratik olmadığı daha büyük paketler için kullanışlıdır.

Adım 4: Doğru ortamı doğru zamanda test edin

Bir çekme isteği hazırlık ortamına karşı test etmelidir. Üretime dağıtım, üretime karşı doğrulanmalıdır. Aynı senaryo her ikisini de yapabilir; sadece -e ile ortam kimliğini değiştirirsiniz.

Yaygın, dayanıklı bir kurulum, tek bir iş akışı dosyasında iki tetikleyici kullanır. Çekme istekleri, hazırlık ortamınıza karşı senaryoyu bir birleştirme kapısı olarak çalıştırır. main dalına yapılan göndermeler (bir birleştirmenin ürettiği şey), dağıtım sonrası bir duman testi olarak aynı senaryoyu üretim ortamına karşı çalıştırır.

name: API tests

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  pr-check:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g apidog-cli
      - name: Test staging
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -r junit,cli \
            --out-dir ./apidog-reports
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: staging-report
          path: ./apidog-reports

  prod-smoke:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g apidog-cli
      - name: Smoke test production
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1730055 \
            -r cli \
            --on-error end
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

İki ortam kimliği (hazırlık için 1629989, üretim için 1730055) tek anlamlı farktır. PR işi, gözden geçirenlerin hataları inceleyebilmesi için bir JUnit raporu oluşturur ve arşivler; üretim duman testi ise --on-error end ile hızlı ve yalın bir şekilde çalışır ve ilk bozuk iddiada durur, böylece bir dağıtımın ters gittiğini hızla öğrenirsiniz.

--on-error bilmeye değerdir. Bir adım senaryo ortasında başarısız olduğunda ne olacağını kontrol eder. end ilk başarısızlıkta çalıştırmayı durdurur (hızlı geri bildirim, duman testleri için iyi). continue kalan her adımı çalıştırır, böylece tüm hataları tek bir raporda görürsünüz (kapsamlı bir PR kontrolü için iyi). ignore bilinen hatalı bir adımı çalıştırmayı aksatmadan atlar. Hangisini seçerseniz seçin, bir şey başarısız olursa çalıştırma yine de sıfır olmayan bir çıkışla biter, bu yüzden kapı her iki durumda da tutar.

Daha da ileri: matris çalıştırmaları, klasörler ve veri odaklı testler

Temel kapı kurulduktan sonra, birkaç bayrak çok fazla ek YAML olmadan onu genişletir.

Bir senaryo değil, tüm bir özellik alanını çalıştırın. Bir klasör içindeki her senaryoyu çalıştırmak için -t <scenarioId> yerine -f <folderId> kullanın veya seçilmiş bir paketi çalıştırmak için --test-suite <testSuiteId> kullanın. Paketler, belirli, sıralı bir senaryo kümesinin tek bir mantıksal iş olarak birlikte çalıştırılmasını istediğinizde doğru araçtır; test paketleriyle otomatik API testlerini ölçeklendirme kılavuzu, onlara ne zaman başvurmanız gerektiğini kapsar.

Birkaç ortamı paralel olarak test edin. Bir matris, aynı işi birden çok ortam kimliği üzerinde aynı anda çalıştırır:

jobs:
  api-tests:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        env-id: [1629989, 1730055]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g apidog-cli
      - name: Run scenario against ${{ matrix.env-id }}
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e ${{ matrix.env-id }} \
            -r cli
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

GitHub, matris değeri başına bir çalıştırıcı başlatır, böylece hazırlık ve üretim eşzamanlı olarak test edilir ve her biri kendi geçme/kalma durumunu raporlar.

Yinelemeleri bir veri dosyasından yönlendirin. -d bayrağı, bir CSV veya JSON dosyasının satırları boyunca bir senaryo çalıştırır ve her satırı ayrı bir geçiş olarak ele alır: apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -d ./test-data.csv -r junit. Bu, elli senaryo oluşturmadan aynı uç noktayı elli girişe karşı nasıl doğrulayacağınızdır.

Bir dala karşı çalıştırın. Ekibiniz Apidog'un dal özelliğini kullanıyorsa, --branch <branchName>, çalıştırmayı main yerine belirli bir dala yönlendirir, bu da bir özellik dalının PR'ının o dalın senaryo tanımlarına karşı test etmesini sağlar.

Yaygın CI hatalarını giderme

Bu, alternatiflerle nasıl karşılaştırılır?

API testlerini bir çerçeveyle kod olarak yazabilir, bunları bir test çalıştırıcısına bağlayabilir ve Eylemler'den çağırabilirsiniz. Bu işe yarar, ancak şimdi API ile ve ekibinizin API aracında tasarladığı her şeyle senkronize kalması gereken bir kod paketi sürdürüyorsunuz. Apidog yaklaşımı bu tekrardan kaçınır: ekibinizin uygulamada zaten sürdürdüğü senaryo, CI'da çalışan testtir.

Ayrıca bir iş akışı adımında ham curl çağrılarını komut dosyasına dönüştürebilirsiniz. Tek bir sağlık kontrolü için iyi, ancak bunun ötesi zahmetlidir, çünkü CLI'nin size ücretsiz olarak sunduğu iddiaları, ortam değiştirmeyi ve raporlamayı elle yapmanız gerekir.

GitHub Actions bunun için tek yer değildir. Aynı apidog run komutu, GitLab CI, Jenkins, CircleCI veya bir kabuk komutunu çalıştırabilen ve bir çıkış kodunu okuyabilen herhangi bir çalıştırıcıya düşer. GitHub Actions platformunuz değilse, buradaki desenler doğrudan aktarılır; platformlar arası görünüm için CI/CD'de API testlerini otomatikleştirme kılavuzuna veya Jenkins kullanıyorsanız Apidog otomatik testlerini Jenkins ile entegre etme kılavuzuna bakın.

Çalıştıracağınız senaryoları oluşturmak için Apidog'u indirin, testlerinizi uygulamada tasarlayın ve senaryonun CI/CD sekmesinden CLI komutunu alın. Çalıştırıcı ücretsiz bir npm paketidir; ne çalıştırabileceğiniz Apidog projenize bağlıdır, ancak komut satırı çalıştırıcının kendisi ayrı bir ücretli ürün değildir.

Sonuç

Kurulum göründüğünden daha küçüktür. Apidog'da bir senaryo oluşturun, bir erişim belirtecini bir GitHub sırrı olarak saklayın ve bir iş akışı dosyasına birkaç adım ekleyin. Buradan itibaren, her çekme isteği API testlerinizi otomatik olarak çalıştırır, başarısız bir uç nokta birleştirmeden önce kontrolü kırmızıya çevirir ve neyin bozulduğunu görmek istediğinizde rapor Yapıtlar sekmesinde sizi bekler.

Basit kalmasının nedeni iş bölümüdür. Apidog uygulaması testlere sahiptir; CLI onları çalıştırır; GitHub çıkış kodunu okur. Hiçbir şeyin kopyalanması veya senkronize tutulması gerekmez. Uygulamada bir iddiayı güncellediğinizde, bir sonraki CI çalıştırması onu kullanır. İşte bu, ilk üretim olayından sonra takmak yerine bir projenin ilk gününde bunu yapmaya değer kılan şeydir.

Düğme

API Tasarım-Öncelikli Yaklaşımı Apidog'da Uygulayın

API'leri oluşturmanın ve kullanmanın daha kolay yolunu keşfedin

Ücretsiz Kaydolİndir