Blog

Cara Menjalankan Tes API Otomatis di TeamCity

Jalankan pengujian API otomatis secara menyeluruh di TeamCity: rancang pengujian di Apidog, jalankan secara headless dengan Apidog CLI, urai hasil JUnit, dan blokir penggabungan yang buruk.

Ashley Innocent

Ashley Innocent

15 June 2026

Cara Menjalankan Tes API Otomatis di TeamCity

Apidog untuk Perusahaan

Penerapan On-Premises

SSO & RBAC

Sesuai SOC 2

Jelajahi Apidog Enterprise

API Anda lolos setiap pengujian di laptop Anda. Kemudian rekan tim menggabungkan cabang yang mengganti nama bidang, dan tidak ada yang menyadarinya sampai klien seluler mulai *crash* di lingkungan produksi. Pengujian manual melewatkannya karena tidak ada yang menjalankan kembali *suite* tersebut. Inilah celah persis yang ingin ditutup oleh integrasi berkelanjutan, dan TeamCity adalah salah satu alat terkuat untuk menutupnya.

TeamCity, server CI/CD JetBrains, menjalankan *pipeline* *build* Anda setiap kali kode masuk. Ia dapat mengkompilasi, menguji, mengemas, dan menerapkan tanpa ada yang mengklik tombol. Bagian yang sering dilewati tim adalah menyambungkan pengujian API yang sesungguhnya ke dalam *pipeline* tersebut. Mereka menguji unit, mereka menguji kompilasi *build*, dan mereka mengirimkan API berdasarkan asumsi. Bidang yang diganti namanya, respons 500 pada kasus ekstrem, alur autentikasi yang rusak; tidak ada yang muncul sampai manusia mengenai *endpoint* tersebut.

Panduan ini menjelaskan cara menjalankan pengujian API otomatis di dalam TeamCity secara menyeluruh. Anda akan merancang dan memvalidasi pengujian Anda di Apidog, lalu menjalankannya secara *headless* melalui Apidog CLI sebagai langkah *build* TeamCity. Hasilnya adalah *pipeline* yang akan menggagalkan *build* saat API Anda berhenti berfungsi, sebelum respons yang buruk mencapai pengguna.

tombol

Apa yang akan Anda bangun

Pada akhirnya Anda akan memiliki:

Pola yang sama berlaku untuk layanan internal kecil atau API publik dengan ratusan *endpoint*. Anda menskalakannya dengan menambahkan skenario pengujian di Apidog, bukan dengan mengedit kode *pipeline*.

Mengapa pengujian API harus ada di TeamCity, tidak hanya di mesin Anda

Pengujian lokal memiliki satu kelemahan fatal: itu tergantung pada seseorang yang mengingat untuk menjalankannya. CI menghilangkan peran manusia dalam proses. Setiap *commit* memicu *suite* yang sama, di lingkungan yang sama, dengan *assertion* yang sama. Tidak ada "ini bekerja di mesin saya" karena tidak ada mesin; ada agen *build* yang menjalankan langkah-langkah persis yang Anda definisikan.

TeamCity sangat cocok untuk ini karena beberapa alasan konkret:

Masalahnya adalah TeamCity tidak tahu cara memanggil API Anda atau memeriksa responsnya. Ia menjalankan perintah apa pun yang Anda berikan. Jadi pekerjaan sebenarnya adalah menghasilkan satu perintah yang menjalankan seluruh *suite* API Anda dan keluar dengan kode bukan nol ketika ada yang gagal. Di situlah desain pengujian menjadi penting.

Langkah 1: Rancang dan validasi pengujian API Anda di Apidog

Sebelum ada yang menyentuh TeamCity, Anda memerlukan pengujian yang benar-benar berjalan secara otomatis. Pengujian yang memerlukan Anda untuk memeriksa respons JSON secara manual tidak berguna dalam CI. Setiap pemeriksaan harus berupa *assertion* yang dapat dievaluasi mesin: kode status adalah 200, bidang id adalah angka, respons kembali dalam waktu kurang dari 800 ms.

Apidog dibangun khusus untuk ini. Anda merancang permintaan, lalu melampirkan *assertion* API yang memvalidasi respons secara otomatis; kode status, kesesuaian JSON Schema, nilai bidang spesifik, waktu respons. Anda dapat merangkai permintaan menjadi skenario sehingga *output* dari panggilan *login* memasukkan *token* ke permintaan berikutnya. Tidak diperlukan *scripting* untuk kasus umum, dan *scripting* penuh tersedia saat Anda membutakannnya.

Skenario realistis untuk API *e-commerce* mungkin terlihat seperti ini:

  1. POST /auth/login dengan kredensial pengujian, *assert* 200, ekstrak *bearer token* ke dalam variabel.
  2. GET /products?category=books dengan *token* tersebut, *assert* 200, *assert* respons adalah sebuah *array*, *assert* setiap item memiliki price lebih besar dari 0.
  3. POST /cart/items dengan ID produk, *assert* 201, *assert* total keranjang yang dikembalikan cocok dengan harga item.
  4. GET /cart, *assert* jumlah item adalah 1.

Setiap langkah memiliki *assertion* yang lolos atau gagal dengan sendirinya. Jalankan skenario di dalam Apidog terlebih dahulu dan konfirmasikan bahwa itu berjalan hijau terhadap lingkungan *staging* Anda. Jika tidak dapat lolos saat Anda menjalankannya secara manual, itu tidak akan pernah lolos di CI. Kelompokkan skenario terkait ke dalam *test suite* sehingga Anda dapat menjalankan semuanya dengan satu perintah alih-alih skenario demi skenario.

Keuntungan membangun pengujian dengan cara ini adalah skenario yang sama yang Anda gunakan untuk *debugging* manual menjadi *suite* CI Anda. Anda tidak perlu memelihara dua set pengujian paralel; satu di GUI untuk eksplorasi, satu dalam kode untuk otomatisasi. Ini adalah satu sumber kebenaran. Jika Anda berasal dari *framework* yang mengutamakan kode seperti REST Assured, inilah bagian yang paling menghemat waktu: Anda berhenti menulis dan menulis ulang kode permintaan/*assertion* *boilerplate* untuk setiap *endpoint*.

Unduh Apidog jika Anda ingin mengikuti. Gratis untuk memulai, dan CLI adalah bagian dari *toolchain* yang sama.

Langkah 2: Jalankan Apidog CLI secara lokal terlebih dahulu

Jangan pernah melakukan *debugging* perintah baru untuk pertama kalinya di dalam CI. Lingkaran umpan balik di server CI sangat kejam; Anda *push*, menunggu agen, membaca *log*, memperbaiki satu karakter, *push* lagi. Buktikan perintah tersebut bekerja di mesin Anda, lalu salin versi yang berfungsi ke TeamCity.

Apidog CLI berjalan di Node.js, jadi instal secara global dengan npm:

npm install -g apidog-cli

Konfirmasikan keberadaannya:

apidog --version

Sekarang jalankan skenario pengujian Anda. CLI dapat menjalankan skenario atau *suite* langsung dari proyek Apidog Anda dengan mereferensikan ID-nya, diautentikasi dengan *access token*, atau dari file yang diekspor secara lokal. Pendekatan *online* menjaga pengujian Anda sebagai satu sumber kebenaran; apa pun yang diedit tim Anda di Apidog adalah apa yang berjalan di CI, tanpa langkah ekspor yang terlupakan.

Buat *access token* dari pengaturan akun Apidog Anda, lalu jalankan:

apidog run \
 --access-token "$APIDOG_ACCESS_TOKEN" \
 -e "$APIDOG_ENV_ID" \
 -r cli,html,junit

Beberapa hal yang perlu diperhatikan di sini:

Ketika eksekusi selesai, CLI keluar 0 jika semuanya lolos dan bukan nol jika ada *assertion* yang gagal. Kode keluar tersebut adalah kunci dalam CI: kode keluar bukan nol adalah yang memberi tahu TeamCity untuk menandai *build* sebagai gagal.

Untuk pengujian yang perlu dijalankan dengan banyak masukan, CLI mendukung eksekusi berbasis data. Arahkan ke file CSV atau JSON dan ia akan mengulang skenario sekali per baris:

apidog run \
 --access-token "$APIDOG_ACCESS_TOKEN" \
 -d test-data/checkout-cases.csv \
 -r cli,junit

Ini adalah cara Anda menguji seratus ID produk atau tabel *payload* yang tidak valid tanpa menulis seratus skenario. Setiap baris menjadi iterasi sendiri dengan hasil lolos/gagalnya sendiri.

Setelah Anda melihat *output* hijau secara lokal, Anda memiliki perintah yang Anda percaya. Salin itu. Perintah persis itulah yang masuk ke TeamCity.

Langkah 3: Hubungkan TeamCity ke repositori Anda

Sekarang beralih ke TeamCity. Tujuan langkah ini adalah untuk memberikan proyek kepada TeamCity, mengarahkannya ke kode Anda, dan membiarkannya memicu *build* pada setiap *push*.

Jika Anda menjalankan TeamCity untuk pertama kalinya, jalur paling sederhana adalah *image* Docker resmi. Ini memberi Anda server yang berfungsi dalam beberapa menit:

docker run -d --name teamcity-server \
 -v ~/teamcity/datadir:/data/teamcity_server/datadir \
 -v ~/teamcity/logs:/opt/teamcity/logs \
 -p 8111:8111 \
 jetbrains/teamcity-server

Buka http://localhost:8111, selesaikan pengaturan awal (*pilihan database*, akun admin), dan Anda akan mendarat di *dashboard*. Pengaturan produksi menggunakan *database* eksternal yang tepat dan agen *build* khusus, tetapi untuk mengikuti panduan ini agen bawaan sudah cukup.

Buat proyek:

  1. Buka Administrasi dan pilih Buat proyek.
  2. Pilih Dari URL repositori dan tempel *remote* Git Anda (HTTPS atau SSH).
  3. Tambahkan kredensial jika repositori bersifat pribadi; *deploy key* atau *personal access token*.
  4. TeamCity memindai repositori dan harus mendeteksi langkah-langkah *build* secara otomatis. Anda bisa membiarkannya, tetapi untuk pengujian API lebih bersih untuk mengonfigurasi langkahnya sendiri di bagian berikutnya.

TeamCity membuat *VCS root* (koneksinya ke repositori Anda) dan konfigurasi *build* (serangkaian langkah yang berjalan). Dengan *VCS root* yang sudah ada, atur *trigger* agar *build* berjalan secara otomatis:

  1. Buka konfigurasi *build* Anda dan pergi ke Triggers.
  2. Tambahkan VCS Trigger.
  3. Biarkan aturan *default* agar setiap perubahan pada cabang yang diawasi mengantrekan *build*.

Dari sini, setiap *push* ke repositori Anda akan memicu *build*. Saat ini *build* tersebut tidak melakukan hal yang berguna; langkah selanjutnya memberikannya perintah pengujian API.

Langkah 4: Tambahkan Apidog CLI sebagai langkah *build*

Ini adalah inti dari penyiapan. Anda menambahkan langkah *build* yang menginstal CLI pada agen dan menjalankan *suite* Anda.

Dalam konfigurasi *build* Anda, buka Build Steps dan tambahkan langkah baru bertipe Command Line. Pilih Custom script dan tempel:

#!/bin/bash
set -e

# Install the Apidog CLI on the build agent
npm install -g apidog-cli

# Run the API test suite and emit a JUnit report for TeamCity
apidog run \
 --access-token "%env.APIDOG_ACCESS_TOKEN%" \
 -e "%env.APIDOG_ENV_ID%" \
 -r cli,junit \
 --out-dir reports

Itu adalah perintah yang sama yang Anda buktikan secara lokal, dengan dua perubahan untuk CI. Pertama, set -e membuat *script* berhenti pada kesalahan apa pun. Kedua, rahasia direferensikan sebagai parameter TeamCity (%env.APIDOG_ACCESS_TOKEN%) alih-alih di-*hardcode*; Anda akan mendefinisikannya selanjutnya.

Jika agen *build* Anda belum memiliki Node.js, instal lebih awal dalam rantai atau gunakan *image* agen yang menyertakannya. *Image* Docker agen TeamCity resmi dan sebagian besar *pool* agen *cloud* sudah dilengkapi dengan Node.js. Anda juga dapat menjalankan seluruh langkah di dalam kontainer Node dengan mengatur langkah agar berjalan di *image* Docker seperti node:20.

Satu detail yang perlu diperhatikan: CLI harus berjalan *setelah* API Anda diterapkan dan dapat dijangkau. Jika TeamCity menguji layanan yang baru saja diterapkan ke *staging*, buat *build* pengujian bergantung pada *build* penerapan menggunakan Snapshot Dependency atau Build Chain. Itu menjamin bahwa pengujian selalu mengenai versi API yang dihasilkan *commit* ini, bukan yang sebelumnya.

Langkah 5: Simpan rahasia sebagai parameter TeamCity

*Access token* Anda adalah kredensial. Itu tidak seharusnya ada dalam *script* *build*, di repositori Anda, atau di *log* *build*. TeamCity memiliki tempat kelas satu untuk ini.

  1. Dalam konfigurasi *build* Anda (atau proyek induk, untuk berbagi di seluruh konfigurasi), buka Parameters.
  2. Tambahkan parameter baru bernama env.APIDOG_ACCESS_TOKEN.
  3. Atur Spesifikasinya ke Password. Ini menyembunyikan nilai di UI dan membersihkannya dari *log* *build*.
  4. Tempel *access token* Apidog Anda sebagai nilai.
  5. Tambahkan env.APIDOG_ENV_ID dengan cara yang sama dengan ID lingkungan Anda (yang ini tidak rahasia, tetapi menjadikannya parameter memungkinkan Anda mengubah lingkungan tanpa mengedit *script*).

Mendefinisikan ini pada tingkat proyek daripada tingkat konfigurasi *build* berarti setiap *build* pengujian API di bawah proyek tersebut akan mewarisinya. Putar *token* sekali, dan setiap *pipeline* akan mengambil nilai baru.

Parameter kata sandi adalah perbedaan antara *token* yang aman di TeamCity dan *token* yang bocor ke file *log* yang dapat dibaca seluruh tim. Perlakukan seperti Anda memperlakukan kata sandi *database*.

Langkah 6: Tampilkan hasil pengujian di tab Tests TeamCity

Sebuah *build* yang hanya berwarna merah memberi tahu Anda ada sesuatu yang rusak. *Build* yang menunjukkan pengujian *mana* yang rusak memberi tahu Anda di mana harus mencari. Itulah yang diberikan oleh laporan JUnit.

*Reporter* -r junit menulis file XML dalam format JUnit, format hasil pengujian CI standar yang dapat dibaca secara native oleh TeamCity. Anda mengarahkan TeamCity ke file tersebut dengan fitur *build* Pemrosesan Laporan XML.

  1. Buka Build Features di konfigurasi *build* Anda.
  2. Tambahkan pemrosesan laporan XML.
  3. Atur jenis laporan ke Ant JUnit.
  4. Atur jalur pemantauan agar sesuai dengan *output* Anda, misalnya reports/*.xml.

Jalankan *build*. Buka dan klik tab Tests. Anda akan melihat setiap skenario dan *assertion* sebagai pengujian individual dengan status lolos/gagal dan waktu. Ketika pengujian gagal, TeamCity menunjukkan pesan kegagalan secara *inline*, menautkannya ke *commit* yang menyebabkannya, dan melacaknya di *build* mendatang. Jika pengujian yang sama gagal dua kali berturut-turut, TeamCity dapat menandainya sebagai kegagalan baru daripada yang *flaky*.

Ini adalah hasil dari pemilihan *output* JUnit sebelumnya. Tanpa itu, kegagalan adalah satu *build* merah dan tumpukan teks konsol. Dengan itu, Anda mendapatkan riwayat pengujian yang terstruktur dan dapat dicari yang mengubah "pengujian API rusak" menjadi "*assertion* total keranjang mulai gagal di *commit* a3f9c2."

Langkah 7: Gagalkan *build* dan blokir penggabungan

Tujuan dari semua ini adalah untuk menghentikan kode yang buruk agar tidak digabungkan. Dua hal yang membuatnya terjadi.

Pertama, kode keluar. Karena Apidog CLI keluar bukan nol pada setiap *assertion* yang gagal dan *script* Anda menggunakan set -e, pengujian yang gagal akan menggagalkan langkah *build*, yang akan menggagalkan *build*. Anda tidak perlu mengonfigurasi apa pun tambahan; pengujian API yang merah adalah *build* yang merah secara *default*.

Kedua, *merge gate*. Jika tim Anda bekerja dalam *pull request* atau *merge request*, konfigurasikan *host* Git Anda (GitHub, GitLab, Bitbucket) untuk mewajibkan pemeriksaan TeamCity lolos sebelum penggabungan. TeamCity melaporkan status *build*-nya kembali ke *commit* melalui fitur *build* Commit Status Publisher:

  1. Tambahkan fitur *build* **Commit Status Publisher**.
  2. Pilih penyedia *hosting* VCS Anda.
  3. Tambahkan *access token* agar TeamCity dapat memposting status.

Sekarang seorang kontributor membuka PR, TeamCity menjalankan *suite* API terhadap cabangnya, dan tombol gabung tetap dinonaktifkan sampai *suite* berwarna hijau. Skenario bidang yang diganti namanya dari awal panduan ini tertangkap di sini, di cabang, sebelum mencapai *main*.

*Pipeline* lengkap yang realistis

Menggabungkan semua bagian, konfigurasi *build* yang berfungsi untuk *pipeline* pengujian API terlihat seperti ini:

Untuk tim yang menyimpan seluruh konfigurasi CI mereka dalam kontrol versi, TeamCity mendukung pendefinisian semua ini dalam Kotlin DSL (.teamcity/settings.kts) yang di-*commit* ke repositori, alih-alih mengklik melalui UI. Langkah *build* adalah perintah apidog run yang sama dalam kedua cara; DSL hanya menjelaskan konfigurasi sebagai kode sehingga ditinjau dan di-*versioning* bersama dengan yang lainnya.

Anda dapat menjalankan *suite* tidak hanya pada setiap *push*. Tambahkan Schedule Trigger untuk menjalankan *full regression suite* setiap malam terhadap *staging*, sehingga Anda menangkap *drift* yang terjadi antar *commit*; dependensi pihak ketiga yang berubah, *database* yang masuk ke keadaan aneh. Eksekusi API malam hari adalah asuransi murah dan mereka menjaga *commit* pertama pagi hari agar tidak mewarisi lingkungan yang rusak dari kemarin.

Perbandingan ini dengan platform CI lainnya

Pola di sini bersifat portabel. Perintah yang menjalankan pengujian Anda (apidog run dengan *access token* dan *reporter* JUnit) identik, tidak peduli server CI mana yang memanggilnya. Hanya pembungkusnya yang berubah:

Jika Anda masih memilih server CI, perbandingan alat CI/CD terbaik kami menguraikan posisi TeamCity dibandingkan alternatif lain. Kekuatan TeamCity adalah rantai *build*-nya, riwayat pengujian yang terperinci, dan Kotlin DSL; ini adalah pilihan yang kuat untuk tim yang sudah berada di ekosistem JetBrains atau menjalankan *pipeline multi-stage* yang kompleks.

Masalah umum dan cara mengatasinya

FAQ

Ringkasan

*Pipeline* TeamCity yang menjalankan pengujian API Anda pada setiap *commit* mengubah ekonomi *endpoint* yang rusak. Alih-alih pelanggan yang menemukan *bug*, *build* lah yang menemukannya; di cabang, sebelum penggabungan, dengan *assertion* yang gagal dan *commit* yang menyebabkannya tertera di tab Tests.

Penyiapan ini melibatkan tiga bagian yang bergerak: pengujian dengan *assertion* nyata yang Anda bangun di Apidog, satu perintah apidog run yang menjalankannya secara *headless* dan keluar bukan nol saat gagal, serta konfigurasi *build* TeamCity yang menjalankan perintah tersebut, mengurai hasil JUnit, dan melaporkan status kembali ke *host* Git Anda. Setelah terpasang, Anda menjaga cakupan dengan menambahkan skenario di Apidog, bukan dengan menyentuh kode *pipeline*.

Unduh Apidog untuk merancang *suite* pengujian pertama Anda, buktikan perintah CLI secara lokal, lalu masukkan ke TeamCity. Sejak saat itu, API Anda diuji dengan cara yang sama pada setiap *commit*, apakah ada yang mengingat untuk menjalankannya atau tidak.

tombol

Mengembangkan API dengan Apidog

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

Daftar gratisUnduh