Eksekusi uji yang tidak mencetak apapun yang berguna adalah eksekusi uji yang tidak dipercaya siapa pun. Pipeline Anda berubah merah, seseorang membuka log pembangunan, dan yang mereka temukan hanyalah deretan stempel waktu dan kode keluar non-nol. Asersi mana yang rusak? Terhadap lingkungan mana? Pada baris mana dari berkas data? Eksekusi itu tahu. Hanya saja tidak pernah menuliskannya di mana pun Anda bisa membacanya nanti.
Itulah celah yang diisi oleh pelapor (reporter). Ketika Anda menjalankan pengujian API dari baris perintah, laporan adalah bagian yang sebenarnya Anda gunakan: artefak yang Anda arsipkan, berkas yang diuraikan dasbor CI Anda, hal yang Anda berikan kepada rekan kerja jam 9 pagi yang tidak mengawasi pipeline pada jam 2 pagi. Putusan pengujian hanyalah separuh pekerjaan. Separuh lainnya adalah membuat putusan itu mudah dibaca oleh manusia dan mesin secara bersamaan.
Runner baris perintah Apidog menangani keduanya. Apidog menyediakan CLI yang menjalankan skenario pengujian yang Anda buat secara visual di aplikasi, dan satu flag mengontrol setiap laporan yang dihasilkannya: -r, --reporters. Anda meneruskan daftar yang dipisahkan koma, runner menulis setiap format ke disk, dan Anda memutuskan siapa yang membaca apa. Panduan ini membahas flag tersebut dan berkas yang dihasilkannya: untuk apa setiap reporter, apa yang mendarat di disk, di mana mendaratnya, dan bagaimana menghubungkan setiap reporter ke alur kerja yang nyata. Jika Anda ingin melihat lebih luas setiap flag yang diterima runner, referensi perintah apidog run mencakup keseluruhan; halaman ini berfokus pada laporan.
Mengapa laporan lebih penting daripada eksekusi
Jalankan skenario secara lokal dan Anda akan melihatnya terjadi. Anda melihat setiap permintaan terpicu, setiap asersi berubah hijau, ringkasan di akhir. Lingkaran umpan balik adalah terminal di depan Anda, secara langsung.
Di CI, lingkaran itu hilang. Eksekusi terjadi pada mesin yang tidak pernah Anda lihat, pada saat Anda tidak mengawasi, dan satu-satunya catatan adalah apa pun yang ditulis ke disk sebelum runner keluar. Jika eksekusi tidak menghasilkan laporan, kegagalan hanya memberi tahu Anda bahwa ada sesuatu yang rusak. Anda terpaksa menjalankan ulang semuanya secara lokal dan berharap itu rusak dengan cara yang sama.
Laporan yang baik menutup jarak itu. Laporan itu menangkap skenario mana yang dijalankan, terhadap lingkungan mana, berapa banyak iterasi, asersi mana yang berhasil, mana yang gagal, serta detail permintaan dan respons di balik setiap kegagalan. Dapatkan itu di disk dan kegagalan jam 2 pagi menjadi bacaan lima menit keesokan paginya alih-alih perburuan reproduksi. Itulah seluruh alasan flag reporter ada, dan mengapa memilih format yang tepat untuk setiap audiens patut dipikirkan beberapa menit.
Satu flag yang mengontrol setiap laporan
Apidog CLI adalah paket npm yang disebut apidog-cli. Instal sekali dan Anda akan mendapatkan satu binary, apidog, yang subperintah utamanya adalah run. Instal secara global:
npm install -g apidog-cli
Setiap laporan yang dapat dihasilkan runner berasal dari satu flag pada perintah itu: -r, --reporters. Flag ini menerima daftar yang dipisahkan koma, dan empat nilai yang diterimanya adalah cli, html, json, dan junit. Defaultnya, jika Anda tidak meneruskan apa pun, adalah cli.
Eksekusi lengkap dengan dua reporter terlihat seperti ini:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,cli
Itu mengautentikasi dengan token, menjalankan skenario pengujian 605067 terhadap lingkungan 1629989 sekali, dan menghasilkan berkas HTML serta keluaran terminal yang dapat dibaca. ID adalah ID skenario dan ID lingkungan; Anda menyalin keduanya, beserta token akses, dari tab CI/CD skenario di Apidog daripada mengetiknya secara manual. Jika salah satu pengaturan itu tidak familiar, panduan lengkap Apidog CLI menjelaskan instalasi, token, dan eksekusi pertama Anda dari awal hingga akhir.
Ide utamanya: satu eksekusi dapat menghasilkan beberapa laporan sekaligus. Anda tidak memilih satu format tunggal. Anda memilih audiens untuk setiap keluaran dan mencantumkannya bersama-sama. Baris CI tipikal menghasilkan berkas HTML yang dapat dibaca manusia dan berkas JUnit yang dapat dibaca mesin dari eksekusi yang sama, sehingga eksekusi yang sama melayani baik orang maupun dasbor.
cli: laporan yang Anda baca di log pembangunan
Reporter cli mencetak ringkasan yang mudah dibaca langsung ke terminal. Ini adalah default, dan ini adalah yang pertama kali dipindai oleh manusia.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli
Apa yang diberikannya kepada Anda adalah putusan langsung: berapa banyak permintaan yang dijalankan, berapa banyak asersi yang berhasil dan gagal, dan asersi spesifik mana yang rusak. Dalam log pembangunan CI, ini adalah blok yang dibaca seseorang ketika mereka mengklik pekerjaan yang gagal. Ini memberi tahu mereka secara sekilas apakah kegagalannya adalah satu asersi yang rusak atau lima puluh, dan endpoint mana yang terlibat, sebelum mereka repot mengunduh apa pun.
Biarkan cli tetap aktif bahkan ketika Anda menulis format mesin. Ini tidak memerlukan biaya dan menjaga log pembangunan tetap berguna dengan sendirinya. Pipeline yang hanya mengeluarkan JUnit XML menghasilkan dasbor yang sempurna dan log yang tidak berguna; siapa pun yang membaca keluaran mentah tidak akan melihat apa pun kecuali runner memulai dan keluar. Menambahkan cli ke daftar memperbaiki masalah itu:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,junit --out-dir ./apidog-reports
Dua flag lagi membentuk apa yang dicetak cli. --verbose mengembangkannya ke permintaan dan respons lengkap untuk setiap langkah, yang merupakan langkah pertama Anda ketika skenario berhasil di laptop Anda tetapi gagal dalam pipeline; detail koneksi menunjukkan dengan tepat apa yang dikirim dan diterima oleh runner. --silent melakukan yang sebaliknya dan menekan keluaran konsol sepenuhnya, yang cocok untuk pekerjaan terjadwal yang bising di mana Anda hanya peduli tentang kode keluar dan berkas yang disimpan.
html: laporan yang Anda berikan kepada manusia
Reporter html menulis berkas HTML mandiri. Bukalah di browser mana pun dan Anda akan mendapatkan seluruh eksekusi yang disajikan secara visual: setiap permintaan, asersi di dalamnya, status berhasil dan gagal, serta detail permintaan dan respons di balik setiap langkah. Tidak ada yang perlu diinstal, tidak ada server yang perlu dijalankan; ini adalah satu berkas yang Anda klik dua kali.
Ini adalah format yang Anda arsipkan dan bagikan. Simpan sebagai artefak pembangunan dan laporan akan bertahan lebih lama dari eksekusi pipeline, sehingga seminggu kemudian Anda masih dapat membuka laporan persis dari deployment yang rusak. Ini juga yang Anda kirimkan kepada orang yang bertanya “apa yang gagal?” tanpa membuat mereka menginstal CLI atau menjalankan ulang apa pun. Mereka membuka berkas, melihat langkah merah, membaca badan respons yang memicu asersi, dan mereka selesai.
HTML paling banyak mendapatkan tempatnya dalam eksekusi yang digerakkan data. Ketika satu skenario mengulang lebih dari lima puluh baris CSV, laporan HTML menunjukkan hasil per iterasi, sehingga Anda dapat melihat bahwa baris 1 hingga 49 berhasil dan baris 50 gagal karena satu akun memiliki token usang. Jumlah berhasil atau gagal saja tidak dapat memberi tahu Anda itu. Jika Anda menjalankan skenario di berbagai berkas data, polanya dibahas dalam pengujian API berbasis data dengan CSV dan JSON.
Kelemahannya: HTML adalah untuk mata, bukan untuk diuraikan. Jangan mencoba mengikisnya untuk status berhasil/gagal dalam skrip. Itulah gunanya JSON dan JUnit.
junit: laporan yang diuraikan dasbor CI Anda
Reporter junit mengeluarkan XML dalam format JUnit standar. Format itu penting karena merupakan lingua franca pelaporan pengujian CI. Hampir setiap sistem CI, GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure Pipelines, tahu cara membaca JUnit XML dan mengubahnya menjadi pohon berhasil/gagal, menampilkan kegagalan di widget permintaan gabungan, dan melihat tren hasil di berbagai pembangunan dari waktu ke waktu.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r junit --out-dir ./apidog-reports
Jika Anda memilih tepat satu format mesin untuk CI, pilihlah yang ini. Manfaatnya adalah hasil pengujian Anda tidak hanya ada di berkas log tetapi mulai ada di dasbor yang sudah dilihat tim Anda. Seorang peninjau membuka permintaan tarik dan melihat asersi mana yang gagal ditampilkan secara inline, tanpa perlu menggali log, tanpa unduhan artefak.
Menghubungkannya ada dua langkah: hasilkan XML, lalu beritahu sistem CI Anda di mana menemukannya. Di GitLab CI, langkah kedua adalah blok reports: junit::
api-tests:
stage: test
image: node:20
script:
- npm install -g apidog-cli
- apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r junit,cli --out-dir ./apidog-reports
artifacts:
when: always
paths:
- apidog-reports/
reports:
junit: apidog-reports/*.xml
Di Jenkins, yang setara adalah langkah junit dalam blok post yang menunjuk ke berkas yang sama. Di GitHub Actions, Anda mengunggah direktori sebagai artefak dan membiarkan tindakan yang mengerti JUnit menampilkannya. Alur kerja GitHub lengkap, termasuk unggahan artefak yang berjalan bahkan ketika pengujian gagal, ada di menjalankan pengujian Apidog CLI di GitHub Actions.
json: laporan yang diproses pasca oleh skrip Anda
Reporter json menghasilkan hasil terstruktur mentah. Di mana HTML untuk mata dan JUnit untuk dasbor, JSON adalah untuk kode yang Anda tulis sendiri.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r json --out-dir ./apidog-reports
Gunakan ini ketika format bawaan tidak sesuai dengan apa yang ingin Anda lakukan dengan hasilnya. Dorong metrik tingkat keberhasilan ke sistem pemantauan. Buat ringkasan Slack khusus. Masukkan hasilnya ke dalam skrip yang memutuskan apakah akan mengembalikan deployment. Bandingkan eksekusi hari ini dengan eksekusi kemarin. Apa pun yang bersifat programatis dimulai dari JSON, karena ini adalah format yang dapat Anda uraikan tanpa menebak-nebak strukturnya.
Satu flag laporan dibangun khusus untuk keluaran JSON. --out-json-failures-separated <value> memisahkan kegagalan ke dalam berkas JSON-nya sendiri. Itu memberi Anda dokumen khusus kegagalan, yang jauh lebih mudah dibaca dan dibandingkan daripada memindai hasil lengkap untuk beberapa langkah yang rusak. Pada sapuan regresi besar di mana sebagian besar langkah berhasil, berkas khusus kegagalan adalah perbedaan antara melihat sekilas dan melakukan grep.
Di mana berkas mendarat: --out-dir, --out-file, dan placeholder
Memilih format adalah separuh gambaran. Separuh lainnya adalah mengontrol di mana berkas mendarat dan apa namanya, yang penting saat Anda menyimpan laporan lebih dari satu kali eksekusi.
--out-dir <dir> menetapkan direktori tempat laporan ditulis. Defaultnya adalah ./apidog-reports. Di CI, arahkan ke tempat yang dapat ditemukan oleh langkah artefak Anda, dan jaga agar tetap konsisten sehingga konfigurasi unggahan Anda tidak perlu diubah:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html,junit --out-dir ./apidog-reports
--out-file <name> menetapkan nama berkas laporan, dan di sinilah letak kegunaannya. Tanpa itu, setiap eksekusi cenderung menimpa yang terakhir, sehingga Anda hanya menyimpan laporan terbaru. Flag ini menerima placeholder yang diisi oleh runner saat menulis:
{SCENARIO_NAME}menjadi nama skenario yang dijalankan.{FOLDER_NAME}menjadi nama folder saat Anda menjalankan folder skenario.{GENERATE_TIME}menjadi stempel waktu.
Cap nama berkas dengan nama skenario dan stempel waktu dan setiap eksekusi menulis berkas yang berbeda, yang menjelaskan dirinya sendiri alih-alih menimpa yang sebelumnya:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html --out-file "{SCENARIO_NAME}-{GENERATE_TIME}"
Sekarang direktori laporan Anda terbaca seperti riwayat. Anda dapat mengetahui laporan mana yang berasal dari skenario mana dan kapan itu dijalankan tanpa membuka satu berkas pun, yang persis seperti yang Anda inginkan saat Anda memindai folder eksekusi malam untuk menemukan yang pertama kali salah.
Satu lagi flag laporan melengkapi sisi cloud. --upload-report [value] mengunggah ikhtisar laporan ke cloud Apidog, sehingga eksekusi juga muncul dalam riwayat proyek Anda di samping berkas lokal. Ini adalah pilihan yang bisa digunakan saat Anda ingin hasilnya terlihat di dalam Apidog itu sendiri, tidak hanya sebagai berkas di runner CI.
Strategi reporter berdasarkan audiens
Cara paling jelas untuk memutuskan adalah dengan memetakan setiap reporter ke siapa yang membacanya, lalu meneruskan yang Anda butuhkan secara bersamaan.
- Seseorang yang sedang memindai log pembangunan saat ini membaca
cli. Selalu sertakan itu. - Seseorang yang membuka laporan yang disimpan nanti membaca
html. Arsipkan sebagai artefak. - Dasbor CI membaca
junit. Ini yang menampilkan kegagalan dalam permintaan gabungan dan tren hasil di berbagai pembangunan. - Skrip yang Anda tulis membaca
json. Ini adalah satu-satunya format yang dimaksudkan untuk diuraikan oleh kode Anda sendiri.
Untuk sebagian besar pipeline CI, kombinasi yang paling sering digunakan adalah HTML untuk manusia ditambah JUnit untuk dasbor, dengan CLI tetap aktif agar log mentah tetap mudah dibaca:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli,html,junit --out-dir ./apidog-reports
Satu eksekusi itu menghasilkan log yang dapat dibaca, artefak yang dapat dijelajahi, dan berkas XML yang dapat diuraikan. Tiga audiens, satu eksekusi, tanpa duplikasi.
Satu peringatan yang patut disebutkan secara jelas: laporan memberi tahu Anda apa yang terjadi, tetapi kode keluar (exit code) adalah yang membuat pipeline bertindak berdasarkan itu. Apidog CLI keluar dengan nilai non-nol ketika ada asersi yang gagal, dan kode keluar itulah, bukan laporannya, yang membuat pembangunan gagal dan memblokir penggabungan. Laporan menjelaskan kegagalan; kode keluar menegakkannya. Jangan membungkus perintah dalam apa pun yang menelan kode itu, seperti menambahkan || true di shell, atau Anda akan mendapatkan laporan merah sempurna yang terpasang pada pembangunan yang tetap berwarna hijau. Versi yang lebih mendalam dari logika gerbang kualitas itu ada dalam panduan mengotomatiskan pengujian API di CI/CD.
Menggabungkannya
Jalankan skenario di CI dan keluarkan ketiga artefak yang berguna untuk tiga audiens:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r cli,html,junit --out-dir ./apidog-reports
Jalankan pembersihan folder malam, kumpulkan setiap kegagalan dalam satu laporan, dan berikan nama yang mendeskripsikan diri sendiri pada setiap berkas:
apidog run --access-token $APIDOG_ACCESS_TOKEN -f 88012 -r html,junit --on-error continue --out-dir ./nightly-reports --out-file "{FOLDER_NAME}-{GENERATE_TIME}"
Jalankan skenario berbasis data dan simpan JSON khusus kegagalan untuk perbandingan cepat:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./accounts.csv -r json --out-json-failures-separated true --out-dir ./apidog-reports
Jika Anda lebih suka tidak menginstal CLI secara global pada runner sementara, ganti instalasi dengan npx dan pertahankan flag reporter yang sama:
npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html,junit --out-dir ./apidog-reports
Perilaku reporter identik dalam kedua cara; pilihan antara instalasi global dan npx adalah tentang kebersihan runner, bukan tentang laporan apa yang Anda dapatkan.
Nama flag, default, dan reporter dapat berubah antara rilis CLI, jadi runner selalu menjadi sumber kebenaran. Jalankan apidog run --help pada versi yang Anda instal dan percayai itu daripada artikel apa pun, termasuk yang ini. Untuk menyiapkan skenario yang pertama kali dijalankan CLI, Unduh Apidog, buat satu skenario di aplikasi, lalu salin perintah yang dihasilkan dari tab CI/CD-nya dan tambahkan reporter yang Anda butuhkan.