Cara Menjalankan Tes API Otomatis di Bamboo CI (Langkah demi Langkah)

Build Anda hijau. Unit test lolos, JAR telah dikemas, artefak telah di-deploy. Lalu permintaan nyata pertama mencapai API staging dan layanan hilir mengembalikan kode 500 karena seseorang mengubah bidang respons dua commit yang lalu. Build mengatakan semuanya baik-baik saja. Ternyata tidak. Ia hanya tidak pernah memeriksa API.

Inilah celah yang dimiliki sebagian besar pipeline Bamboo CI. Atlassian Bamboo sangat baik dalam mengompilasi kode, menjalankan suite JUnit, dan mengirimkan artefak. Yang tidak dilakukannya sendiri adalah memverifikasi bahwa endpoint HTTP Anda masih berfungsi seperti yang dijanjikan kontrak Anda. Jika Anda menginginkan jaring pengaman itu, Anda harus menambahkan pengujian API otomatis sebagai tahap dalam pipeline. Panduan ini menjelaskan dengan tepat cara melakukannya, menggunakan Apidog untuk membangun pengujian dan Apidog CLI untuk menjalankannya di dalam pekerjaan Bamboo.

Pada akhirnya, Anda akan memiliki rencana Bamboo yang, pada setiap push, mengenai endpoint Anda, memeriksa kode status, memvalidasi body respons terhadap skema Anda, dan menggagalkan build saat kontrak rusak. Tidak ada lisensi Postman per kursi, tidak ada skrip asersi yang ditulis tangan untuk dipelihara, dan laporan pengujian HTML nyata yang dilampirkan pada setiap build. Unduh Apidog jika Anda ingin mengikuti; bagian CLI gratis dan terbuka.

tombol

Mengapa pengujian API harus ada di Bamboo, bukan setelahnya

Banyak tim menguji API mereka secara manual, atau lebih buruk lagi, di lingkungan produksi. Seseorang mengklik serangkaian permintaan yang tersimpan sebelum rilis dan melihat responsnya. Itu berfungsi sampai tidak berfungsi lagi. Orang-orang lupa. Rilis terjadi pada hari Jumat. Satu-satunya endpoint yang tidak terpikirkan untuk diperiksa ulang adalah endpoint yang rusak.

CI ada untuk menghilangkan variabel manusia itu. Inti dari server build adalah bahwa pemeriksaan yang sama dijalankan dengan cara yang sama setiap saat, secara otomatis, tanpa ada yang perlu mengingat untuk menjalankannya. Unit test Anda sudah ada di sana. Integration test Anda mungkin juga demikian. Pengujian API pantas mendapatkan perlakuan yang sama, dan untuk beberapa alasan konkret:

Kontrak rusak secara diam-diam. Seorang pengembang backend mengganti nama bidang JSON dari userId menjadi user_id. Unit test masih lolos karena mereka menguji fungsi, bukan format kawat. Tim seluler baru mengetahuinya tiga hari kemudian. Pengujian API yang menegaskan pada body respons akan menangkapnya di build yang sama yang memperkenalkannya.
Kode status berbohong saat tidak ada yang memperhatikan. Sebuah endpoint yang seharusnya mengembalikan 201 Created mulai mengembalikan 200 OK setelah refactor. Secara fungsional dekat, secara teknis salah, dan klien yang ketat akan menolaknya. Asersi pipeline menandai ini dalam hitungan detik.
Regresi otentikasi mahal. Alur token-refresh yang salah konfigurasi yang mengembalikan 401 pada kredensial yang valid adalah jenis bug yang menjatuhkan layar login. Menjalankan permintaan terotentikasi pada setiap build berarti Anda menemukannya sebelum pengguna Anda.
Lingkungan bergeser. Staging mengalami perubahan konfigurasi, feature flag berbalik, dependensi di-upgrade. Menjalankan suite API yang sama terhadap staging setelah setiap deploy memberi tahu Anda segera apakah lingkungan masih sehat.

Konteks yang lebih dalam adalah alasan yang sama mengapa tim mengadopsi CI/CD sejak awal: tangani masalah lebih awal, saat biaya perbaikannya murah, daripada terlambat, saat biayanya mahal dan memalukan. Pengujian API hanyalah lapisan strategi yang dilewati sebagian besar pipeline.

Bagaimana pengujian API masuk ke dalam rencana Bamboo

Sebelum langkah-demi-langkah, ada baiknya memahami di mana ini berada dalam model Bamboo. Bamboo mengatur pekerjaan menjadi rencana (plan), dan setiap rencana berisi satu atau lebih tahap (stage) yang berjalan secara berurutan. Setiap tahap memiliki pekerjaan (job), dan setiap pekerjaan adalah urutan tugas (task). Tugas adalah perintah sebenarnya: checkout, kompilasi, jalankan skrip.

Pengujian API Anda menjadi tugas di dalam pekerjaan di dalam tahap. Penempatan alami adalah tahap khusus yang berjalan setelah aplikasi Anda dibangun dan di-deploy ke lingkungan pengujian, karena Anda memerlukan sesuatu yang aktif untuk mengirim permintaan. Rencana tipikal akan terlihat seperti ini:

Plan: payments-service
├── Tahap: Build
│   └── Pekerjaan: Kompilasi & Unit Test
│       ├── Tugas: Checkout Kode Sumber
│       └── Tugas: Maven, clean package
├── Tahap: Deploy ke Staging
│   └── Pekerjaan: Deploy
│       └── Tugas: Deploy artefak ke staging
└── Tahap: Pengujian API          <- inilah yang Anda tambahkan
    └── Pekerjaan: Jalankan Suite API
        ├── Tugas: Checkout Kode Sumber
        ├── Tugas: Skrip, instal & jalankan Apidog CLI
        └── Tugas: Final, publikasikan laporan pengujian

Jika tugas di tahap Pengujian API keluar dengan kode non-nol, Bamboo menandai tahap tersebut sebagai gagal dan seluruh build menjadi merah. Itulah perilaku yang Anda inginkan; kontrak yang rusak harus menghentikan baris, bukan lolos begitu saja.

Alat yang melakukan pekerjaan sebenarnya dalam tugas skrip itu adalah Apidog CLI, sebuah command-line runner yang mengeksekusi skenario pengujian yang Anda rancang secara visual di Apidog. Anda membangun pengujian sekali, di GUI, tanpa kode, dan pengujian yang sama berjalan tidak berubah di terminal Anda dan di Bamboo. Ini adalah pola yang sama yang digunakan tim untuk mengotomatisasi pengujian API di seluruh sistem CI/CD mana pun; Bamboo adalah salah satu target di antara banyak lainnya.

Langkah 1: Bangun pengujian API Anda di Apidog

Anda tidak dapat menjalankan pengujian di CI sampai Anda memiliki pengujian. Apidog adalah tempat Anda merancangnya, dan desainnya visual, sehingga insinyur QA yang tidak menulis kode dapat membangun suite yang sama seperti yang akan dibuat oleh pengembang backend.

Buka Apidog dan buat skenario pengujian. Skenario adalah urutan permintaan API yang berurutan, dijalankan dari atas ke bawah, di mana setiap langkah dapat menggunakan kembali data dari langkah-langkah sebelumnya. Skenario realistis untuk layanan pembayaran mungkin adalah:

POST /auth/login dengan kredensial yang valid, lalu ekstrak token bearer dari respons.
POST /orders menggunakan token itu, membuat pesanan baru, lalu simpan orderId yang dikembalikan.
GET /orders/{orderId} dan konfirmasikan pesanan muncul dengan status yang benar.
DELETE /orders/{orderId} untuk membersihkan.

Untuk setiap permintaan, tambahkan asersi. Ini adalah bagian yang mengubah permintaan menjadi pengujian. Apidog memungkinkan Anda melakukan asersi secara visual, tanpa memerlukan skrip:

Kode status sama dengan 200 (atau 201, sesuai kontrak).
Bidang JSON ada dan cocok: $.data.status sama dengan "pending".
Respons memvalidasi terhadap skema OpenAPI endpoint, sehingga setiap jenis bidang yang tidak terduga atau properti wajib yang hilang akan menggagalkan langkah tersebut.
Waktu respons tetap di bawah ambang batas, misalnya 800ms, sehingga regresi yang lambat juga akan muncul.

Asersi berbasis skema patut disoroti. Karena Apidog mengutamakan skema, ia sudah mengetahui bentuk yang dijanjikan endpoint Anda dalam definisi API-nya. Anda dapat menegaskan "respons ini cocok dengan skemanya" dalam satu klik, dan pemeriksaan tunggal itu melindungi dari seluruh kategori penyimpangan kontrak, bidang yang diganti namanya, tipe yang salah, properti yang dihapus, tanpa Anda menulis satu baris pun. Jika Anda berasal dari alat yang sangat mengandalkan skrip, ini saja menghilangkan banyak pemeliharaan. Ini adalah model asersi visual yang sama yang menjadikan Apidog sebagai alternatif Postman umum untuk pengujian API.

Kelompokkan skenario terkait ke dalam suite pengujian jika Anda memiliki banyak. Suite hanyalah kumpulan skenario yang dapat Anda jalankan bersama, yang membuat perintah CI Anda sederhana; Anda mengarahkan runner ke satu suite alih-alih mencantumkan dua puluh skenario.

Gunakan variabel lingkungan untuk apa pun yang berubah antara lokal, staging, dan produksi: URL dasar, kredensial, kunci API. Definisikan lingkungan staging di Apidog dengan baseUrl diatur ke host staging Anda. Anda akan memberi tahu CLI lingkungan mana yang akan digunakan saat dijalankan, sehingga skenario yang sama persis berjalan terhadap staging di Bamboo dan terhadap localhost di laptop Anda.

Langkah 2: Hasilkan token akses Apidog dan dapatkan ID-nya

Bamboo berjalan headless pada agen build. Ia tidak dapat masuk ke akun Apidog Anda melalui browser, jadi CLI melakukan otentikasi dengan token akses sebagai gantinya.

Di dalam skenario pengujian Anda, buka tab CI/CD. Klik Tambahkan token akses, lalu Hasilkan token. Salin nilainya di tempat yang aman untuk sementara; Anda akan menyimpannya sebagai variabel Bamboo sebentar lagi, bukan menempelkannya ke dalam skrip. Token inilah yang memungkinkan agen build menarik dan menjalankan pengujian proyek pribadi Anda.

Saat Anda berada di tab CI/CD itu, Apidog menghasilkan perintah run lengkap untuk Anda. Pilih Command line sebagai penyedia dan itu akan mencetak sesuatu yang dapat Anda salin langsung, dengan ID skenario pengujian dan ID proyek Anda sudah terisi. Perintah yang disalin itu adalah fondasi tugas Bamboo Anda. Bagian-bagian yang Anda perhatikan:

Token akses: otentikasi, diteruskan sebagai --access-token.
ID skenario pengujian: ID numerik setelah -t, mengidentifikasi skenario mana yang akan dijalankan.
ID lingkungan: ID numerik setelah -e, memberi tahu CLI untuk berjalan melawan staging.

Simpan perintah yang dihasilkan itu dengan baik. Langkah-langkah selanjutnya akan mengadaptasinya untuk Bamboo.

Langkah 3: Simpan token sebagai variabel rencana Bamboo

Jangan pernah hard-code token ke dalam tugas skrip. Siapa pun dengan akses baca ke rencana, dan siapa pun yang membaca log build, akan melihatnya.

Di Bamboo, buka rencana Anda, buka Konfigurasi Rencana, dan temukan tab Variabel. Tambahkan variabel baru. Beri nama yang jelas seperti APIDOG_ACCESS_TOKEN dan tempelkan token sebagai nilainya. Bamboo menyembunyikan variabel yang namanya berisi password, secret, atau token, jadi beri nama yang sesuai dan nilainya akan disembunyikan di log dan UI.

Saat runtime, Bamboo mengekspos variabel rencana ke skrip sebagai variabel lingkungan, dengan awalan dan huruf besar, dengan titik menjadi garis bawah. Variabel bernama APIDOG_ACCESS_TOKEN tersedia untuk tugas shell Anda sebagai $bamboo_APIDOG_ACCESS_TOKEN. Anda akan merujuk itu, tidak pernah token mentah, dalam skrip build.

Kebersihan yang sama berlaku untuk rahasia lain yang dibutuhkan pengujian Anda; kata sandi database, kunci API pihak ketiga, rahasia penandatanganan. Definisikan sebagai variabel Bamboo yang disamarkan dan baca melalui awalan lingkungan bamboo_.

Langkah 4: Tambahkan tahap pengujian API dan tugas skrip

Sekarang hubungkan ke rencana. Di Konfigurasi Rencana, tambahkan tahap baru dan beri nama Pengujian API. Tambahkan pekerjaan ke dalamnya, lalu tambahkan tugas ke pekerjaan ini dalam urutan ini.

Tugas 1, Checkout Kode Sumber. Meskipun pengujian berada di cloud Apidog, melakukan checkout repo Anda memberi agen direktori kerja yang bersih dan memungkinkan Anda melakukan commit file data lokal apa pun (misalnya, data iterasi CSV) di samping kode Anda.

Tugas 2, Skrip. Inilah intinya. Pilih tugas Skrip, atur interpreter ke Shell (atau /bin/sh), dan gunakan body skrip inline. Skrip ini menginstal Apidog CLI pada agen dan menjalankan skenario Anda.

Apidog CLI adalah paket npm, jadi agen memerlukan Node.js v16 atau yang lebih baru. Jika agen Anda sudah memiliki Node, Anda dapat melewati baris instalasi; jika tidak, sediakan melalui kemampuan Bamboo atau agen berbasis Docker. Berikut adalah body skrip lengkap:

#!/bin/sh
set -e

# Instal Apidog CLI secara global pada agen
npm install -g apidog-cli

# Jalankan skenario pengujian terhadap staging, hasilkan laporan HTML + CLI
apidog run \
  --access-token "$bamboo_APIDOG_ACCESS_TOKEN" \
  -t 637132 \
  -e 358171 \
  -r cli,html \
  --out-dir ./apidog-reports

Ganti 637132 dengan ID skenario pengujian Anda yang sebenarnya dan 358171 dengan ID lingkungan staging Anda, nilai-nilai dari perintah Apidog yang dihasilkan pada langkah 2. Beberapa catatan tentang fungsi setiap flag:

--access-token membaca variabel Bamboo yang disamarkan, sehingga rahasia tidak pernah muncul dalam skrip.
-t (singkatan dari --test-scenario) memilih skenario yang akan dijalankan. Untuk menjalankan seluruh suite sebagai gantinya, gunakan --test-suite <id>; untuk menjalankan seluruh folder skenario, gunakan -f <folderId>.
-e (--environment) memilih lingkungan staging yang Anda definisikan di Apidog, sehingga permintaan menuju ke host yang benar dengan variabel yang benar.
-r cli,html (--reporters) menghasilkan laporan konsol yang akan Anda lihat di log build Bamboo dan laporan HTML yang dapat Anda publikasikan sebagai artefak. CLI juga mendukung format json dan junit di sini.
--out-dir mengontrol tempat laporan disimpan. Defaultnya adalah ./apidog-reports; mengaturnya secara eksplisit membuat jalur artefak dapat diprediksi.

set -e di bagian atas itu penting. Itu membuat shell keluar pada perintah pertama yang gagal. Apidog CLI sudah mengembalikan kode keluar non-nol ketika ada asersi yang gagal, dan kode non-nol itulah yang memberi tahu Bamboo untuk menggagalkan build. Bersama-sama mereka menjamin kontrak API yang rusak mengubah build menjadi merah daripada terkubur dalam log.

Jika Anda pernah mengintegrasikan pengujian API ke GitHub Actions sebelumnya, ini akan terasa familiar; runner dan flag identik, hanya wrapper YAML-versus-Bamboo-UI yang berbeda.

Langkah 5: Publikasikan laporan pengujian sebagai artefak Bamboo

Build merah memberi tahu Anda ada sesuatu yang rusak. Laporan HTML memberi tahu Anda apa yang rusak. Sambungkan sehingga setiap build menyimpan laporan.

Pada pekerjaan yang sama, buka tab Artefak dan definisikan artefak bersama yang baru:

Nama: Laporan Pengujian Apidog
Lokasi: apidog-reports
Pola salin: **/*

Setelah setiap build, Bamboo mengumpulkan semua yang ada di direktori apidog-reports dan melampirkannya ke hasil build. Buka build apa pun, buka tab Artefak, dan Anda dapat mengunduh atau melihat laporan HTML; hasil permintaan-demi-permintaan, asersi yang dijalankan, dan body respons persis untuk apa pun yang gagal. Bagian terakhir itu menghemat waktu debugging yang nyata. Alih-alih menjalankan ulang permintaan yang gagal secara manual, Anda membaca respons yang ditangkap langsung dari build.

Untuk tampilan yang lebih kaya di Bamboo, reporter junit juga berguna. Tambahkan junit ke daftar -r, lalu tambahkan tugas JUnit Parser yang mengarah ke file JUnit XML. Bamboo kemudian merender jumlah pengujian, rincian lulus/gagal, dan tren kegagalan secara native pada ringkasan build, dengan cara yang sama seperti menampilkan hasil unit test Anda.

Langkah 6: Jalankan dan baca hasilnya

Picu rencana secara manual untuk dijalankan pertama kali; di Bamboo, Jalankan rencana dari halaman rencana. Perhatikan log build untuk tahap Pengujian API. Anda akan melihat npm menginstal CLI, lalu output run Apidog mengalir, nama skenario, setiap permintaan, setiap asersi, dan baris ringkasan akhir dengan total.

Dua hasil:

Semua asersi lolos. CLI keluar dengan kode 0, tahap menjadi hijau, build berhasil, dan laporan HTML tetap dilampirkan sebagai artefak, jadi Anda memiliki catatan. Bagus. Sekarang jadikan otomatis; atur rencana untuk memicu pada setiap commit ke cabang utama Anda (Konfigurasi Rencana, Pemicu, polling Repositori atau webhook). Mulai sekarang, setiap push menjalankan suite API Anda tanpa campur tangan manusia.

Sebuah asersi gagal. CLI keluar dengan kode non-nol, set -e menghentikan skrip, tahap menjadi merah, dan build gagal. Buka artefak, temukan permintaan yang gagal, dan baca respons yang ditangkap. Mungkin ada bidang yang berubah. Mungkin staging mengembalikan 502 karena dependensi mati. Bagaimanapun Anda akan tahu dalam satu atau dua menit setelah commit yang memperkenalkannya, itulah keseluruhan imbalannya.

Ringkasan konsol yang realistis terlihat seperti ini:

┌──────────────┬──────────┬──────────┐
│              │ dieksekusi │   gagal  │
├──────────────┼──────────┼──────────┤
│   iterasi    │        1 │        0 │
├──────────────┼──────────┼──────────┤
│   permintaan │        4 │        0 │
├──────────────┼──────────┼──────────┤
│   asersi     │       11 │        1 │
└──────────────┴──────────┴──────────┘

  1 asersi gagal:
    GET /orders/{orderId}
      diharapkan $.data.status sama dengan "pending" tetapi mendapatkan "failed"

Satu asersi yang gagal itulah seluruh alasan tahap ini ada. Ini menangkap regresi kontrak yang dikompilasi dengan bersih dan lolos setiap unit test.

Membuat suite dapat diandalkan di CI

Pengujian API yang tidak stabil lebih buruk daripada tidak ada pengujian, karena melatih tim untuk mengabaikan build yang merah. Beberapa kebiasaan menjaga suite tetap dapat dipercaya.

Isolasi data pengujian. Setiap eksekusi harus membuat apa yang dibutuhkan dan membersihkan setelahnya, seperti alur pesanan buat-lalu-hapus di atas. Pengujian yang bergantung pada catatan yang dibuat seseorang pada hari Selasa lalu akan rusak saat catatan itu berubah. Jalankan terhadap lingkungan staging atau pengujian khusus, jangan pernah produksi.

Gunakan eksekusi berbasis data untuk cakupan tanpa duplikasi. Jika Anda perlu menguji endpoint yang sama dengan dua puluh input berbeda, jangan membangun dua puluh skenario. Gunakan satu skenario dengan --iteration-data path/to/data.csv (atau -d), dan CLI menjalankannya sekali per baris. Komit CSV ke repo Anda sehingga di-checkout bersama kode. Ini adalah pola pengujian berbasis data yang sama yang akan Anda gunakan secara lokal, hanya didorong dari file di CI.

Pin versi CLI. npm install -g apidog-cli mengambil yang terbaru. Untuk build yang dapat direproduksi, pin versi yang diketahui, npm install -g apidog-cli@<version>, sehingga pembaruan CLI tidak secara diam-diam mengubah perilaku antara dua build dari commit yang sama.

Atur batas waktu yang masuk akal. Tambahkan --timeout-request 10000 untuk gagal dengan cepat pada endpoint yang macet daripada membiarkan build menggantung sampai batas waktu Bamboo sendiri menghentikannya. Pesan "request timed out" yang jelas lebih baik daripada build yang macet yang tidak jelas.

Gerbang deploy pada tahap API. Karena tahap Pengujian API berjalan sebelum tahap deploy produksi mana pun, dan tahap yang gagal menghentikan rencana, kontrak yang rusak tidak dapat mencapai produksi. Urutan itu adalah gerbang rilis Anda. Ini adalah versi praktis dari membangun pipeline CI/CD nyata daripada build yang hanya mengompilasi.

Jaga skenario tetap cepat dan terfokus. Suite CI yang membutuhkan waktu dua puluh menit tidak akan berjalan pada setiap commit; orang akan memindahkannya ke eksekusi malam dan kehilangan umpan balik yang cepat. Pertahankan suite per-commit ke jalur kritis Anda, otentikasi, CRUD inti, alur pembayaran, dan jalankan suite kasus batas yang lengkap sesuai jadwal.

Ringkasan

Bamboo sudah melindungi Anda dari kode yang tidak terkompilasi dan unit test yang tidak lolos. Menambahkan tahap pengujian API memperluas perlindungan itu ke kontrak yang sebenarnya diekspos layanan Anda melalui jaringan, lapisan di mana sebagian besar insiden "tapi itu berfungsi secara lokal" sebenarnya berada.

Pengaturannya singkat: bangun pengujian visual yang sadar skema di Apidog, buat token akses, simpan sebagai variabel Bamboo yang disamarkan, dan tambahkan tugas skrip yang menjalankan apidog run dengan ID skenario dan lingkungan Anda. Publikasikan laporan sebagai artefak, jadikan tahap deploy Anda bergantung padanya, dan picu rencana pada setiap commit. Setelah itu otomatis. Setiap push memeriksa API Anda, dan kontrak yang rusak mengubah build menjadi merah sebelum dapat berubah menjadi pemadaman.

Unduh Apidog dan bangun skenario pengujian pertama Anda, lalu masukkan perintah CLI yang dihasilkan ke dalam tugas skrip Bamboo. Pertama kali ia menangkap regresi yang dikompilasi dengan bersih, tahap tersebut akan sepadan dengan sepuluh menit yang dibutuhkan untuk pengaturannya.

tombol