Anda menjalankan tes API otomatis di Buildkite dengan mendefinisikan langkah perintah di .buildkite/pipeline.yml yang menginstal Apidog CLI, menjalankan apidog run terhadap suatu lingkungan, dan mengunggah laporan HTML sebagai artefak build. Panduan ini menjelaskan seluruh pipeline, termasuk bagaimana Buildkite menangani rahasia agar token akses Apidog Anda tidak pernah bocor ke log. Kami berasumsi tes Apidog Anda sudah ada; Anda membuatnya secara visual sekali, lalu menjalankannya dari satu perintah di CI.
Satu klarifikasi singkat sebelum kita mulai. Buildkite adalah platform CI/CD. Ini tidak sama dengan Docker BuildKit, backend pembangunan citra di dalam Docker. Nama-nama tersebut terlihat mirip, tetapi merupakan produk yang tidak terkait. Artikel ini sepenuhnya tentang Buildkite, platform CI/CD.
Apa Itu Buildkite
Buildkite adalah platform CI/CD yang dibangun di sekitar model hibrida. Ia memiliki bidang kontrol yang di-host (hosted control plane), dasbor dan orkestrasi build yang Anda lihat di browser Anda, serta agen yang benar-benar menjalankan tugas Anda.
Pemisahan ini penting. Bidang kontrol menjadwalkan pekerjaan, tetapi pekerjaan tersebut berjalan pada agen. Anda dapat meng-host sendiri agen di infrastruktur atau cloud Anda sendiri, atau Anda dapat menggunakan agen yang di-host oleh Buildkite, yang merupakan komputasi terkelola yang dijalankan Buildkite untuk Anda.
Ini adalah hal utama yang membedakan Buildkite dari sistem CI yang di-host sepenuhnya. Kode dan rahasia Anda dapat tetap berada di mesin Anda sendiri sementara Buildkite mengoordinasikan build. Untuk pengujian API, itu berarti tes Anda berjalan di tempat layanan dan akses jaringan Anda sudah ada.
Agen Buildkite itu sendiri adalah sumber terbuka. Ia ditulis dalam Go dan dirilis di bawah Lisensi MIT, dengan kode sumbernya di GitHub. Platform dan bidang kontrol di sekitarnya adalah produk SaaS komersial.
Untuk Apa Buildkite Digunakan
Tim menggunakan Buildkite untuk menjalankan segala jenis tugas otomatis yang dipicu oleh perubahan kode: membangun artefak, menjalankan tes unit dan integrasi, menyebarkan layanan, dan menjalankan pemeriksaan end-to-end. Karena agen dapat berjalan di perangkat keras Anda sendiri, ini umum di tim yang membutuhkan kontrol atas komputasi, batas jaringan, atau perangkat keras seperti GPU.
Pengujian API sangat cocok dengan ini. Anda ingin tes Anda mengenai lingkungan staging atau pengujian, memverifikasi respons yang sebenarnya, dan memblokir penyebaran ketika suatu kontrak rusak. Buildkite memberi Anda jenis langkah untuk memodelkan alur tersebut, yang akan kita gunakan di bawah.
Jika Anda menimbang Buildkite terhadap opsi lain, rangkuman kami tentang alat integrasi berkelanjutan terbaik untuk tim API mencakup perbandingan beberapa platform untuk kasus penggunaan ini.
Bagaimana Pipeline Buildkite Didefinisikan
Pipeline Buildkite adalah daftar langkah-langkah. Tempat default untuk mendefinisikannya adalah file di .buildkite/pipeline.yml di repositori Anda. Ketika build dimulai, Buildkite mencari direktori bernama .buildkite yang berisi file bernama pipeline.yml. Direktori buildkite/ yang tidak tersembunyi di root repo juga berfungsi.
Kunci tingkat atas adalah steps:, dan ia menampung sebuah daftar. Jenis langkah yang paling sering Anda gunakan untuk pengujian API adalah ini:
- Langkah perintah (Command steps) menjalankan perintah shell pada agen. Di sinilah tes Anda berjalan.
- Langkah tunggu (Wait steps) menjeda pipeline sampai setiap langkah sebelumnya selesai. Anda menuliskannya sebagai item daftar
- waitsederhana. - Langkah blokir (Block steps) membuat gerbang persetujuan manual, ditulis sebagai
- block: "Label". Manusia mengeklik untuk melanjutkan, yang berguna sebelum penyebaran ke produksi.
Langkah perintah mendukung serangkaian kunci yang sering Anda gunakan: label dan key untuk penamaan dan referensi, command atau commands untuk skrip, env untuk variabel lingkungan, agents untuk penargetan, secrets untuk menyuntikkan nilai rahasia, artifact_paths untuk file yang akan disimpan, parallelism untuk fan-out, dan matrix untuk menjalankan langkah yang sama di seluruh kumpulan nilai.
Kunci agents adalah hash pasangan tag. Anda menggunakannya untuk mengarahkan langkah ke agen yang tepat, misalnya queue: "tests". Tag memungkinkan Anda menyimpan tugas pengujian pada agen yang memiliki akses jaringan atau peralatan yang tepat.
Pipeline Salin-Tempel yang Menjalankan Tes API
Berikut adalah .buildkite/pipeline.yml minimal yang menginstal Apidog CLI, menjalankan skenario pengujian terhadap suatu lingkungan, dan mengunggah laporan HTML. Apidog CLI adalah alat Node.js yang menjalankan skenario pengujian Apidog Anda dari baris perintah.
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
Beberapa catatan tentang flag. -t adalah ID skenario pengujian atau direktori skenario yang ingin Anda jalankan. -e adalah ID lingkungan runtime, yang memilih URL dasar dan variabel yang digunakan tes Anda. -r html,cli meminta ringkasan terminal yang mudah dibaca manusia dan file laporan HTML. --access-token meneruskan token Apidog Anda agar CLI dapat mengakses proyek Anda.
Host agen Buildkite sudah memiliki biner buildkite-agent, karena itulah yang menjalankan tugas. Anda hanya menginstal apidog-cli sendiri. Untuk tinjauan lebih dalam tentang setiap flag, lihat panduan lengkap Apidog CLI.
Jika Anda ingin panduan langkah demi langkah untuk menjalankan satu API dari terminal terlebih dahulu, tutorial pengujian baris perintah Apidog CLI adalah pemanasan yang baik sebelum mengintegrasikannya ke CI.
Meneruskan Token Akses Apidog dengan Rahasia Buildkite
Token akses Apidog Anda adalah kredensial. Seharusnya tidak pernah berada di pipeline.yml Anda atau dicetak ke log build. Buildkite memberi Anda fitur asli untuk ini yang disebut rahasia Buildkite (Buildkite secrets).
Rahasia Buildkite (Buildkite secrets) adalah penyimpanan kunci-nilai terenkripsi. Nilai-nilai dienkripsi saat tidak aktif dan saat dalam perjalanan melalui TLS, didekripsi di server Buildkite, dan dicakup per klaster, di mana setiap klaster memiliki kunci enkripsinya sendiri. Ini berfungsi dengan agen yang di-host Buildkite maupun yang di-host sendiri. Setiap nilai rahasia yang muncul di log Anda akan otomatis disunting.
Ada dua cara untuk menggunakan rahasia yang tersimpan. Yang pertama adalah kunci secrets: pada langkah perintah. Dalam bentuk daftar paling sederhananya, nama variabel lingkungan cocok dengan kunci rahasia:
steps:
- command: |
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
secrets:
- APIDOG_ACCESS_TOKEN
Jika rahasia yang Anda simpan memiliki nama yang berbeda dari variabel lingkungan yang Anda inginkan, gunakan bentuk hash. Kunci adalah nama variabel lingkungan dan nilai adalah kunci rahasia:
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
Cara kedua adalah mengambil rahasia secara imperatif di dalam skrip Anda dengan CLI agen. Ini berguna ketika Anda ingin mengontrol kapan nilai tersebut dibaca:
APIDOG_ACCESS_TOKEN="$(buildkite-agent secret get apidog_token)"
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r html,cli
Rahasia Buildkite (Buildkite secrets) bukanlah satu-satunya pilihan Anda. Pada agen yang di-host sendiri, Anda dapat menggunakan environment agent hook, sebuah skrip yang berjalan di awal setiap tugas dan mengekspor nilai ke lingkungan. Anda dapat mengontrolnya berdasarkan variabel seperti $BUILDKITE_PIPELINE_SLUG atau $BUILDKITE_STEP_KEY sehingga rahasia hanya dimuat untuk tugas yang tepat. Anda juga dapat menarik dari penyimpanan eksternal seperti AWS Secrets Manager, HashiCorp Vault, atau GCP melalui plugin Buildkite, dalam hal ini rahasia tidak pernah disimpan atau dikirim ke Buildkite.
Nilai env: biasa baik untuk konfigurasi non-sensitif, tetapi jangan letakkan token di sana. Untuk detail lebih lanjut tentang bagaimana token mengalir dari penyimpanan rahasia Anda ke CLI, lihat panduan autentikasi Apidog CLI.
Mengunggah Laporan HTML sebagai Artefak
Reporter -r html menulis laporan HTML ke jalur lokal di ruang kerja agen. File tersebut akan hilang ketika tugas berakhir kecuali Anda menyimpannya. Perintah buildkite-agent artifact upload akan menyimpannya.
buildkite-agent artifact upload "apidog-reports/**/*"
Tanda kutip di sekitar pola glob itu penting. Tanda kutip tersebut menghentikan shell Anda memperluas pola sebelum agen melihatnya, sehingga agen melakukan pencocokan sendiri. Artefak yang diunggah secara default masuk ke penyimpanan yang dikelola Buildkite, dengan jendela retensi 6 bulan dan batas 5GB per artefak. Anda dapat meneruskan tujuan sebagai argumen kedua jika Anda ingin mengirimnya ke tempat lain.
Setelah build berjalan, laporan muncul di bawah tab Artefak build. Siapa pun yang meninjau build dapat mengunduhnya dan melihat penegasan mana yang berhasil atau gagal. Jika Anda ingin memahami format laporan terlebih dahulu, panduan laporan tes Apidog CLI mencakup output CLI, HTML, dan JSON.
Menjalankan Tes Secara Paralel di Berbagai Lingkungan
Ketika Anda ingin rangkaian tes yang sama berjalan di beberapa lingkungan sekaligus, gunakan matrix. Buildkite memperluas satu definisi langkah menjadi satu tugas per nilai matriks, dan semuanya berjalan secara paralel.
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
Di sini {{matrix.env}} disubstitusikan ke label dan flag -e, sehingga setiap tugas menargetkan lingkungan Apidog yang berbeda. Jika Anda hanya ingin menyebarkan salinan identik dari satu tugas, atur parallelism: 5 pada langkah tersebut alih-alih matriks.
Untuk eksekusi berbasis data, di mana satu skenario mengulang baris file CSV atau JSON, Apidog CLI menanganinya dengan flag -d sendiri daripada matriks Buildkite. Panduan pengujian berbasis data Apidog CLI menunjukkan cara memasukkan file data ke dalam skenario.
Menjaga Penyebaran di Balik Tes
Bentuk umum adalah: jalankan tes, tunggu hingga selesai, minta persetujuan manusia, lalu sebarkan. Buildkite memodelkan ini dengan langkah wait dan block.
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"
Langkah wait menahan pipeline hingga tes selesai. Langkah block menjeda untuk klik manual dan dibatasi pada cabang main dengan branches:. Hanya setelah seseorang menyetujui, langkah penyebaran berjalan. Ini mencegah rangkaian tes yang gagal mencapai produksi. Untuk pola yang lebih luas mengenai hal ini, lihat praktik terbaik CI/CD kami untuk pengujian API.
Menambahkan Anotasi Ringkasan
Log build itu panjang. Anotasi menempatkan ringkasan singkat dan terformat di bagian atas halaman build. Anda membuatnya dengan mengalirkan markdown ke buildkite-agent annotate.
cat << 'EOF' | buildkite-agent annotate --style "success" --context "apidog"
### Hasil tes API
Semua skenario Apidog berhasil. [Unduh laporan HTML lengkap](artifact://apidog-reports/index.html)
EOF
Flag --style mengontrol warna dan ikon, dengan nilai info, warning, error, dan success. Flag --context memberikan ID unik pada anotasi, sehingga langkah selanjutnya dengan konteks yang sama memperbarui anotasi yang sama alih-alih menambahkan yang baru. Tautan artifact:// mengarahkan peninjau langsung ke laporan HTML yang diunggah.
Di Mana Apidog Cocok
Pipeline di atas sengaja dibuat singkat. Pekerjaan berat menulis dan memelihara tes terjadi di Apidog, bukan di YAML.
Apidog adalah platform API all-in-one untuk merancang, men-debug, menguji, melakukan mocking, dan mendokumentasikan API. Anda membangun skenario pengujian di editor visual: merangkai permintaan, meneruskan data antar langkah, dan menambahkan penegasan tanpa menulis skrip. Karena skenario berada di proyek Apidog Anda, tim Anda mengeditnya di satu tempat dan mengontrol versinya dengan dukungan cabang.
CLI adalah jembatan menuju CI. Anda membangun skenario sekali, mengambil ID skenario dan lingkungannya, dan seluruh integrasi CI adalah satu perintah apidog run. Ketika Anda memperbarui tes di Apidog, build Buildkite berikutnya mengambil perubahan tanpa editan YAML. Properti satu perintah itulah yang membuat Apidog dapat masuk dengan rapi ke Buildkite, GitHub Actions, atau sistem lainnya. Kami membahas perintah yang sama di platform lain dalam panduan pipeline CI/CD Apidog CLI dan panduan Apidog CLI dengan GitHub Actions.
Untuk mencobanya dari mesin Anda sendiri terlebih dahulu, sebelum mengintegrasikan apa pun ke CI, jalankan perintah yang sama secara lokal dengan token Anda:
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 637132 -e 358171 -r cli,html
Unduh Apidog secara gratis, bangun skenario pengujian, dan masukkan perintah apidog run satu baris ke dalam pipeline Buildkite Anda.
Pertanyaan yang Sering Diajukan
Apa itu Buildkite?
Buildkite adalah platform CI/CD dengan desain hibrida. Bidang kontrol yang di-host menjalankan dasbor dan mengorkestrasi build, sementara agen menjalankan tugas yang sebenarnya. Agen dapat berjalan di infrastruktur Anda sendiri atau pada komputasi yang di-host Buildkite. Ini tidak terkait dengan Docker BuildKit, yang merupakan alat pembangunan citra terpisah yang kebetulan memiliki nama yang mirip.
Untuk Apa Buildkite Digunakan?
Tim menggunakan Buildkite untuk mengotomatiskan tugas yang dipicu oleh perubahan kode: membangun artefak, menjalankan tes, dan menyebarkan. Ini umum di mana tim ingin build mereka berjalan di perangkat keras mereka sendiri atau di dalam jaringan mereka sendiri. Untuk tim API, ini menjalankan tes otomatis terhadap lingkungan staging dan produksi dan dapat memblokir penyebaran ketika tes gagal.
Apakah Buildkite Sumber Terbuka?
Agen Buildkite adalah sumber terbuka. Ia ditulis dalam Go dan dirilis di bawah Lisensi MIT, dengan kode sumbernya di GitHub. Platform dan bidang kontrol di sekitar agen adalah produk SaaS komersial, jadi hanya agen itu sendiri yang sumber terbuka.
Apakah Buildkite Gratis?
Ya, Buildkite memiliki paket gratis yang disebut Personal. Biayanya $0 tanpa kartu kredit dan tanpa kedaluwarsa. Ini mencakup 3 tugas bersamaan, 1 pengguna, retensi 90 hari, 500 menit agen yang di-host Linux per bulan, dan 50.000 eksekusi tes per bulan. Ada juga uji coba All Access 30 hari untuk mengevaluasi fitur berbayar.
Bagaimana Cara Mengunggah Artefak di Buildkite?
Anda menjalankan buildkite-agent artifact upload "<pattern>" di dalam langkah perintah. Beri tanda kutip pada pola glob agar agen yang mencocorkannya, bukan shell. File secara default masuk ke penyimpanan yang dikelola Buildkite, dengan retensi 6 bulan dan batas 5GB per artefak. Untuk tes API, Anda mengunggah laporan HTML agar peninjau dapat membukanya dari tab Artefak build.
Bagaimana Cara Menjalankan Tes API di Pipeline Buildkite?
Tambahkan langkah perintah ke .buildkite/pipeline.yml yang menginstal Apidog CLI dengan npm install -g apidog-cli, lalu jalankan apidog run dengan ID skenario tes, ID lingkungan melalui -e, dan -r html,cli untuk laporan. Teruskan token akses Anda melalui rahasia Buildkite, dan unggah laporan HTML dengan buildkite-agent artifact upload agar hasilnya tetap ada setelah build.