Sebagian besar pengujian API dimulai di GUI. Anda mengklik-klik, menambahkan beberapa *assertion*, dan menjalankannya secara manual. Itu berhasil sampai Anda membutuhkan tes yang sama untuk berjalan di setiap *push*, setiap malam, atau di dalam *pipeline* di mana tidak ada yang mengawasi. Pada titik itu Anda menginginkan satu perintah yang dapat Anda ketik, skrip, dan salurkan ke CI.
Perintah itu adalah Apidog CLI. Tutorial ini akan memandu Anda menguji REST API nyata secara *end-to-end* dari terminal Anda: menginstal alat, mengimpor API, menyiapkan lingkungan, membangun skenario pengujian, menjalankannya dengan *assertion*, memberinya data, dan mengumpulkan laporan. Setiap perintah dan keluaran di bawah ini berasal dari eksekusi nyata pada Apidog CLI versi 2.2.2 terhadap API publik langsung, sehingga Anda dapat mengikuti dan mendapatkan hasil yang sama.
Jika Anda menginginkan sisi visual dari platform yang sama, Anda dapat mengunduh Apidog dan mendesain pengujian di aplikasi terlebih dahulu. Namun, semua yang ada di sini tetap menggunakan baris perintah.
Apa yang akan Anda bangun
Anda akan menguji restful-api.dev, sebuah REST API publik gratis dengan CRUD nyata melalui sumber daya /objects. Pada akhirnya Anda akan memiliki:
- Sebuah proyek Apidog yang diinisialisasi dari berkas OpenAPI
- Skenario pengujian tiga langkah yang membuat objek, membacanya kembali, dan menghapusnya, dengan *assertion* di setiap langkah
- Eksekusi berbasis data yang mengulang permintaan sekali per baris data pengujian
- Laporan CLI, HTML, JSON, dan JUnit, ditambah laporan *cloud* yang dapat dibagikan
Alur yang sama dapat diskalakan ke API Anda sendiri, dan itu adalah dasar untuk menjalankan pengujian API di CI/CD.
Sebelum Anda memulai
Anda memerlukan Node.js 16 atau yang lebih baru dan akun Apidog. Jika Anda membandingkan *runner* terlebih dahulu, versi singkatnya adalah Apidog CLI menjalankan skenario pengujian lengkap dan mengelola sumber daya API sebagai kode, yang membedakannya dari Newman dan Postman CLI.
Langkah 1: Instal dan masuk
Instal CLI secara global dari npm:
npm install -g apidog-cli@latest
Konfirmasi keberadaannya:
apidog --version
# 2.2.2
Sekarang otentikasi. Ambil token dari aplikasi Apidog di bawah avatar Anda, Pengaturan Akun, Token Akses API, lalu jalankan:
apidog login --with-token <YOUR_TOKEN>
Token disimpan di ~/.apidog/config.toml, jadi Anda hanya perlu melakukan ini sekali per mesin. Periksa siapa Anda:
Setiap perintah mengembalikan JSON terstruktur dengan *flag* success dan agentHints yang membantu, yang membuat keluaran mudah untuk diskrip atau disalurkan ke jq.
Langkah 2: Buat proyek
Pilih tim untuk membuat proyek di bawahnya, lalu buat:
apidog team list
apidog project create --team 329562 --name "CLI Field Test"
Anda akan mendapatkan id proyek baru.
Simpan ke variabel *shell* agar sisa tutorial ini dapat disalin-tempel:
PID=1314366 # ganti dengan id proyek Anda
apidog project get $PID
Langkah 3: Impor REST API Anda
Anda bisa membuat *endpoint* secara manual, tetapi mengimpor berkas OpenAPI lebih cepat dan mencerminkan bagaimana proyek nyata dimulai. Berikut adalah spesifikasi kecil yang menjelaskan *endpoint* CRUD /objects (simpan sebagai objects-api.openapi.json):
{
"openapi": "3.0.3",
"info": { "title": "Objects API", "version": "1.0.0" },
"servers": [{ "url": "https://api.restful-api.dev" }],
"paths": {
"/objects": {
"get": { "summary": "List objects" },
"post": { "summary": "Create object" }
},
"/objects/{id}": {
"get": { "summary": "Get object by id" },
"put": { "summary": "Update object" },
"delete": { "summary": "Delete object" }
}
}
}
Impor:
apidog import --project $PID --format openapi --file ./objects-api.openapi.json
# "createCount": 5 (5 endpoint dibuat, 0 kesalahan)
*Importer* juga membaca openapi, postman, har, insomnia, jmeter, dan lainnya. Cantumkan apa yang telah diimpor:
apidog endpoint list --project $PID
# 37921721 get /objects
# 37921722 post /objects
# 37921723 get /objects/{id}
# 37921724 put /objects/{id}
# 37921725 delete /objects/{id}
Langkah 4: Siapkan lingkungan
Sebuah lingkungan menyimpan URL dasar dan variabel apa pun yang digunakan kembali oleh pengujian Anda. Buat satu dan simpan ID-nya:
apidog environment create "Production" --project $PID --base-url "https://api.restful-api.dev"
apidog environment list --project $PID
# { "id": 6334917, "name": "Production", "baseUrls": { "default": "https://api.restful-api.dev" } }
ENV=6334917 # ganti dengan id lingkungan Anda
Anda akan meneruskan -e $ENV ke perintah *run* nanti agar pengujian tahu ke mana harus mengirim permintaan.
Langkah 5: Lewati gerbang penulisan otomatisasi
Inilah hal pertama yang sering membingungkan orang. Skenario pengujian dan data pengujian adalah sumber daya otomatisasi, dan menuliskannya ke cabang utama Anda dari alat eksternal diblokir secara *default*:
apidog test-scenario create --project $PID --name "x" --description "" --folder-id 0 --priority 1
# "error": { "code": "403075", "message": "Automation caller branch required" }
Ini adalah *guardrail*, bukan *bug*. Anda memiliki dua cara untuk melewatinya:
- Aktifkan izin edit langsung di aplikasi desktop Apidog di bawah Project Settings, Feature Settings, AI Feature Settings, External AI Edit Permissions.
- Bekerja pada cabang AI, yang menjaga perubahan otomatisasi terisolasi sampai Anda memilih untuk menggabungkan. Jalur ini sepenuhnya menggunakan baris perintah, jadi itulah yang akan kita gunakan.
Buat cabang dari main:
apidog branch create --project $PID --type ai \
--name "ai/20260616-from-main-cli-field-test" --from main
BR="ai/20260616-from-main-cli-field-test"
Pola penamaan ai/YYYYMMDD-from-- adalah konvensi yang diharapkan CLI. Perhatikan bahwa import, environment create, dan pengeditan *endpoint* tidak digerbang; hanya sumber daya otomatisasi saja yang digerbang.
Langkah 6: Bangun skenario pengujian
Skenario adalah alur permintaan terurut dengan *assertion* di antaranya. Anda membuat *shell*-nya terlebih dahulu, lalu menambahkan langkah-langkah. Buat di cabang AI Anda:
apidog test-scenario create --project $PID --branch "$BR" \
--name "Object CRUD lifecycle" \
--description "Create, read, then delete an object and assert each step" \
--folder-id 0 --priority 1
SID=1836498 # id skenario yang dikembalikan
Langkah-langkah ditambahkan melalui update dengan berkas JSON. Aturan emas dengan penulisan JSON apa pun adalah memvalidasi sebelum Anda mengirimnya, agar Anda tidak pernah mendorong *payload* yang salah format:
apidog cli-schema get test-scenario-update # lihat bentuk pastinya
apidog cli-schema validate test-scenario-update --file ./steps-crud.json
# "data file is valid"
Setiap langkah adalah permintaan ditambah skrip kecil yang menegaskan respons dan menyerahkan data ke langkah berikutnya. Berikut adalah bentuk langkah pembuatan, yang mem-*posting* objek baru dan menyimpan id-nya untuk langkah-langkah selanjutnya:
{
"type": "customHttp",
"name": "Create object",
"customHttpRequest": {
"path": "https://api.restful-api.dev/objects",
"method": "post",
"requestBody": { "type": "json", "data": "{\"name\":\"Apidog CLI Field Test\",\"data\":{\"price\":42}}" },
"postProcessors": [{
"type": "customScript",
"data": "pm.test('create returns 200', function () { pm.response.to.have.status(200); });\nvar body = pm.response.json();\npm.globals.set('objId', body.id);",
"enable": true
}],
"projectId": 1314366
}
}
Langkah selanjutnya menggunakan kembali {{objId}} di URL untuk mengambil dan kemudian menghapus objek yang sama. Terapkan berkas tiga langkah lengkap:
apidog test-scenario update $SID --project $PID --branch "$BR" --file ./steps-crud.json
# "success": true
Anda tidak harus membuat skenario sebagai JSON. Membangunnya secara visual di Apidog dan menjalankannya dari CLI juga sama validnya. Jalur JSON penting ketika Anda ingin pengujian Anda terkontrol versi dan ditinjau seperti kode lainnya.
Langkah 7: Jalankan dari baris perintah
Inilah hasilnya. Jalankan skenario dengan *reporter* CLI:
apidog run -t $SID --project $PID --branch "$BR" -e $ENV -r cli
❏ Object CRUD lifecycle
↳ Create object POST .../objects [200 OK]
✓ create returns 200 ✓ response has an id ✓ name was echoed back
↳ Get the created object GET .../objects/ff80...3de [200 OK]
✓ get returns 200 ✓ id matches the created object ✓ price persisted in data
↳ Delete the object DELETE .../objects/ff80...3de [200 OK]
✓ delete returns 200
Permintaan Http 3 / 0 gagal
Assertion 7 / 0 gagal
Tiga permintaan, tujuh *assertion*, nol kegagalan, dan id yang dibuat mengalir dari langkah pertama ke dua langkah berikutnya. Itu adalah pengujian API lengkap yang berjalan tanpa satu klik pun.
Ingin berkas alih-alih keluaran konsol? Minta beberapa *reporter* sekaligus dan arahkan ke sebuah folder:
apidog run -t $SID --project $PID --branch "$BR" -e $ENV \
-r cli,html,json,junit --out-dir ./reports --out-file "crud-report"
ls ./reports
# crud-report.html crud-report.json crud-report.xml
XML JUnit adalah apa yang dibaca oleh *server* CI Anda untuk menunjukkan lulus/gagal per *build*. Laporan HTML adalah yang Anda bagikan dengan rekan tim.
Langkah 8: Jalankan pengujian yang sama terhadap banyak masukan
Paket pengujian nyata mencakup lebih dari satu kasus. Eksekusi berbasis data mengulang skenario sekali per baris data, sehingga Anda menguji sepuluh masukan tanpa menulis sepuluh skenario. Ini adalah ide yang sama dengan pengujian berparameter dari CSV dan JSON.
Masukkan baris Anda dalam berkas:
[
{ "name": "Pixel 8 Pro", "price": 999 },
{ "name": "iPhone 15", "price": 899 },
{ "name": "Galaxy S24", "price": 799 }
]
Referensi data dengan -d, dan biarkan skenario membaca {{name}} dan {{price}} dari setiap baris:
apidog run -t $DID --project $PID --branch "$BR" -e $ENV -d ./objects-data.json -r cli
Iterasi 1/3 … ✓ baris dibuat (200) ✓ nama cocok dengan baris data
Iterasi 2/3 … ✓ baris dibuat (200) ✓ nama cocok dengan baris data
Iterasi 3/3 … ✓ baris dibuat (200) ✓ nama cocok dengan baris data
Iterasi 3 / 0 gagal Assertion 6 / 0 gagal
Tiga baris masuk, tiga iterasi keluar. Tukar berkas dengan CSV dan tidak ada yang berubah.
Langkah 9: Kumpulkan laporan
Eksekusi lokal menulis berkas. Untuk mendapatkan laporan yang dapat dibuka oleh seluruh tim Anda di *browser*, tambahkan --upload-report:
apidog run -t $SID --project $PID --branch "$BR" -e $ENV -r cli --upload-report
# Data eksekusi Apidog CLI berhasil diunggah ke cloud.
# https://app.apidog.com/link/project/1314366/api-test/test-report/2605398
Satu hal yang perlu diketahui: laporan *cloud* diberi tag dengan cabang tempat ia dijalankan. Karena eksekusi ini terjadi di cabang AI Anda, apidog test-report list --project $PID biasa (yang menargetkan main) tidak akan menunjukkannya. Ambil laporan itu berdasarkan ID dari tautan unggahan saja:
apidog test-report get 2605398 --project $PID
apidog test-report download 2605398 --project $PID --format json --output ./cloud-report.json
Langkah 10: Ekspor API Anda sebagai dokumen atau spesifikasi
CLI juga mengeluarkan data. Ekspor proyek sebagai berkas OpenAPI, Markdown, atau dokumen HTML:
apidog export --project $PID --format openapi --oas-version 3.0 --output ./openapi-export.json
apidog export --project $PID --format markdown --output ./api-docs.md
apidog export --project $PID --format html --output ./api-docs.html
Ini berguna untuk meng-*commit* spesifikasi baru pada setiap perubahan atau memublikasikan dokumen statis dari *pipeline*.
Langkah 11: Sambungkan ke CI/CD
Semua yang Anda jalankan secara manual menjadi tiga baris dalam sebuah *pipeline*. Intinya adalah instalasi, lalu jalankan dengan *reporter* JUnit agar *server* CI dapat membaca hasilnya:
- run: npm install -g apidog-cli@latest
- run: apidog login --with-token $APIDOG_TOKEN
- run: apidog run -t $SID --project $PID -e $ENV -r junit --out-dir ./reports
Simpan token sebagai rahasia, dan gagal-*build* ketika sebuah pengujian gagal (CLI mengembalikan kode keluar non-nol pada kegagalan). Untuk alur kerja lengkap yang dapat disalin-tempel, lihat panduan tentang menjalankan pengujian Apidog CLI di GitHub Actions, atau jelajahi alat otomatisasi pengujian API yang cocok untuk *pipeline*.
Ringkasan
Anda beralih dari terminal kosong ke pengujian API berbasis data yang berhasil dengan laporan yang dapat dibagikan, dan Anda tidak pernah meninggalkan baris perintah. Polanya selalu sama: impor atau desain API Anda, buat lingkungan, bangun skenario dengan *assertion*, lalu jalankan dengan apidog run. Setelah perintah itu berfungsi secara lokal, memasukkannya ke CI adalah perubahan tiga baris.
Arahkan langkah-langkah yang sama ke API Anda sendiri, *commit* berkas skenario bersama kode Anda, dan pengujian Anda berjalan di mana pun *shell* berjalan. Unduh Apidog untuk memulai, dan simpan alternatif *curl* untuk pengujian REST API agar praktis untuk pemeriksaan cepat satu kali yang mana CLI terlalu berlebihan.