Blog

Cara Menjalankan Tes API Apidog CLI di GitHub Actions: Alur Kerja Lengkap

Jalankan skenario uji API Apidog Anda di GitHub Actions. Alur kerja lengkap: instal apidog-cli, simpan token akses sebagai rahasia, lindungi penggabungan, dan publikasikan laporan.

Ashley Innocent

Ashley Innocent

15 June 2026

Cara Menjalankan Tes API Apidog CLI di GitHub Actions: Alur Kerja Lengkap

Apidog untuk Perusahaan

Penerapan On-Premises

SSO & RBAC

Sesuai SOC 2

Jelajahi Apidog Enterprise

Tes API Anda berhasil di mesin Anda. Kemudian rekan tim menggabungkan perubahan yang merusak titik akhir login, dan tidak ada yang menyadarinya sampai pelanggan mengajukan tiket. Tes-tes itu ada. Hanya saja mereka tidak pernah berjalan pada saat yang penting: pada pull request, sebelum penggabungan.

Kesenjangan itulah yang ditutup oleh integrasi berkelanjutan (continuous integration). Anda memindahkan tes dari terminal lokal Anda ke dalam pipeline yang menjalankannya secara otomatis, pada setiap push, terhadap setiap perubahan. Khusus untuk tes API, cara terbersih untuk melakukannya adalah dengan runner baris perintah yang mengeksekusi skenario yang sudah Anda buat, mengembalikan kode keluar lulus/gagal, dan membiarkan CI memutuskan apakah build akan berwarna hijau atau merah.

tombol

TL;DR

Mengapa menjalankan tes API di CI sama sekali

Tes yang hanya berjalan ketika Anda ingat untuk menjalankannya adalah tes yang tidak dapat Anda percayai. Jalankan secara lokal tidak masalah saat Anda menulis skenario. Mereka akan berantakan saat sebuah tim terlibat, karena setiap mesin pengembang sedikit berbeda dan tidak ada yang menjalankan seluruh suite sebelum setiap push.

CI memperbaiki masalah kepercayaan dengan membuat proses berjalan otomatis dan seragam. Setiap pull request memicu job yang sama, pada runner bersih yang sama, terhadap lingkungan yang sama. Ketika sebuah endpoint mulai mengembalikan 500 atau skema respons berubah, pemeriksaan akan gagal pada PR yang menyebabkannya, dengan nama orang yang melakukan push terlampir. Umpan balik tiba dalam hitungan menit, saat perubahan masih baru, alih-alih berhari-hari kemudian di produksi.

Tes API sangat cocok untuk ini karena cepat dan deterministik. Sebuah skenario mengenai endpoint nyata, menegaskan kode status dan badan respons, dan baik lulus atau gagal. Tidak ada browser yang tidak stabil, tidak ada rendering yang harus ditunggu. Itu membuatnya ideal sebagai gerbang penggabungan: cukup cepat untuk dijalankan pada setiap PR, cukup tegas untuk memblokir yang buruk. Jika Anda ingin latar belakang yang lebih luas tentang apa itu CI/CD dan bagaimana bagian-bagiannya saling terkait, pengantar tentang apa itu CI/CD dan cara kerjanya mencakup dasar-dasarnya.

Apa yang sebenarnya dilakukan Apidog CLI

Ini adalah bagian yang paling menghemat waktu Anda: Anda tidak menulis kode tes untuk CLI.

Anda membangun skenario pengujian Anda secara visual di aplikasi Apidog, dengan permintaan, pernyataan (assertions), variabel lingkungan, dan data yang Anda butuhkan. CLI adalah runner. Dengan ID skenario dan token akses, ia mengambil skenario tersebut dari proyek Apidog Anda dan mengeksekusinya, permintaan demi permintaan, mengevaluasi setiap pernyataan persis seperti yang akan dilakukan aplikasi. Hasilnya adalah laporan dan kode keluar.

Apidog CLI mengeksekusi skenario yang sama dengan yang Anda buat secara visual di aplikasi Apidog.

Desain itu penting untuk CI. Sebagian besar runner pengujian meminta Anda untuk mempertahankan representasi kode terpisah dari pengujian Anda; hal yang Anda jalankan di pipeline menyimpang dari hal yang Anda desain. Dengan Apidog, pipeline menjalankan skenario yang sama yang sudah dikelola oleh tim Anda di aplikasi. Perbarui pernyataan di editor visual dan CI berikutnya akan mengambilnya. Tidak ada salinan kedua yang perlu disinkronkan.

Binari adalah apidog, didistribusikan sebagai paket npm apidog-cli. Setiap perintah dimulai dengan apidog run. Jika Anda ingin melihat runner terintegrasi ke dalam alur kerja otomatisasi yang lebih lengkap, panduan tentang mengintegrasikan Apidog CLI dengan Claude Skills untuk otomatisasi tes API mencakup sudut pandang tersebut; artikel ini berfokus pada flag yang Anda butuhkan untuk pipeline GitHub Actions.

Sebelum Anda mulai: tiga hal yang Anda butuhkan

Anda memerlukan tiga informasi sebelum alur kerja akan berjalan. Dua adalah ID dari proyek Apidog Anda; satu adalah token.

  1. Skenario pengujian. Bangun di aplikasi Apidog jika Anda belum melakukannya. Ini adalah yang akan dijalankan oleh CLI. Skenario login-dan-ambil-profil tunggal sudah cukup untuk memulai; Anda dapat meningkatkannya nanti.
  2. ID skenario dan ID lingkungan. ID skenario memberi tahu CLI apa yang harus dijalankan; ID lingkungan memberi tahu di mana (dev, staging, produksi). Keduanya terlihat di aplikasi.
  3. Token akses. Ini mengotentikasi CLI ke akun Apidog Anda sehingga dapat mengambil dan menjalankan skenario.

Cara paling bersih untuk mendapatkan semua ini sekaligus adalah tab CI/CD skenario. Buka skenario pengujian yang ingin Anda otomatisasi, beralihlah ke tab CI/CD-nya, dan pilih opsi baris perintah. Klik untuk menambahkan token akses dan buat satu. Apidog akan menyusun perintah apidog run lengkap untuk Anda, dengan token akses, ID skenario (-t), dan ID lingkungan (-e) sudah terisi. Salin perintah itu; itu adalah dasar untuk langkah CI Anda.

Satu aturan yang patut disebutkan di awal: perlakukan token akses seperti kata sandi. Jangan tempel ke file alur kerja yang dikomit. Simpan sebagai rahasia GitHub Actions dan referensikan sebagai variabel lingkungan. Setiap contoh di bawah ini menggunakan $APIDOG_ACCESS_TOKEN untuk alasan yang sama persis.

Langkah 1: simpan token akses sebagai rahasia GitHub

Buka repositori Anda di GitHub. Buka Pengaturan, lalu Rahasia dan variabel, lalu Tindakan, dan klik Rahasia repositori baru.

Simpan. Token sekarang terenkripsi saat tidak digunakan dan hanya terekspos ke eksekusi alur kerja, tidak pernah dicetak di log. Dalam alur kerja, Anda akan merujuknya sebagai ${{ secrets.APIDOG_ACCESS_TOKEN }} dan memberikannya ke CLI melalui blok env:. ID skenario dan ID lingkungan tidak rahasia; keduanya adalah ID yang tidak berbahaya, jadi Anda bisa menuliskannya langsung di file alur kerja. Hanya token yang perlu dilindungi.

Jika tim Anda bekerja di beberapa repositori yang semuanya mengakses proyek Apidog yang sama, tentukan rahasia sekali di tingkat organisasi sebagai gantinya dan berikan akses ke repositori yang relevan. Nama yang sama, satu tempat untuk merotasinya.

Langkah 2: alur kerja minimal

Buat .github/workflows/api-tests.yml di repositori Anda. Ini adalah alur kerja terkecil yang melakukan sesuatu yang berguna: ia menjalankan skenario Anda pada setiap pull request yang menargetkan main.

name: Tes API

on:
  pull_request:
    branches: [main]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Siapkan Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

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

      - name: Jalankan skenario tes API
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -r cli
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

Ganti 605067 dengan ID skenario Anda dan 1629989 dengan ID lingkungan Anda. Komit file ini, buka pull request, dan perhatikan tab Checks. Job akan menjalankan runner Ubuntu, menginstal Node 20, menginstal CLI, dan menjalankan skenario Anda. Jika setiap pernyataan berhasil, pemeriksaan akan berwarna hijau. Jika satu gagal, apidog run keluar dengan kode bukan nol, GitHub akan membuat pemeriksaan gagal, dan PR akan menunjukkan tanda silang merah.

Tanda silang merah itu adalah intinya. Tidak ada yang perlu membaca log untuk mengetahui sesuatu rusak; pemeriksaan yang gagal ada di pull request.

Catatan tentang langkah instal: npm install -g apidog-cli global itu sederhana dan berfungsi. Jika Anda tidak ingin mengubah paket global runner, Anda dapat melewati langkah instal dan memanggil CLI melalui npx sebagai gantinya:

      - name: Jalankan skenario tes API
        run: npx apidog-cli run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r cli
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

Kedua pendekatan menjalankan skenario yang identik. npx lebih rapi pada runner ephemeral; instalasi global sedikit lebih cepat ketika Anda menyimpan cache node_modules di antara eksekusi. Pilih yang sesuai dengan gaya Anda.

Langkah 3: publikasikan laporan yang benar-benar bisa Anda baca

Tanda centang hijau atau merah memberitahu Anda hasilnya. Ketika sebuah tes gagal, Anda ingin tahu alasannya, dan untuk itu Anda menginginkan laporannya.

Flag -r (atau --reporters) mengontrol format laporan. Ini menerima cli, html, json, dan junit, dipisahkan koma. Untuk CI, dua format sangat berguna:

Biarkan cli juga jika Anda ingin output yang mudah dibaca di log build itu sendiri. Berikut adalah langkah jalankan yang ditingkatkan untuk menghasilkan kedua format laporan dan menuliskannya ke direktori, ditambah langkah unggah agar laporan tetap ada setelah dijalankan:

      - name: Jalankan skenario tes API
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -n 1 \
            -r html,junit,cli \
            --out-dir ./apidog-reports
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - name: Unggah laporan tes
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: laporan-apidog
          path: ./apidog-reports

Dua detail membuat ini berfungsi seperti yang Anda inginkan. Flag --out-dir memberi tahu CLI di mana harus menulis laporan; di sini adalah ./apidog-reports, yang kemudian diambil oleh langkah unggah. Dan if: always() pada langkah unggah adalah yang penting: secara default GitHub melewati langkah-langkah selanjutnya setelah sebuah langkah gagal, tetapi Anda paling membutuhkan laporan ketika pengujian gagal. if: always() memaksa unggahan untuk berjalan terlepas dari hasil pengujian. Setelah job selesai, laporan muncul di bawah Artefak pada halaman ringkasan jalankan, siap untuk diunduh.

Flag -n 1 mengatur jumlah iterasi menjadi satu kali jalan; tingkatkan jika Anda ingin skenario dieksekusi beberapa kali berturut-turut.

Jika Anda ingin GitHub menampilkan hasil JUnit secara langsung sebagai pemeriksaan beranotasi daripada file yang dapat diunduh, tambahkan tindakan `published-test-results` setelah langkah run dan arahkan ke `./apidog-reports/*.xml`. Ini akan mengubah XML menjadi ringkasan lulus/gagal yang dilampirkan pada run, yang berguna untuk suite yang lebih besar di mana menggulir log tidak praktis.

Langkah 4: uji lingkungan yang tepat pada waktu yang tepat

Pull request harus menguji terhadap staging. Deploy ke produksi harus diverifikasi terhadap produksi. Skenario yang sama dapat melakukan keduanya; Anda hanya perlu mengubah ID lingkungan dengan -e.

Pengaturan umum dan tahan lama menggunakan dua pemicu dalam satu file alur kerja. Pull request menjalankan skenario terhadap lingkungan staging Anda sebagai gerbang merge. Push ke main (yang merupakan hasil dari merge) menjalankan skenario yang sama terhadap produksi sebagai smoke test pasca-deploy.

name: Tes API

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  pr-check:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g apidog-cli
      - name: Tes staging
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -r junit,cli \
            --out-dir ./apidog-reports
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: laporan-staging
          path: ./apidog-reports

  prod-smoke:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g apidog-cli
      - name: Smoke test produksi
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1730055 \
            -r cli \
            --on-error end
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

Dua ID lingkungan (1629989 untuk staging, 1730055 untuk produksi) adalah satu-satunya perbedaan yang signifikan. Job PR membuat dan mengarsipkan laporan JUnit sehingga peninjau dapat memeriksa kegagalan; smoke test produksi berjalan ramping dan cepat gagal dengan --on-error end, yang berhenti pada pernyataan pertama yang rusak sehingga Anda segera mengetahui bahwa deploy berjalan salah.

--on-error layak diketahui. Ini mengontrol apa yang terjadi ketika sebuah langkah gagal di tengah skenario. end menghentikan eksekusi pada kegagalan pertama (umpan balik cepat, baik untuk smoke tests). continue menjalankan setiap langkah yang tersisa sehingga Anda melihat semua kegagalan dalam satu laporan (baik untuk pemeriksaan PR yang menyeluruh). ignore melewatkan langkah yang diketahui tidak stabil tanpa menggagalkan eksekusi. Mana pun yang Anda pilih, eksekusi tetap berakhir dengan kode keluar bukan nol jika ada yang gagal, sehingga gerbang tetap berfungsi.

Melangkah lebih jauh: eksekusi matriks, folder, dan tes berbasis data

Setelah gerbang dasar terpasang, beberapa flag memperluasnya tanpa banyak YAML tambahan.

Jalankan seluruh area fitur, bukan satu skenario. Ganti -t <scenarioId> dengan -f <folderId> untuk menjalankan setiap skenario di dalam folder, atau --test-suite <testSuiteId> untuk menjalankan suite yang dikurasi. Suite adalah alat yang tepat ketika Anda menginginkan serangkaian skenario yang spesifik dan terurut dijalankan bersama sebagai satu job logis; panduan tentang menskalakan pengujian API otomatis dengan test suite mencakup kapan harus menggunakannya.

Uji beberapa lingkungan secara paralel. Sebuah matriks menjalankan job yang sama di beberapa ID lingkungan sekaligus:

jobs:
  api-tests:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        env-id: [1629989, 1730055]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g apidog-cli
      - name: Jalankan skenario terhadap ${{ matrix.env-id }}
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e ${{ matrix.env-id }} \
            -r cli
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

GitHub menjalankan satu runner per nilai matriks, sehingga staging dan produksi diuji secara bersamaan dan masing-masing melaporkan hasil lulus/gagalnya sendiri.

Jalankan iterasi dari file data. Flag -d menjalankan satu skenario di seluruh baris file CSV atau JSON, memperlakukan setiap baris sebagai pass terpisah: apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -d ./test-data.csv -r junit. Ini adalah cara Anda memvalidasi endpoint yang sama terhadap lima puluh input tanpa membangun lima puluh skenario.

Jalankan terhadap sebuah cabang (branch). Jika tim Anda menggunakan fitur cabang Apidog, --branch <namaCabang> mengarahkan eksekusi ke cabang tertentu alih-alih main, yang memungkinkan PR cabang fitur menguji terhadap definisi skenario cabang tersebut.

Memecahkan masalah kegagalan CI yang umum

Job berwarna hijau tetapi sebuah tes seharusnya gagal. Periksa apakah kode keluar dari langkah apidog run benar-benar mencapai GitHub. Jika Anda membungkus perintah dalam pipeline shell atau menambahkan || true, kode keluar bukan nol akan tertelan dan gerbang secara diam-diam berhenti berfungsi. Hapus apa pun yang menyamarkan kode keluar. Jalankan perintah pada barisnya sendiri, atau sebagai perintah terakhir dalam blok run:, sehingga status keluarnya adalah status keluar langkah tersebut.

Autentikasi gagal. Penyebab paling umum adalah nama rahasia tidak cocok. Kunci env:, referensi nilai ${{ secrets.APIDOG_ACCESS_TOKEN }}, dan rahasia yang Anda buat di Pengaturan semuanya harus menggunakan nama yang sama. Juga konfirmasikan token belum diregenerasi di Apidog sejak Anda menyimpannya; meregenerasi akan membatalkan yang lama.

Berhasil secara lokal, gagal di CI. Tambahkan --verbose ke perintah jalankan untuk sementara waktu. Ini akan mencetak permintaan lengkap yang dikirim runner dan respons lengkap yang diterimanya, yang biasanya mengungkapkan perbedaan, seringkali variabel lingkungan yang diatur di mesin Anda tetapi tidak di lingkungan CI, atau layanan staging yang berperilaku berbeda dari yang lokal Anda.

Laporan tidak muncul sebagai artefak. Pastikan --out-dir di langkah run dan path: di langkah upload menunjuk ke direktori yang sama, dan bahwa langkah upload memiliki if: always(). Tanpa if: always(), tes yang gagal akan melewati upload dan Anda akan kehilangan laporan tepat saat Anda membutuhkannya.

Runner tidak dapat mencapai API Anda. Jika lingkungan staging atau produksi Anda berada di balik firewall atau VPN, runner publik yang dihosting GitHub tidak dapat mencapainya. Anda akan membutuhkan runner yang dihosting sendiri di dalam jaringan Anda, atau entri daftar izin untuk rentang IP GitHub.

Bagaimana ini dibandingkan dengan alternatif lain

Anda bisa menulis tes API sebagai kode dengan framework, mengintegrasikannya ke dalam runner tes, dan memanggilnya dari Actions. Itu berfungsi, tetapi sekarang Anda harus memelihara suite kode yang harus tetap sinkron dengan API dan dengan apa pun yang dirancang tim Anda di alat API mereka. Pendekatan Apidog menghindari duplikasi itu: skenario yang sudah dikelola tim Anda di aplikasi adalah tes yang berjalan di CI.

Anda juga bisa membuat skrip panggilan curl mentah dalam langkah alur kerja. Ini bagus untuk satu pemeriksaan kesehatan, tetapi menyakitkan setelah itu, karena Anda harus membuat sendiri pernyataan, peralihan lingkungan, dan pelaporan yang diberikan CLI secara gratis.

GitHub Actions juga bukan satu-satunya tempat untuk ini. Perintah apidog run yang sama persis dapat dimasukkan ke GitLab CI, Jenkins, CircleCI, atau runner mana pun yang dapat mengeksekusi perintah shell dan membaca kode keluar. Jika GitHub Actions bukan platform Anda, pola-pola di sini dapat langsung ditransfer; lihat panduan untuk mengotomatiskan tes API di CI/CD untuk tampilan lintas platform, atau panduan mengintegrasikan tes otomatis Apidog dengan Jenkins jika Anda menggunakan Jenkins.

Untuk membangun skenario yang akan Anda jalankan, unduh Apidog, rancang tes Anda di aplikasi, dan ambil perintah CLI dari tab CI/CD skenario. Runner adalah paket npm gratis; apa yang dapat Anda jalankan tergantung pada proyek Apidog Anda, tetapi runner baris perintah itu sendiri bukan produk berbayar terpisah.

Kesimpulan

Pengaturannya lebih sederhana dari yang terlihat. Bangun skenario di Apidog, simpan satu token akses sebagai rahasia GitHub, dan tambahkan beberapa langkah ke file alur kerja. Dari situ, setiap pull request menjalankan tes API Anda secara otomatis, titik akhir yang gagal akan mengubah pemeriksaan menjadi merah sebelum penggabungan (merge), dan laporan menunggu di tab Artifacts setiap kali Anda perlu melihat apa yang rusak.

Alasan tetap sederhana adalah pembagian tugas. Aplikasi Apidog memiliki tes; CLI menjalankannya; GitHub membaca kode keluar. Tidak ada yang perlu diduplikasi atau disinkronkan. Ketika Anda memperbarui sebuah pernyataan di aplikasi, eksekusi CI berikutnya akan menggunakannya. Itulah yang membuat ini layak dilakukan pada hari pertama sebuah proyek daripada mengintegrasikannya setelah insiden produksi pertama.

tombol

Mengembangkan API dengan Apidog

Apidog adalah alat pengembangan API yang membantu Anda mengembangkan API dengan lebih mudah dan efisien.

Daftar gratisUnduh