Cara Menjalankan Tes API Apidog CLI di CircleCI

Untuk menjalankan pengujian API Apidog CLI di CircleCI, tambahkan file .circleci/config.yml yang menggunakan eksekutor Docker cimg/node, menginstal apidog-cli dengan npm, dan menjalankan apidog run dengan token akses Anda, ID skenario pengujian, dan ID lingkungan. Simpan token dan ID sebagai variabel lingkungan CircleCI, lalu publikasikan laporan JUnit dan HTML dengan store_test_results dan store_artifacts. Panduan ini akan menjelaskan setiap bagian agar Anda bisa menyalin, menempel, dan menggunakannya.

Artikel ini adalah tentang menjalankan pengujian, bukan memilih platform CI. Jika Anda masih memutuskan antar alat, perbandingan CircleCI vs Jenkins membahas hal tersebut. Di sini kami mengasumsikan Anda sudah memilih CircleCI dan ingin rangkaian API Anda berjalan di setiap pendorongan (push).

Apa itu CircleCI dan bagaimana cara kerjanya

CircleCI adalah layanan integrasi dan pengiriman berkelanjutan berbasis cloud. Layanan ini memantau repositori Git Anda, dan ketika Anda mendorong (push) sebuah commit, CircleCI akan menjalankan langkah-langkah build, test, dan deploy yang telah Anda definisikan. Anda menjelaskan langkah-langkah tersebut dalam satu file YAML, sehingga pipeline Anda tersimpan dalam kontrol versi bersama kode Anda.

Semuanya dimulai dengan .circleci/config.yml di root repo Anda. CircleCI membaca file ini pada setiap pendorongan dan mengubahnya menjadi sebuah pipeline. Format konfigurasi saat ini adalah versi 2.1, yang menambahkan blok bangunan yang dapat digunakan kembali seperti orbs, perintah, dan parameter di atas mesin dasar 2.0.

Sebuah konfigurasi CircleCI memiliki tiga konsep inti:

Jobs (Pekerjaan) adalah unit kerja. Setiap pekerjaan menjalankan serangkaian steps (langkah), seperti melakukan checkout kode, menginstal dependensi, atau menjalankan perintah pengujian.
Executors (Eksekutor) mendefinisikan di mana suatu pekerjaan berjalan. Eksekutor Docker menjalankan langkah-langkah Anda di dalam sebuah image kontainer yang Anda pilih, seperti cimg/node untuk proyek Node.js.
Workflows (Alur Kerja) mengorkestrasi pekerjaan. Sebuah alur kerja memutuskan pekerjaan mana yang berjalan, dalam urutan apa, dan apakah berjalan secara paralel atau berurutan.

Pemisahan itu penting untuk pengujian API. Anda mendefinisikan satu pekerjaan yang menginstal Apidog CLI dan menjalankan skenario Anda, lalu sebuah alur kerja yang memicunya pada branch yang Anda minati.

Mengapa menjalankan pengujian API di CircleCI

Menjalankan rangkaian API Anda di CI menangkap pelanggaran kontrak sebelum mencapai produksi. Perubahan skema, bidang yang diganti nama, atau alur otentikasi yang rusak akan muncul sebagai build yang gagal (merah) alih-alih tiket dukungan.

Apidog CLI dibangun untuk tujuan ini. Anda merancang dan men-debug skenario pengujian di aplikasi Apidog, lalu menjalankan skenario yang sama secara headless di CI dengan satu perintah. Tidak perlu menulis ulang pernyataan dalam kode, dan tidak ada harness pengujian terpisah yang harus dipelihara.

Jika Anda ingin gambaran lebih luas tentang bagaimana pemeriksaan otomatis cocok dalam pipeline, 12 praktik terbaik CI/CD untuk pengujian API adalah bacaan pelengkap yang bagus.

Prasyarat

Sebelum Anda menulis konfigurasi, siapkan ini di aplikasi Apidog:

Sebuah token akses. Hasilkan di bawah pengaturan akun Apidog Anda. Ini mengotentikasi CLI di lingkungan headless. Panduan otentikasi Apidog CLI membahas pembuatan token dan penanganan rahasia CI secara rinci.
Sebuah ID skenario pengujian. Buka skenario pengujian yang ingin Anda jalankan dan salin ID-nya dari URL atau pengaturan skenario.
Sebuah ID lingkungan. Ini memberitahu CLI URL dasar dan variabel mana yang akan digunakan, seperti staging atau produksi.

Anda juga akan memerlukan akun CircleCI yang terhubung ke penyedia Git Anda, dengan proyek diaktifkan di dasbor CircleCI.

Menyimpan rahasia sebagai variabel lingkungan

Jangan pernah memasukkan token akses Anda secara langsung (hardcode) di config.yml. File tersebut di-commit ke Git, jadi token yang ada di sana berarti token yang bocor.

CircleCI memberi Anda dua opsi aman:

Variabel lingkungan proyek. Di UI CircleCI, buka Pengaturan Proyek, lalu Variabel Lingkungan, dan tambahkan setiap nilai. Variabel-variabel tersebut dienkripsi dan diekspos ke pekerjaan sebagai $VARS.
Konsteks. Konteks adalah grup variabel lingkungan bernama yang dibagikan di seluruh proyek. Anda membuatnya di bawah Pengaturan Organisasi, lalu Konteks, dan mereferensikannya dari alur kerja. Konteks berguna ketika beberapa repo berbagi token Apidog yang sama.

Untuk panduan ini, tambahkan tiga variabel: APIDOG_ACCESS_TOKEN, APIDOG_TEST_SCENARIO_ID, dan APIDOG_ENVIRONMENT_ID. CLI membacanya saat runtime, dan tidak ada yang sensitif tersimpan di repo Anda.

File config.yml lengkap

Berikut adalah konfigurasi lengkap yang bisa langsung disalin dan ditempel. Letakkan di .circleci/config.yml, atur tiga variabel lingkungan Anda, lalu lakukan push.

version: 2.1

jobs:
  api-tests:
    docker:
      - image: cimg/node:20.11
    steps:
      - checkout
      - run:
          name: Install Apidog CLI
          command: npm install -g apidog-cli
      - run:
          name: Run Apidog API tests
          command: |
            apidog run \
              --access-token $APIDOG_ACCESS_TOKEN \
              -t $APIDOG_TEST_SCENARIO_ID \
              -e $APIDOG_ENVIRONMENT_ID \
              -r cli,junit,html \
              --out-dir ./reports
      - store_test_results:
          path: ./reports
      - store_artifacts:
          path: ./reports

workflows:
  test-api:
    jobs:
      - api-tests

Izinkan saya menjelaskan apa yang dilakukan setiap bagian.

Eksekutor

docker:
  - image: cimg/node:20.11

cimg/node adalah image kemudahan CircleCI untuk Node.js. Image ini dilengkapi dengan Node, npm, dan alat build umum yang sudah terinstal, sehingga npm install -g apidog-cli berfungsi tanpa pengaturan tambahan. Tag :20.11 menentukan versi Node; gunakan versi yang distandarisasi oleh tim Anda.

Langkah-langkah

checkout menarik repositori Anda ke dalam direktori kerja job. Langkah run pertama menginstal CLI secara global. Langkah run kedua mengeksekusi pengujian Anda.

Perhatikan perintah pengujian dengan seksama:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  -r cli,junit,html \
  --out-dir ./reports

Setiap flag melakukan satu tugas:

--access-token mengautentikasi eksekusi. Tidak ada bentuk pendeknya.
-t memilih skenario pengujian berdasarkan ID.
-e memilih lingkungan. Flag ini wajib; CLI perlu mengetahui URL dasar dan variabel mana yang akan digunakan.
-r mengatur reporter. Di sini Anda meminta tiga: cli mencetak hasil langsung ke log build, junit menulis XML yang dapat dibaca mesin, dan html menulis laporan yang dapat dijelajahi.
--out-dir memberi tahu CLI di mana harus menulis file laporan.

Mempublikasikan laporan

- store_test_results:
    path: ./reports
- store_artifacts:
    path: ./reports

store_test_results menunjuk CircleCI ke JUnit XML di ./reports. CircleCI memparse-nya dan menampilkan tab Pengujian pada build, sehingga kegagalan dicantumkan berdasarkan nama dengan data waktu. Ini yang mengubah tumpukan teks log menjadi tampilan lulus/gagal yang terstruktur.

store_artifacts mengunggah direktori yang sama sebagai file yang dapat diunduh, termasuk laporan HTML. Setelah build, Anda membuka tab Artifacts dan melihat laporan yang dirender di browser Anda. Panduan laporan pengujian Apidog CLI menjelaskan format CLI, HTML, dan JSON secara lebih mendalam.

Alur kerja

workflows:
  test-api:
    jobs:
      - api-tests

Alur kerja ini menjalankan job api-tests pada setiap pendorongan. Anda dapat menambahkan filter untuk membatasinya pada branch tertentu, atau menambahkan job lain yang berjalan sebelum atau sesudahnya. Untuk satu job pengujian, blok minimal ini sudah cukup.

Jalankan pengujian hanya pada branch utama

Anda mungkin tidak ingin seluruh rangkaian API berjalan pada setiap branch fitur. Tambahkan filter branch ke alur kerja:

workflows:
  test-api:
    jobs:
      - api-tests:
          filters:
            branches:
              only:
                - main
                - develop

Sekarang job hanya berjalan pada pendorongan ke main dan develop. Branch lain akan dilewati, yang membuat waktu build Anda terfokus pada branch yang siap dirilis.

Gunakan Konteks alih-alih variabel proyek

Jika beberapa repositori berbagi satu token Apidog, sebuah Konteks menyimpannya di satu tempat. Buat Konteks di Pengaturan Organisasi, tambahkan variabel Anda di sana, lalu referensikan:

workflows:
  test-api:
    jobs:
      - api-tests:
          context:
            - apidog-secrets

Job kini membaca APIDOG_ACCESS_TOKEN dan sisanya dari Konteks apidog-secrets. Putar token sekali, dan setiap proyek akan menggunakan nilai baru.

Eksekusi berbasis data dan opsi lainnya

CLI memiliki lebih banyak flag daripada yang digunakan dalam panduan ini. Dua di antaranya penting untuk diketahui dalam CI.

Anda dapat mengulang skenario di seluruh baris data pengujian dengan -d dan -n:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  -d ./data/users.csv \
  -r cli,junit \
  --out-dir ./reports

Flag -d mengambil jalur file CSV atau JSON, atau ID set data tersimpan numerik, dan menjalankan skenario sekali per baris. Panduan pengujian berbasis data menunjukkan cara menyusun file-file tersebut.

Anda juga dapat mengontrol bagaimana eksekusi menangani kegagalan dengan --on-error, yang menerima continue, end, atau ignore. Dan untuk proyek yang menggunakan branch Apidog, --project--branchmenargetkan branch tertentu. Untuk mendorong gambaran umum laporan ke cloud Apidog, tambahkan --upload-report sebagai flag biasa.

Bagaimana ini sesuai dengan alur kerja Apidog

Inti dari Apidog CLI adalah Anda tidak menulis atau memelihara kode pengujian. Anda membangun skenario pengujian dari baris perintah atau di pembuat pengujian visual, menetapkan pernyataan pada kode status dan badan respons, lalu menyimpannya. CI kemudian menjalankan skenario yang persis sama itu.

Karena skenario tersimpan dalam proyek Apidog Anda, tim Anda mengedit pengujian di satu tempat. Konfigurasi CI jarang berubah; itu hanya memanggil apidog run. Ketika seseorang menambahkan pernyataan di aplikasi, build CircleCI berikutnya akan mengambilnya tanpa mengedit YAML.

Itu menjaga pemisahan yang bersih. Apidog memiliki apa yang diuji. CircleCI memiliki kapan dan di mana itu berjalan. Jika Anda ingin membandingkan CircleCI dengan runner lain untuk jenis pekerjaan ini, rangkuman alat integrasi berkelanjutan terbaik untuk tim API menjelaskan komprominya.

Siap menempatkan rangkaian API Anda di setiap pendorongan? Unduh Apidog, buat skenario pengujian, dan letakkan konfigurasi di atas ke repo Anda.

button

Pertanyaan yang Sering Diajukan

Apa itu CircleCI?

CircleCI adalah platform integrasi dan pengiriman berkelanjutan berbasis cloud. Ia terhubung ke repositori Git Anda, membaca file .circleci/config.yml, dan secara otomatis menjalankan langkah-langkah build, test, dan deploy setiap kali Anda mendorong kode. Ini menghilangkan kebutuhan untuk menjalankan langkah-langkah tersebut secara manual di mesin Anda sendiri.

Untuk apa CircleCI digunakan?

Tim menggunakan CircleCI untuk mengotomatiskan pengujian dan deployment. Tugas umum meliputi kompilasi kode, menjalankan pengujian unit dan integrasi, memeriksa kontrak API, membangun citra Docker, dan mengirimkan rilis ke staging atau produksi. Dalam panduan ini, tugasnya menjalankan pengujian API Apidog CLI pada setiap pendorongan.

Apakah CircleCI gratis?

CircleCI memiliki paket gratis yang mencakup alokasi bulanan kredit build, yang cukup untuk proyek kecil dan repo pribadi. Tim yang lebih besar yang membutuhkan lebih banyak konkurensi, waktu build yang lebih lama, atau mesin yang lebih besar beralih ke paket Performance dan Scale berbayar. Periksa halaman harga CircleCI saat ini untuk batasan yang tepat.

Apakah CircleCI sumber terbuka (open source)?

Tidak, CircleCI adalah produk komersial yang di-host, bukan sumber terbuka. Anda mengkonfigurasinya melalui file YAML dan menjalankannya di infrastruktur CircleCI atau runner yang di-host sendiri. Jika Anda memerlukan server CI yang sepenuhnya sumber terbuka, Jenkins adalah alternatif umum, yang dibahas dalam perbandingan CircleCI vs Jenkins.

Bagaimana cara kerja CircleCI?

Ketika Anda mendorong (push) sebuah commit, CircleCI mendeteksi perubahan, membaca .circleci/config.yml, dan memutar eksekutor yang Anda definisikan, seperti kontainer Docker cimg/node. Ia menjalankan setiap langkah dalam job Anda secara berurutan, lalu melaporkan hasilnya kembali ke penyedia Git Anda. Alur kerja (workflows) memungkinkan Anda untuk merangkai dan memparalelkan job. Untuk gambaran yang lebih besar tentang bagaimana ini cocok dalam pipeline pengiriman, lihat panduan Apa itu CI/CD.