Cara Menjalankan Tes API Apidog CLI di Drone CI

Anda menjalankan tes API Apidog CLI di Drone CI dengan menambahkan langkah _pipeline_ Docker yang menggunakan _image_ Node, menginstal `apidog-cli`, dan menjalankan `apidog run` terhadap sebuah lingkungan. _Access token_ Apidog Anda tersimpan dalam _secret_ Drone dan disuntikkan melalui `from_secret`. Panduan ini akan membahas `.drone.yml` yang bisa langsung disalin-tempel, penanganan _secret_, _branch gating_, dan cara mengekspos laporan tes karena Drone tidak memiliki _artifact store_ bawaan.

Apa Itu Drone CI dan Cara Kerjanya

Drone adalah platform CI/CD _open-source_ dan _container-native_, sekarang menjadi bagian dari Harness. CI/CD adalah singkatan dari _continuous integration_ dan _continuous delivery_, praktik membangun dan menguji kode secara otomatis pada setiap perubahan. Jika Anda ingin menyegarkan kembali konsepnya, lihat apa itu CI/CD.

Ciri khas Drone sangat sederhana: setiap langkah _pipeline_ berjalan di dalam kontainer Docker-nya sendiri. Tidak ada _agent_ _build_ bersama dengan banyak _tool_ yang sudah terinstal sebelumnya. Anda memilih _image_ untuk setiap langkah, dan Drone menjalankan perintah Anda di dalamnya. Hal ini membuat _build_ dapat direproduksi dan mudah dipahami.

Anda mendefinisikan _pipeline_ dalam file .drone.yml di akar repositori Anda. Sebuah _pipeline_ Docker memiliki tiga kunci tingkat atas: kind, type, dan name. Pekerjaan berlangsung di bawah steps, di mana setiap langkah mendeklarasikan name, image, dan daftar commands.

kind: pipeline
type: docker
name: api-tests

steps:
  - name: greeting
    image: alpine
    commands:
      - echo hello
      - echo world

Drone menjalankan commands sebagai _shell script_ dengan set -e dan set -x, sehingga _build_ akan gagal dengan cepat pada kode keluar bukan nol yang pertama dan mengulang setiap perintah sebelum menjalankannya. Perintah menimpa _entrypoint_ kontainer, dan direktori kerja adalah akar repositori Anda.

Mengapa Menjalankan Tes API dalam Langkah Kontainer

Tes API mencegah _contract drift_. Perubahan _backend_ yang secara diam-diam mengubah bentuk respons atau kode status dapat merusak setiap _client_ di hilir. Menjalankan tes tersebut pada setiap _push_ menangkap regresi sebelum dirilis.

Apidog sangat cocok dengan model ini. Anda membangun dan memelihara tes Anda secara visual di aplikasi Apidog, lalu menjalankan skenario tes yang sama persis dari baris perintah dengan Apidog CLI. Tidak ada penulisan ulang _script_, tidak ada _test harness_ terpisah. Untuk panduan lebih luas tentang cara menghubungkan tes API ke dalam _pipeline_, baca praktik terbaik CI/CD untuk pengujian API.

Apidog adalah platform API lengkap untuk desain, _debugging_, pengujian, _mocking_, dan dokumentasi. CLI adalah bagian yang mengubah skenario tes yang Anda simpan menjadi satu perintah yang dapat diulang, yang persis seperti yang dibutuhkan oleh langkah Drone.

Perintah Apidog CLI yang Akan Anda Jalankan

Instal CLI dengan npm, lalu jalankan skenario tes. Di CI, Anda mengarahkan eksekusi ke skenario yang disimpan dengan _flag_, jadi tidak ada file koleksi lokal yang perlu dikelola.

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli

Berikut adalah fungsi setiap _flag_:

--access-token meneruskan _access token_ Apidog Anda. Tidak ada bentuk singkat.
-t adalah ID skenario tes yang ingin Anda jalankan.
-e adalah ID lingkungan, dan ini wajib. Ini memilih URL dasar dan variabel mana yang digunakan oleh eksekusi.
-r mencantumkan _reporter_. Nilai yang valid adalah cli, html, json, dan junit.

Anda dapat menambahkan lebih banyak _flag_ sesuai kebutuhan:

-n atau --iteration-count mengulang eksekusi sejumlah kali yang ditentukan.
-d atau --iteration-data mengambil jalur file CSV atau JSON, atau ID _data-set_ numerik yang disimpan, untuk eksekusi berbasis data.
--out-dir mengatur direktori output laporan.
--upload-report mengirimkan ringkasan laporan ke _cloud_ Apidog, tempat Anda dapat melihatnya di aplikasi. Anda dapat menggunakannya sebagai _bare flag_.
--on-error mengontrol perilaku kegagalan dengan continue, end, atau ignore.
--project <id> dan --branch <name> menargetkan _branch_ proyek tertentu.

Untuk tur lengkap tentang perintah dan opsinya, lihat panduan lengkap Apidog CLI dan _walkthrough_ tentang menguji REST API dari baris perintah.

`.drone.yml` Lengkap untuk Tes Apidog

Berikut adalah _pipeline_ yang berfungsi. Ini menggunakan _image_ Node, menginstal CLI, dan menjalankan skenario Anda. _Token_ berasal dari _secret_ Drone daripada dikodekan secara _hardcode_.

kind: pipeline
type: docker
name: apidog-api-tests

steps:
  - name: run-api-tests
    image: node:20-alpine
    environment:
      APIDOG_ACCESS_TOKEN:
        from_secret: apidog_access_token
    commands:
      - npm install -g apidog-cli
      - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli

trigger:
  branch:
    - main
  event:
    - push
    - pull_request

Ganti 1234567 dengan ID skenario tes Anda dan 89012 dengan ID lingkungan Anda. Keduanya terlihat di aplikasi Apidog. Karena langkah ini menggunakan _reporter_ cli, rincian lulus/gagal lengkap dicetak langsung ke log _build_ Drone, di mana siapa pun yang meninjau _build_ dapat membacanya.

Menyimpan _Secret_ di Drone CI

Jangan pernah melakukan _commit_ _API token_ ke repositori Anda. Drone menyimpan _secret_ di luar YAML dan menyuntikkannya saat waktu proses (_runtime_).

Anda mereferensikan _secret_ di dalam blok environment sebuah langkah (atau blok settings sebuah _plugin_) dengan from_secret. Nilai yang Anda tulis adalah nama _secret_, bukan _token_ itu sendiri.

environment:
  APIDOG_ACCESS_TOKEN:
    from_secret: apidog_access_token

Ada dua cara umum untuk membuat _secret_. Yang pertama adalah UI Drone: buka repositori Anda, buka Pengaturan (_Settings_), lalu _Secret_, dan tambahkan _secret_ bernama apidog_access_token dengan _token_ Anda sebagai nilainya. Yang kedua adalah _tool_ baris perintah Drone.

drone secret add \
  --repository your-org/your-repo \
  --name apidog_access_token \
  --data your-apidog-token

Konfirmasikan nama _flag_ yang tepat dengan dokumentasi Drone CLI untuk versi Anda, karena _flag_ CLI dapat berubah antar rilis. Drone juga mendukung varian _secret_ terenkripsi di dalam repo di mana drone encrypt menghasilkan _blob_ terenkripsi yang Anda masukkan sebagai dokumen YAML kind: secret terpisah. Untuk sebagian besar tim, _secret_ repo yang ditambahkan melalui UI atau drone secret add lebih sederhana dan merupakan titik awal yang direkomendasikan.

Menyimpan _token_ dalam _secret_ adalah disiplin yang sama yang akan Anda terapkan di mana pun. Untuk lebih lanjut tentang bagaimana CLI menangani kredensial, lihat panduan tentang autentikasi Apidog CLI.

Mengatur Eksekusi berdasarkan _Branch_ dan _Event_

Drone memberi Anda dua tuas untuk mengontrol kapan pekerjaan berjalan: trigger di tingkat _pipeline_ dan when di tingkat langkah.

Blok trigger memutuskan apakah seluruh _pipeline_ berjalan. Semua kondisi harus bernilai benar, jadi contoh di bawah ini hanya berjalan pada _push_ dan _pull request_ yang menargetkan main.

trigger:
  branch:
    - main
  event:
    - push
    - pull_request

Blok when berada di dalam satu langkah dan hanya mengontrol langkah tersebut. Ini berguna ketika Anda ingin sebagian besar _pipeline_ berjalan di mana-mana tetapi menyimpan _test pass_ yang lebih berat untuk satu _branch_.

steps:
  - name: run-api-tests
    image: node:20-alpine
    commands:
      - npm install -g apidog-cli
      - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli
    when:
      branch:
        - main
      event:
        - push

Kedua blok mendukung pola _glob_ dan sub-kunci _include/exclude_. Jenis _event_ yang didukung termasuk push, pull_request, tag, promote, rollback, cron, dan custom.

Mengekspos Laporan Tes Tanpa _Artifact Store_

Drone tidak memiliki hosting _artifact_ asli. Hal itu mengubah cara Anda menangani laporan, tetapi Anda memiliki dua opsi bersih.

Yang pertama adalah yang paling sederhana: gunakan _reporter_ cli sehingga hasilnya dicetak ke log _build_. Bagi sebagian besar tim ini sudah cukup, karena log sudah menunjukkan _assertion_ mana yang berhasil dan mana yang gagal.

Opsi kedua adalah membuat laporan HTML dan mengunggahnya ke tempat yang tahan lama. Drone menerbitkan _plugin_ S3 resmi, plugins/s3, yang mengunggah file ke S3 atau _store_ yang kompatibel dengan S3 lainnya. Hasilkan laporan dengan _reporter_ html dan --out-dir, lalu tambahkan langkah unggah.

steps:
  - name: run-api-tests
    image: node:20-alpine
    environment:
      APIDOG_ACCESS_TOKEN:
        from_secret: apidog_access_token
    commands:
      - npm install -g apidog-cli
      - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -r cli,html --out-dir reports

  - name: upload-report
    image: plugins/s3
    settings:
      bucket: my-bucket
      region: us-east-1
      source: reports/**/*
      target: /apidog-reports
      access_key:
        from_secret: aws_access_key
      secret_key:
        from_secret: aws_secret_key

Plugin membaca kredensial AWS-nya dari _secret_ melalui from_secret, mekanisme yang sama yang Anda gunakan untuk _token_ Apidog. Kunci source adalah _glob_ file yang akan diunggah, dan target adalah _prefix_ tujuan di _bucket_.

Jika Anda ingin melihat lebih dalam tentang isi laporan dan cara membacanya, lihat rincian laporan tes Apidog CLI.

Menambahkan Eksekusi Berbasis Data

Terkadang satu skenario perlu dijalankan terhadap banyak baris _input_: sepuluh ID pengguna, selusin _payload_, serangkaian _edge case_. CLI menangani ini dengan -d, yang menerima jalur file CSV atau JSON atau ID _data-set_ yang disimpan.

commands:
  - npm install -g apidog-cli
  - apidog run --access-token $APIDOG_ACCESS_TOKEN -t 1234567 -e 89012 -d ./data.csv -r cli

Setiap baris di data.csv menjadi satu iterasi, dengan nilai kolom terikat ke variabel skenario Anda. Pola lengkap dibahas dalam pengujian berbasis data Apidog CLI.

Bagaimana Ini Dibandingkan dengan _Tool_ CI Lain

Pola Drone, instal CLI dalam kontainer bersih dan jalankan satu perintah, berlaku untuk hampir setiap sistem CI. Sintaks pembungkus berbeda, tetapi langkah Apidog sama.

Jika Anda juga menjalankan _pipeline_ di tempat lain, Apidog memiliki panduan yang sesuai untuk GitHub Actions dan Azure Pipelines. Ide yang sama adalah bahwa tes Anda ada di Apidog dan _tool_ CI hanya memicunya.

Satu catatan jujur tentang cakupan: Apidog CLI menjalankan tes fungsional dan kontrak, bukan pengujian beban skala besar. Jika Anda membutuhkan ribuan pengguna virtual bersamaan untuk menekan _endpoint_, gunakan _tool_ pengujian beban khusus. Untuk memverifikasi bahwa API Anda berfungsi dengan benar pada setiap _commit_, CLI dalam langkah Drone melakukan tugas dengan baik.

Bangun Tes Secara Visual, Jalankan dengan Satu Perintah

Alur kerja yang membuat ini menyenangkan adalah pemisahan antara penulisan dan eksekusi. Anda mendesain _endpoint_ dan menyusun skenario tes secara visual di Apidog, merangkai permintaan, menegaskan kode status dan bidang respons, dan menggunakan kembali variabel lingkungan. Tidak ada kode yang diperlukan untuk membangun _suite_.

Kemudian CI menjalankan _suite_ yang sama dengan satu perintah CLI di dalam langkah kontainer. Ketika rekan tim memperbarui tes di aplikasi Apidog, _build_ Drone berikutnya akan mengambilnya secara otomatis. Tidak ada salinan kedua dari tes yang perlu disinkronkan.

Unduh Apidog secara gratis untuk membangun skenario tes pertama Anda, lalu letakkan .drone.yml di atas ke repositori Anda untuk menjalankannya pada setiap _push_.

Pertanyaan yang Sering Diajukan

Apa itu Drone CI?

Drone adalah platform CI/CD _open-source_ dan _container-native_, sekarang menjadi bagian dari Harness. Ia menjalankan setiap langkah _pipeline_ di dalam kontainer Docker-nya sendiri, dengan _pipeline_ didefinisikan dalam file .drone.yml. Ini menjaga _build_ dapat direproduksi dan menghindari penyebaran _tool_ yang sudah terinstal sebelumnya dari _agent_ _build_ tradisional.

Apakah Drone CI gratis?

Proyek inti Drone bersifat _open-source_ dan gratis untuk di-_self-host_. Setelah akuisisi Harness, Drone menjadi Harness CI Community Edition, dengan tingkatan _enterprise_ berbayar tersedia. Untuk sebagian besar tim, versi _open-source_ yang di-_self-host_ mencakup menjalankan tes API seperti yang ada di panduan ini.

Apakah Drone CI _open-source_?

Ya. Drone adalah salah satu _tool_ CI _container-native_ asli dan tetap _open-source_. Ketika Harness mengakuisisinya pada tahun 2020, perusahaan berkomitmen untuk menjaga proyek tetap _open-source_, dan Anda masih dapat me-_self-host_-nya.

Bagaimana Drone CI digunakan?

Tim menggunakan Drone untuk secara otomatis membangun, menguji, dan mengirimkan kode pada setiap _push_ atau _pull request_. Anda melakukan _commit_ file .drone.yml ke repositori Anda, Drone membacanya, dan menjalankan setiap langkah dalam kontainer. Langkah-langkah umum termasuk mengkompilasi kode, menjalankan tes unit, menjalankan tes API, dan mengunggah _artifact_ ke penyimpanan eksternal.

Bagaimana cara menyimpan _secret_ di Drone CI?

Anda menambahkan _secret_ melalui layar Pengaturan Repositori (_Repository's Settings_) lalu _Secret_ di UI Drone, atau dengan drone secret add dari CLI. Anda kemudian mereferensikan setiap _secret_ di dalam blok environment sebuah langkah atau blok settings sebuah _plugin_ menggunakan from_secret, di mana nilainya adalah nama _secret_. _Token_ itu sendiri tidak pernah muncul di YAML Anda.

Bisakah saya menjalankan tes Apidog di CI tanpa menulis _script_?

Ya. Anda membangun skenario tes secara visual di aplikasi Apidog, lalu menjalankannya di CI dengan satu perintah apidog run. Langkah Drone hanya membutuhkan _image_ Node, baris npm install -g apidog-cli, dan perintah eksekusi yang menunjuk ke ID skenario dan lingkungan Anda.