Hoppscotch CLI'dan Apidog CLI'a Geçiş Nasıl Yapılır

Hoppscotch CLI, bir terminalde veya CI işlem hattında API koleksiyonlarını çalıştırmak için temiz, ücretsiz bir yoldur. `hopp test` komutu bir koleksiyon dosyasını okur, her isteği yürütür, ön-istek ve test komut dosyalarınızı çalıştırır ve bir doğrulama başarısız olduğunda sıfır olmayan bir çıkış koduyla çıkar. Birçok ekip için bu yeterlidir.

Ancak bir çalıştırıcı (runner), API işinin yalnızca bir dilimidir. Bir noktada ayrı bir tasarım aracı, bir mock sunucusu, bir doküman sitesi ve çalıştırıcı arasında hokkabazlık yaparsınız ve bunların hiçbiri tek bir doğruluk kaynağını paylaşmaz. Ekipler genellikle Hoppscotch CLI'dan Apidog CLI'a nasıl geçiş yapacaklarını araştırmaya işte o zaman başlarlar. Apidog, tasarım, hata ayıklama, taklit (mocking), dokümantasyon ve testi tek bir platformda birleştirir ve CLI'sı test tarafını CI'da çalıştırır. Çalıştırıcı zaten bildiğiniz şekliyle kalır. Değişen şey, etrafındaki her şeydir.

Ne zaman geçiş yapmalısınız (ve yapmamalısınız)

Önce kendinize karşı dürüst olun. Eğer tek gereksiniminiz “bir koleksiyonu CI'da ücretsiz çalıştırmak, istersem kendi kendine barındırmak” ise, Hoppscotch CLI gerçekten iyi bir araçtır. Açık kaynaklıdır, çalıştırıcı hızlıdır ve `@hoppscotch/cli` normal bir npm paketi olarak gelir. Kalmakta utanılacak bir şey yoktur.

Aşağıdakilerden biri sizi rahatsız etmeye başladığında geçiş yapın:

• API'ları bir araçta tasarlıyor, başka birinde taklit ediyor ve üçüncü bir araçta doküman yazıyorsunuz ve bunları senkronize tutmak manuel bir iş.
• Test çalıştırmalarının, mock sunucularının ve yayınlanmış dokümantasyonun tek bir proje tanımını paylaşmasını istiyorsunuz.
• Daha zengin raporlamaya (paydaşlar için HTML raporları, makineler için JSON) ve bulutta barındırılan çalıştırma geçmişine ihtiyacınız var.
• Uç noktaları, şemaları, ortamları ve dalları sadece yürütmekle kalmayıp CLI'nin yönetebileceği kod olarak ele almak istiyorsunuz.

Eğer bu liste haftanızın özeti gibiyse, geçişin nedeni çalıştırıcı değil platformdur. İşte bunu temiz bir şekilde nasıl yapacağınız.

Adım 1: Hoppscotch koleksiyonunuzu ve ortamınızı dışa aktarın

Hoppscotch'taki her şey JSON formatındadır, bu da dışa aktarımı zahmetsiz hale getirir.

Hoppscotch uygulamasından (web veya masaüstü) CI'da çalıştırdığınız koleksiyonu açın. Koleksiyonun menüsünü kullanın ve size bir `.json` dosyası veren **Dışa Aktar**'ı seçin. `-e` ile geçirdiğiniz ortam için de aynısını yapın: ortamlar panelini açın ve onu kendi JSON dosyasına dışa aktarın.

CLI'yı zaten yerel dosyalara karşı çalıştırıyorsanız, bunlar diskte zaten mevcuttur. Tipik bir Hoppscotch CI adımı şöyle görünür:

npm i -g @hoppscotch/cli
hopp test ./collections/checkout-api.json -e ./environments/staging.json

Her iki dosyayı da saklayın. `checkout-api.json` sizin koleksiyonunuz, `staging.json` ise ortamınızdır. Bu ikisi, taşıdığınız tüm yüktür.

Buradayken Node sürümleri hakkında küçük bir not. Mevcut Hoppscotch CLI, Node.js v22 veya daha yenisini gerektirir; Node 20'ye sabitlenmiş ekipler CLI v0.26.0'da kalır. Apidog CLI sizi buna bağlamaz, bu nedenle bir geçiş aynı zamanda bir sürüm kısıtlamasını kaldırma şansıdır.

Adım 2: Koleksiyonu Apidog'a aktarın

Apidog'da bir proje oluşturun (veya mevcut birini açın), ardından Hoppscotch dışa aktarımınızı içeri aktarın. Apidog yaygın koleksiyon formatlarını ve OpenAPI'yi okur, böylece koleksiyonu doğrudan içeri getirebilirsiniz. API'nizin bir OpenAPI belirtimi de varsa, onu da içeri aktarın. Apidog, belirtimi aktarımda doğrular, böylece yapısal sorunlar, çalıştırma sırasında sessizce başarısız olmak yerine hemen ortaya çıkar.

Hoppscotch ortamınızı, aynı değişken adlarına sahip bir Apidog ortamına eşleyin. Eğer `staging.json` `base_url` ve `api_token` tanımladıysa, bu anahtarları eşleşen Apidog ortamı altında yeniden oluşturun. Adları aynı tutmak, test komut dosyalarınızın ve istek URL'lerinizin düzenleme gerektirmeyeceği anlamına gelir.

Platform tarafının karşılığını vermeye başladığı an da budur. Aktardığınız uç noktalar artık tasarım yapıtlarıdır. Bunlara şemalar ekleyebilir, onlardan bir mock sunucusu oluşturabilir ve test ettiğiniz aynı tanımlardan dokümanlar yayınlayabilirsiniz. Apidog CLI eksiksiz kılavuzu kurulumdan sonra tüm yüzeyi kapsar ve kurulum kılavuzu çalıştırıcı ikili dosyasını ele alır.

Adım 3: `hopp test` komutunu `apidog run` ile eşleştirin

Zihinsel model doğrudan aktarılır. Hoppscotch bir koleksiyon dosyasını çalıştırırken, Apidog projenizden bir test senaryosu veya koleksiyonunu çalıştırır. Aynı iş, farklı bir doğruluk kaynağı.

# Hoppscotch
hopp test ./collections/checkout-api.json -e ./environments/staging.json

# Apidog
apidog run --access-token $APIDOG_TOKEN -e "Staging"

Her iki komut da her isteği sırasıyla yürütür, ön-istek komut dosyalarını çalıştırır, test doğrulamalarınızı çalıştırır ve herhangi bir şey başarısız olursa sıfır olmayan bir çıkış kodu döndürür. Bu çıkış kodu sözleşmesi, CI'ın bağlı olduğu kısımdır ve korunur, böylece işlem hattınızın başarılı/başarısız mantığı değişmez.

Kimlik doğrulama faydalı bir şekilde farklılık gösterir. Hoppscotch, bulut veya kendi kendine barındırılan koleksiyonlar için `--token` ile kişisel bir erişim belirteci geçirir. Apidog, bir oturum açma veya erişim belirteci ile kimlik doğrulaması yapar, bu da CLI'nın tek bir dışa aktarılmış dosya yerine projenizdeki kaynaklara erişmesini sağlar. Daha önce belirteç işleme ile uğraştıysanız, kimlik doğrulama kılavuzu seçenekleri sunar.

Adım 4: Veri odaklı çalıştırmaları dönüştürün

Her iki araç da veri odaklı test yapar, bu nedenle bir girdi CSV'si üzerinde yineleme, geçişi atlatır.

Hoppscotch'ta yineleme verilerini ve bir sayıyı geçirirsiniz:

hopp test ./collections/checkout-api.json \
  -e ./environments/staging.json \
  --iteration-count 50 \
  --iteration-data ./data/orders.csv

Apidog'da çalıştırıcı, `-d` ile bir veri kümesi alır. CSV ve JSON'u kabul eder, bu nedenle aynı `orders.csv` içe aktarımdan sonra çalışır:

apidog run --access-token $APIDOG_TOKEN \ -e "Staging" \ -d ./data/orders.csv

CSV başlık satırınız, istekler ve doğrulamalar içinde başvurduğunuz değişken adları haline gelir, Hoppscotch'un kullandığı aynı desendir, bu nedenle test gövdelerinin yeniden yazılmasına gerek kalmaz. Apidog'un bu özelliğine yeniyseniz, veri odaklı test kılavuzu, sütunları değişkenlere nasıl bağlayacağınızı ve her yineleme için bir satır nasıl çalıştıracağınızı gösterir.

Adım 5: Raporlayıcılarınızı dönüştürün

Raporlama, platformun öne çıktığı yerdir ve dönüştürme basittir.

Hoppscotch, çoğu CI sisteminin test panelleri için ayrıştırdığı tek bir bayrakla bir JUnit XML dosyası yayınlar:

hopp test ./collections/checkout-api.json \
  -e ./environments/staging.json \
  --reporter-junit ./reports/results.xml

Apidog size raporlayıcı seçenekleri sunar: okunabilir bir CLI özeti, paydaşlara sunabileceğiniz bir HTML raporu ve makineler için bir JSON raporu. Ayrıca sonuçları buluta iterek paylaşılabilir çalıştırma geçmişi elde edebilirsiniz.

# İnsan tarafından okunabilir HTML raporu
apidog run --access-token $APIDOG_TOKEN \
  -e "Staging" \
  -r html \
  --upload-report

CI panonuz özellikle JUnit XML bekliyorsa, bu entegrasyonu değişim sırasında aklınızda bulundurun, çünkü Apidog, bir JUnit bayrağı yerine CLI/HTML/JSON raporlarına ve bulut raporlarına dayanır. Çoğu ekip için HTML raporu ve yüklenen bulut geçmişi, kimsenin açmadığı ham bir XML dosyasından daha iyi bir adımdır. Test raporları kılavuzu her formatı ve ne zaman kullanılacağını ayrıntılarıyla açıklar.

Öncesi ve sonrası: komut eşlemesi

Tablodaki `-d` bayrağına dikkat edin. Hoppscotch'ta `-d` milisaniye cinsinden gecikme anlamına gelir; Apidog'da `-d` veri odaklı çalıştırmalar için veri kümesidir. Aynı harf, farklı iş. Hopp'tan Apidog'a geçiş sırasında insanları şaşırtan tek püf noktası budur.

Adım 6: GitHub Actions'a entegre edin

Son adım, ve hedef tüm yol boyunca yeşil bir derlemedir. Önce eski Hoppscotch işinin yanına Apidog işini kurun, başarılı olduğunu onaylayın, sonra eski adımı silin. Asla körlemesine geçiş yapmayın.

name: API tests
on: [push, pull_request]

jobs:
  apidog-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

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

      - name: Run API tests
        env:
          APIDOG_TOKEN: ${{ secrets.APIDOG_TOKEN }}
        run: |
          apidog run \
            --access-token "$APIDOG_TOKEN" \
            -e "Staging" \
            -d ./data/orders.csv \
            -r html \
            --upload-report

Erişim belirtecinizi bir depo sırrı olarak saklayın, asla YAML'da değil. CLI, herhangi bir başarısız doğrulama durumunda sıfır olmayan bir çıkış kodu döndürdüğü için, iş testleriniz başarısız olduğunda aynen başarısız olur, bu da ekibinizin Hoppscotch'tan zaten güvendiği bir davranıştır. GitHub Actions kılavuzu önbelleğe almayı ve matris çalıştırmalarını kapsar ve daha geniş CI/CD işlem hattı kılavuzu GitLab, Jenkins ve diğerlerini ele alır.

Apidog işi birkaç çalıştırma boyunca yeşil olduğunda, Hoppscotch adımını ve npm kurulumunu kaldırın. Geçiş tamamlandı, derleme asla kırmızıya dönmedi.

Hoppscotch hakkında adil bir söz

Bunların hiçbiri Hoppscotch'u kötülemek değildir. CLI çalıştırıcısı hızlı ve ücretsizdir, proje tamamen açık kaynaklıdır ve tüm yığını kendi kendine barındırabilirsiniz. Sadece yalın bir çalıştırıcı istiyorsanız, yerini fazlasıyla hak eder. Geçiş nedeni kapsamdır: tasarım, mock, dokümanlar ve testlerin hepsinin tek bir tanımı paylaşması gerektiğinde, bağımsız bir çalıştırıcı bunu sağlayamazken, entegre bir platform sağlayabilir. İki çalıştırıcıyı doğrudan Apidog CLI vs Hoppscotch CLI makalesinde karşılaştırın ve CLI'lar yerine uygulamaları tartıyorsanız, Postman vs Hoppscotch ve Hoppscotch alternatifleri özeti bağlam sağlar.