Buildkite'ta otomatik API testlerini, Apidog CLI'yı kuran, bir ortama karşı apidog run komutunu çalıştıran ve HTML raporunu bir derleme yapıtı olarak yükleyen bir komut adımını .buildkite/pipeline.yml dosyasında tanımlayarak çalıştırırsınız. Bu kılavuz, Buildkite'ın sırları nasıl işlediği ve Apidog erişim jetonunuzun günlüklere sızmamasını sağlama dahil olmak üzere tüm işlem hattını anlatır. Apidog testlerinizin zaten mevcut olduğunu varsayıyoruz; onları bir kez görsel olarak oluşturursunuz, ardından CI'da tek bir komutla çalıştırırsınız.
Başlamadan önce küçük bir açıklama. Buildkite bir CI/CD platformudur. Docker'ın içindeki görüntü oluşturma arka ucu olan Docker BuildKit ile aynı değildir. İsimler benzer görünse de, birbiriyle ilişkisi olmayan ürünlerdir. Bu makale tamamen CI/CD platformu olan Buildkite hakkındadır.
Buildkite Nedir
Buildkite, hibrit bir model etrafında inşa edilmiş bir CI/CD platformudur. Tarayıcınızda gördüğünüz kontrol paneli, gösterge paneli ve derleme orkestrasyonu gibi barındırılan bir kontrol düzlemine ve işlerinizi fiilen yürüten aracılara (agent'lara) sahiptir.
Bu ayrım önemlidir. Kontrol düzlemi işleri planlar, ancak işler aracılar üzerinde çalışır. Kendi altyapınızda veya bulutunuzda aracılar barındırabilir veya Buildkite'ın sizin için çalıştırdığı yönetilen işlem gücü olan Buildkite tarafından barındırılan aracıları kullanabilirsiniz.
Buildkite'ı tamamen barındırılan CI sistemlerinden ayıran temel özellik budur. Buildkite derlemeleri koordine ederken kodunuz ve sırlarınız kendi makinelerinizde kalabilir. API testi için bu, testlerinizin hizmetlerinizin ve ağ erişiminizin zaten bulunduğu yerde çalıştığı anlamına gelir.
Buildkite aracısı (agent) açık kaynaklıdır. Go dilinde yazılmış ve MIT Lisansı altında yayınlanmıştır, kaynak kodu GitHub'dadır. Platform ve etrafındaki kontrol düzlemi ticari bir SaaS ürünüdür.
Buildkite Ne İçin Kullanılır
Ekipler Buildkite'ı kod değişiklikleriyle tetiklenen her türlü otomatik işi çalıştırmak için kullanır: yapıtları derleme, birim ve entegrasyon testlerini çalıştırma, hizmetleri dağıtma ve uçtan uca kontrolleri yapma. Aracılar kendi donanımınızda çalışabildiği için, işlem gücü, ağ sınırları veya GPU'lar gibi donanımlar üzerinde kontrol ihtiyacı duyan ekiplerde yaygındır.
API testi buna çok iyi uyar. Testlerinizin bir hazırlık (staging) veya test ortamına ulaşmasını, gerçek yanıtlara göre doğrulama yapmasını ve bir sözleşme bozulduğunda bir dağıtımı engellemesini istersiniz. Buildkite size tam olarak bu akışı modellemek için adım türleri sunar ve bunları aşağıda kullanacağız.
Buildkite'ı diğer seçeneklerle karşılaştırıyorsanız, API ekipleri için en iyi sürekli entegrasyon araçları hakkındaki derlememiz, bu kullanım durumu için çeşitli platformların nasıl karşılaştırıldığını ele almaktadır.
Buildkite İşlem Hatları Nasıl Tanımlanır
Bir Buildkite işlem hattı, adımların bir listesidir. Bunları tanımlamak için varsayılan yer, deponuzdaki .buildkite/pipeline.yml dosyasında bulunur. Bir derleme başladığında, Buildkite, pipeline.yml adlı bir dosya içeren .buildkite adlı bir dizin arar. Depo kökündeki gizli olmayan bir buildkite/ dizini de çalışır.
En üst düzey anahtar steps:'tir ve bir liste tutar. API testi için en çok kullanacağınız adım türleri şunlardır:
- Komut adımları bir aracı üzerinde kabuk komutları çalıştırır. Testlerinizin çalıştığı yer burasıdır.
- Bekleme adımları her önceki adım bitene kadar işlem hattını duraklatır. Bunları yalnızca
- waitliste öğesi olarak yazarsınız. - Blok adımları manuel bir onay geçidi oluşturur,
- block: "Etiket"olarak yazılır. Bir insan devam etmek için tıklar, bu da üretim dağıtımından önce faydalıdır.
Komut adımları, sıkça kullanacağınız bir dizi anahtarı destekler: adlandırma ve referanslar için label ve key, betik için command veya commands, ortam değişkenleri için env, hedefleme için agents, gizli değerleri enjekte etmek için secrets, saklanacak dosyalar için artifact_paths, yayma (fan-out) için parallelism ve bir dizi değer boyunca aynı adımı çalıştırmak için matrix.
agents anahtarı, etiket çiftlerinin bir hash'idir. Bunu, bir adımı doğru aracıya yönlendirmek için kullanırsınız, örneğin queue: "tests". Etiketler, test işlerini doğru ağ erişimine veya araçlara sahip aracılarda tutmanıza olanak tanır.
API Testlerini Çalıştıran Kopyala-Yapıştır Bir İşlem Hattı
İşte Apidog CLI'yı kuran, bir ortama karşı bir test senaryosu çalıştıran ve HTML raporunu yükleyen minimal bir .buildkite/pipeline.yml dosyası. Apidog CLI, Apidog test senaryolarınızı komut satırından çalıştıran bir Node.js aracıdır.
steps:
- label: ":test_tube: API tests (Apidog)"
key: "api-tests"
command: |
npm install -g apidog-cli
apidog run \
--access-token "$APIDOG_ACCESS_TOKEN" \
-t 637132 \
-e 358171 \
-r html,cli
buildkite-agent artifact upload "apidog-reports/**/*"
agents:
queue: "default"
secrets:
- APIDOG_ACCESS_TOKEN
Bayraklar hakkında birkaç not. -t, çalıştırmak istediğiniz test senaryosunun veya senaryo dizininin kimliğidir. -e, testlerinizin kullandığı temel URL'yi ve değişkenleri seçen çalışma zamanı ortam kimliğidir. -r html,cli hem insan tarafından okunabilir bir terminal özeti hem de bir HTML rapor dosyası ister. --access-token Apidog jetonunuzu iletir, böylece CLI projenize erişebilir.
Buildkite aracı ana bilgisayarında buildkite-agent ikili dosyası zaten mevcuttur, çünkü işi çalıştıran odur. Yalnızca apidog-cli'yi kendiniz yüklersiniz. Her bayrağın daha derinlemesine incelenmesi için Apidog CLI kapsamlı kılavuzuna bakın.
Önce terminalden tek bir API çalıştırma konusunda adım adım bir rehber istiyorsanız, Apidog CLI komut satırı test eğitimi, bunu CI'a bağlamadan önce iyi bir ısınmadır.
Apidog Erişim Jetonunu Buildkite Gizlilikleri ile Geçirme
Apidog erişim jetonunuz bir kimlik bilgisidir. Asla pipeline.yml dosyanızda bulunmamalı veya derleme günlüğüne yazdırılmamalıdır. Buildkite size bunun için Buildkite sırları adı verilen yerel bir özellik sunar.
Buildkite sırları, şifreli bir anahtar-değer deposudur. Değerler, beklerken ve TLS üzerinden iletilirken şifrelenir, Buildkite sunucularında şifresi çözülür ve her kümenin kendi şifreleme anahtarına sahip olduğu küme başına kapsamlıdır. Hem Buildkite tarafından barındırılan hem de kendi kendine barındırılan aracılarla çalışır. Günlüklerinizde görünen herhangi bir gizli değer otomatik olarak gizlenir.
Depolanmış bir sırrı kullanmanın iki yolu vardır. Birincisi, bir komut adımındaki secrets: anahtarıdır. En basit liste biçiminde, ortam değişkeni adı sır anahtarıyla eşleşir:
steps:
- command: |
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
secrets:
- APIDOG_ACCESS_TOKEN
Depolanan sırrınız istediğiniz ortam değişkeninden farklı bir ada sahipse, hash formunu kullanın. Anahtar, ortam değişkeni adıdır ve değer, sırrın anahtarıdır:
steps:
- command: |
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
secrets:
APIDOG_ACCESS_TOKEN: apidog_token # env var name : Buildkite secret key
İkinci yol, aracı CLI ile betiğinizin içinde sırrı zorunlu olarak getirmektir. Bu, değerin tam olarak ne zaman okunacağını kontrol etmek istediğinizde kullanışlıdır:
APIDOG_ACCESS_TOKEN="$(buildkite-agent secret get apidog_token)"
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
Buildkite sırları tek seçeneğiniz değildir. Kendi kendine barındırılan aracılarda, her işin başlangıcında çalışan ve değerleri ortama aktaran bir environment aracı kancası kullanabilirsiniz. $BUILDKITE_PIPELINE_SLUG veya $BUILDKITE_STEP_KEY gibi değişkenlere dayanarak bir sırrın yalnızca doğru işler için yüklenmesini sağlayabilirsiniz. Ayrıca AWS Secrets Manager, HashiCorp Vault veya GCP gibi harici depolardan Buildkite eklentileri aracılığıyla çekebilirsiniz, bu durumda sır asla Buildkite'a depolanmaz veya gönderilmez.
Düz env: değerleri hassas olmayan yapılandırmalar için uygundur, ancak jetonları oraya koymayın. Jetonun gizli depolamanızdan CLI'ya nasıl aktığı hakkında daha fazla ayrıntı için Apidog CLI kimlik doğrulama kılavuzuna bakın.
HTML Raporunu Yapıt Olarak Yükleme
-r html raporlayıcısı, bir HTML raporunu aracı çalışma alanındaki yerel bir yola yazar. Bu dosya, kaydetmediğiniz sürece iş bittiğinde kaybolur. buildkite-agent artifact upload komutu onu korur.
buildkite-agent artifact upload "apidog-reports/**/*"
Glob kalıbının etrafındaki tırnak işaretleri önemlidir. Bunlar, kabuğunuzun kalıbı aracı görmeden önce genişletmesini durdurur, böylece aracı eşleştirmeyi kendisi yapar. Yüklenen yapıtlar varsayılan olarak Buildkite tarafından yönetilen depolamaya gider; 6 aylık saklama süresi ve yapıt başına 5 GB sınırı vardır. Bunları başka bir yere göndermek isterseniz ikinci bir argüman olarak bir hedef geçirebilirsiniz.
Bir derleme çalıştıktan sonra, rapor derlemenin Yapıtlar sekmesinde görünür. Derlemeyi inceleyen herkes indirebilir ve hangi doğrulamaların geçtiğini veya başarısız olduğunu görebilir. Rapor formatlarını önce anlamak isterseniz, Apidog CLI test raporları kılavuzu CLI, HTML ve JSON çıktılarını kapsar.
Ortamlar Arasında Testleri Paralel Çalıştırma
Aynı paketin birkaç ortama karşı aynı anda çalışmasını istediğinizde bir matrix kullanın. Buildkite, bir adım tanımını matris değeri başına bir işe genişletir ve bunlar paralel olarak çalışır.
steps:
- label: ":test_tube: API tests {{matrix.env}}"
command: |
npm install -g apidog-cli
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e "{{matrix.env}}" -r html,cli
buildkite-agent artifact upload "apidog-reports/**/*"
secrets:
- APIDOG_ACCESS_TOKEN
matrix:
setup:
env:
- "358171" # staging environment id
- "358172" # production environment id
Burada {{matrix.env}}, hem etikete hem de -e bayrağına ikame edilir, böylece her iş farklı bir Apidog ortamını hedefler. Yalnızca tek bir işin özdeş kopyalarını yaymak istiyorsanız, bir matris yerine adımda parallelism: 5 ayarlayın.
Bir senaryonun bir CSV veya JSON dosyasının satırları üzerinde yineleme yaptığı veri odaklı çalıştırmalar için, Apidog CLI bunu Buildkite matrisi yerine kendi -d bayrağıyla ele alır. Apidog CLI veri odaklı test kılavuzu, bir veri dosyasının bir senaryoya nasıl besleneceğini gösterir.
Dağıtımı Testlerin Arkasına Kilitleme
Yaygın bir şekil şöyledir: testleri çalıştır, bitmelerini bekle, bir insandan onay iste, ardından dağıt. Buildkite bunu wait ve block adımlarıyla modeller.
steps:
- label: ":test_tube: API tests"
command: "npm install -g apidog-cli && apidog run --access-token \"$APIDOG_ACCESS_TOKEN\" -t 637132 -e 358171 -r html,cli"
secrets:
- APIDOG_ACCESS_TOKEN
- wait
- block: ":rocket: Deploy?"
branches: "main"
- label: ":rocket: Deploy"
command: "scripts/deploy.sh"
wait adımı, testler tamamlanana kadar işlem hattını bekletir. block adımı manuel bir tıklama için duraklatılır ve branches: ile main dalıyla sınırlıdır. Yalnızca birisi onayladıktan sonra dağıtım adımı çalışır. Bu, başarısız bir test paketinin üretime ulaşmasını engeller. Bununla ilgili daha geniş kalıplar için, API testi için CI/CD en iyi uygulamalarımıza bakın.
Özet Açıklama Ekleme
Derleme günlükleri uzundur. Bir açıklama (annotation), derleme sayfasının en üstüne kısa, biçimlendirilmiş bir özet yerleştirir. Bunu, markdown'ı buildkite-agent annotate komutuna yönlendirerek oluşturursunuz.
cat << 'EOF' | buildkite-agent annotate --style "success" --context "apidog"
### API test sonuçları
Tüm Apidog senaryoları geçti. [HTML raporunun tamamını indirin](artifact://apidog-reports/index.html)
EOF
--style bayrağı, info, warning, error ve success değerleriyle rengi ve simgeyi kontrol eder. --context bayrağı açıklamaya benzersiz bir kimlik verir, böylece aynı bağlama sahip sonraki bir adım yeni bir açıklama eklemek yerine aynı açıklamayı günceller. artifact:// bağlantısı, inceleyenleri doğrudan yüklenen HTML raporuna yönlendirir.
Apidog'un Yeri
Yukarıdaki işlem hattı bilerek kısadır. Testleri yazma ve sürdürme gibi ağır işler YAML'de değil, Apidog'da gerçekleşir.
Apidog, API'ları tasarlamak, hata ayıklamak, test etmek, taklit etmek ve belgelemek için hepsi bir arada bir API platformudur. Test senaryolarını görsel bir düzenleyicide oluşturursunuz: istekleri zincirleme, adımlar arasında veri aktarma ve betik yazmadan doğrulama ekleme. Senaryolar Apidog projenizde yaşadığı için, ekibiniz bunları tek bir yerden düzenler ve dal desteğiyle sürüm kontrolünü yapar.
CLI, CI'a köprüdür. Bir senaryoyu bir kez oluşturur, senaryo ve ortam kimliklerini alırsınız ve tüm CI entegrasyonu tek bir apidog run komutudur. Apidog'da bir testi güncellediğinizde, bir sonraki Buildkite derlemesi YAML düzenlemesi olmadan değişikliği alır. Bu tek komut özelliği, Apidog'u Buildkite, GitHub Actions veya başka herhangi bir sisteme sorunsuz bir şekilde entegre etmesini sağlar. Aynı komutu diğer platformlarda Apidog CLI CI/CD işlem hattı kılavuzunda ve GitHub Actions ile Apidog CLI rehberinde ele alıyoruz.
CI'a herhangi bir şey bağlamadan önce, önce kendi makinenizden denemek için jetonunuzla aynı komutu yerel olarak çalıştırın:
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r cli,html
Apidog'u ücretsiz indirin, bir test senaryosu oluşturun ve tek satırlık apidog run komutunu Buildkite işlem hattınıza ekleyin.
Sıkça Sorulan Sorular
Buildkite Nedir?
Buildkite, hibrit tasarıma sahip bir CI/CD platformudur. Barındırılan bir kontrol düzlemi, gösterge panelini çalıştırır ve derlemeleri düzenlerken, aracılar gerçek işleri yürütür. Aracılar kendi altyapınızda veya Buildkite tarafından barındırılan işlem gücünde çalışabilir. Benzer bir isme sahip ayrı bir görüntü oluşturma aracı olan Docker BuildKit ile ilgisi yoktur.
Buildkite Ne İçin Kullanılır?
Ekipler Buildkite'ı kod değişiklikleriyle tetiklenen işleri otomatikleştirmek için kullanır: yapıtları derleme, testleri çalıştırma ve dağıtım yapma. Ekiplerin derlemelerinin kendi donanımlarında veya kendi ağları içinde çalışmasını istediği durumlarda yaygındır. API ekipleri için, hazırlık (staging) ve üretim ortamlarına karşı otomatik testler çalıştırır ve testler başarısız olduğunda bir dağıtımı engelleyebilir.
Buildkite Açık Kaynak mı?
Buildkite aracısı (agent) açık kaynaklıdır. Go dilinde yazılmış ve MIT Lisansı altında yayınlanmıştır, kaynak kodu GitHub'dadır. Aracının etrafındaki platform ve kontrol düzlemi ticari bir SaaS ürünüdür, bu nedenle yalnızca aracının kendisi açık kaynaktır.
Buildkite Ücretsiz mi?
Evet, Buildkite'ın Personal adlı ücretsiz bir planı vardır. Kredi kartı ve son kullanma tarihi olmaksızın 0 $ maliyetlidir. 3 eşzamanlı iş, 1 kullanıcı, 90 günlük saklama, ayda 500 Linux barındırılan aracı dakikası ve ayda 50.000 test yürütmesi içerir. Ayrıca ücretli özellikleri değerlendirmek için 30 günlük bir Tüm Erişim denemesi de bulunmaktadır.
Buildkite'ta Yapıtları Nasıl Yüklersiniz?
Bir komut adımının içinde buildkite-agent artifact upload "<pattern>" komutunu çalıştırırsınız. Glob kalıbını tırnak içine alın ki kabuk yerine aracı eşleştirsin. Dosyalar varsayılan olarak Buildkite tarafından yönetilen depolamaya gider; 6 aylık saklama süresi ve yapıt başına 5 GB sınırı vardır. API testleri için, HTML raporunu yüklersiniz, böylece inceleyenler bunu derlemenin Yapıtlar sekmesinden açabilir.
Buildkite İşlem Hattında API Testlerini Nasıl Çalıştırırsınız?
Apidog CLI'yı npm install -g apidog-cli ile kuran, ardından bir test senaryosu kimliği, -e aracılığıyla bir ortam kimliği ve raporlar için -r html,cli ile apidog run komutunu çalıştıran bir komut adımını .buildkite/pipeline.yml dosyasına ekleyin. Erişim jetonunuzu bir Buildkite sırrı aracılığıyla geçirin ve derleme sonrası sonuçların kalıcı olması için HTML raporunu buildkite-agent artifact upload ile yükleyin.