Cara Menjalankan Tes API Apidog CLI di Harness CI/CD

Anda menjalankan tes Apidog CLI di Harness dengan menambahkan stage CI dengan satu langkah Run yang menginstal apidog-cli, menjalankan apidog run, dan memublikasikan hasil JUnit. Simpan token akses Apidog Anda sebagai rahasia Harness, referensikan dengan ekspresi <+secrets.getValue("...")>, dan arahkan blok laporan JUnit ke output XML CLI. Panduan ini memberikan YAML pipeline siap pakai untuk Harness Cloud dan delegate yang di-hosting sendiri.

Apa itu Harness CI/CD?

Harness CI adalah modul integrasi berkelanjutan dari platform Harness. Ini membangun, menguji, dan memvalidasi kode Anda pada infrastruktur build yang dikelola atau di-hosting sendiri, lalu menyerahkan artefak ke Harness CD untuk deployment.

Anda mendefinisikan semuanya sebagai YAML. Sebuah pipeline berisi satu atau lebih stage. Setiap stage memiliki tipe, dan stage CI berjalan pada infrastruktur build. Di dalam stage, blok eksekusi menampung daftar langkah yang berurutan yang menjalankan perintah Anda.

Model ini cocok dengan pengujian API. Anda menambahkan stage CI, memasukkan langkah yang menjalankan perintah pengujian Anda, dan membiarkan Harness mengendalikan build berdasarkan hasilnya. Jika tes gagal, langkah tersebut gagal, dan pipeline berhenti.

Harness membaca XML JUnit untuk pelaporan pengujian. Karena Apidog CLI dapat mengeluarkan JUnit, Anda mendapatkan tab Tes bawaan dengan jumlah lulus dan gagal pada setiap build. Tidak diperlukan kode penghubung.

Bagaimana Harness CI Bekerja

Hierarki YAML sangat ketat, jadi ada baiknya untuk melihat susunannya sebelum Anda menulis apa pun. Pipeline CI terlihat seperti ini dari atas ke bawah:

pipeline menampung metadata dan daftar stages.
Setiap stage memiliki type: CI dan spec.
spec stage mendeklarasikan infrastruktur build dan blok execution.
execution menampung daftar steps.
Setiap step memiliki type, name, identifier, dan spec-nya sendiri.

Untuk menjalankan perintah shell, tipe langkah adalah Run. spec langkah Run membawa bidang shell (Bash, Sh, PowerShell, Pwsh, atau Python) dan bidang command yang menampung skrip Anda. Anda menulis perintah multi-baris dengan skalar blok YAML |-.

Satu langkah Run itu saja sudah cukup untuk menginstal dan menjalankan Apidog CLI. Semua yang lain dalam panduan ini adalah konfigurasi di sekitar langkah tersebut.

Apidog CLI dalam Satu Menit

Apidog CLI adalah runner baris perintah untuk skenario pengujian yang Anda buat secara visual di Apidog. Anda mendesain tes di aplikasi, lalu menjalankannya tanpa kepala di pipeline mana pun, mirip dengan cara Newman menjalankan koleksi Postman. Jika Anda ingin perbandingan, lihat Apidog CLI vs Newman.

Anda menginstalnya dari npm dan menjalankan satu perintah:

npm install -g apidog-cli
apidog run --access-token <ACCESS_TOKEN> -t <TEST_SCENARIO_ID> -e <ENVIRONMENT_ID> -r cli,junit --out-dir ./apidog-reports

Beberapa flag penting untuk CI. Flag --access-token mengautentikasi eksekusi cloud dan tidak memiliki bentuk singkat. Flag -e mengatur lingkungan dan bersifat wajib. Flag -t memilih skenario pengujian berdasarkan ID. Flag -r memilih pelapor, dan junit adalah salah satu nilai yang didukung (cli, html, json, junit). Flag --out-dir mengontrol tempat laporan disimpan, dengan default ke ./apidog-reports.

Pilihan -r cli,junit itu adalah jembatan ke Harness. CLI menulis XML JUnit ke direktori output, dan Harness membacanya langsung. Untuk lebih lanjut tentang apa yang dihasilkan CLI, lihat panduan laporan pengujian Apidog CLI.

Menyimpan token akses Apidog Anda sebagai rahasia Harness

Jangan pernah melakukan hardcode token di YAML. Tambahkan ke manajer rahasia Harness terlebih dahulu, lalu referensikan.

Di UI Harness, buka pengaturan proyek (atau org/akun) Anda, buka Secrets, dan buat rahasia Teks baru. Beri identifikasi apidog_token. Pengidentifikasi adalah apa yang Anda referensikan dalam YAML, dan berbeda dari nama tampilan.

Anda mereferensikan rahasia dengan ekspresi ini:

<+secrets.getValue("apidog_token")>

Gunakan pengidentifikasi di dalam tanda kutip, bukan nama tampilan. Untuk rahasia berskala organisasi, awali dengan org. seperti <+secrets.getValue("org.apidog_token")>. Untuk rahasia berskala akun, gunakan account. sebagai gantinya.

Bungkus ekspresi dalam tanda kutip tunggal di dalam perintah shell. Token bisa berisi karakter $, dan tanda kutip tunggal menghentikan shell agar tidak mengembangkannya. Anda dapat membaca lebih lanjut tentang pengaturan token di catatan autentikasi Apidog CLI.

Pipeline Harness Cloud (titik awal yang direkomendasikan)

Harness Cloud memberi Anda mesin build yang dikelola Harness dengan Node.js dan npm yang sudah terinstal. Tidak ada infrastruktur yang perlu dipelihara, dan Linux berjalan secara langsung. Ini adalah cara tercepat untuk mendapatkan pipeline yang berfungsi.

Di Harness Cloud, spec stage menggunakan blok platform dan blok runtime bertipe: Cloud. Anda tidak menentukan image pada langkah Run di sini, karena mesin terkelola sudah memiliki alat-alat tersebut.

pipeline:
  name: Apidog API Tests
  identifier: apidog_api_tests
  projectIdentifier: YOUR_PROJECT
  orgIdentifier: YOUR_ORG
  stages:
    - stage:
        name: API Tests
        identifier: api_tests
        type: CI
        spec:
          cloneCodebase: false
          platform:
            os: Linux
            arch: Amd64
          runtime:
            type: Cloud
            spec: {}
          execution:
            steps:
              - step:
                  type: Run
                  name: Run Apidog CLI Tests
                  identifier: run_apidog_cli_tests
                  spec:
                    shell: Sh
                    command: |-
                      npm install -g apidog-cli
                      apidog run \
                        --access-token '<+secrets.getValue("apidog_token")>' \
                        -t 605067 \
                        -e 1629989 \
                        -n 1 \
                        -r cli,junit \
                        --out-dir ./apidog-reports
                    reports:
                      type: JUnit
                      spec:
                        paths:
                          - apidog-reports/*.xml

Ganti 605067 dengan ID skenario pengujian Anda dan 1629989 dengan ID lingkungan Anda. Flag -n 1 menjalankan satu iterasi. Atur cloneCodebase: false karena pengujian berada di cloud Apidog, jadi pipeline tidak memerlukan repo Anda.

Mempublikasikan hasil pengujian

Blok reports pada langkah Run adalah yang menampilkan hasil di Harness. Ini mengambil tipe JUnit dan spec dengan daftar paths yang menunjuk ke file XML Anda.

reports:
  type: JUnit
  spec:
    paths:
      - apidog-reports/*.xml

Harness hanya mengurai JUnit XML untuk pelaporan native. Setelah build, Anda melihat tab Tes dengan setiap skenario, statusnya, dan waktunya. Glob apidog-reports/*.xml cocok dengan file yang ditulis CLI dengan -r cli,junit ke direktori output default.

Harness juga menawarkan Test Intelligence, yang menggunakan tipe langkah Tes terpisah untuk menjalankan hanya tes yang terpengaruh oleh perubahan kode. Optimasi itu menargetkan pengujian unit tingkat bahasa, bukan skenario API headless. Untuk memasukkan output Apidog CLI, langkah Run biasa dengan blok reports JUnit adalah jalur yang benar.

Jika Anda mengganti pelapor, pertahankan setidaknya junit dalam daftar -r. Tanpa itu, CLI tidak menulis XML, dan tab Tes tetap kosong bahkan ketika langkah itu sendiri berhasil.

Alternatif delegate yang di-hosting sendiri

Gunakan build yang didukung delegate ketika Anda membutuhkan akses jaringan pribadi, runtime kustom atau lama, atau Anda ingin menghindari kredit build Harness Cloud. Delegate Kubernetes menjalankan setiap stage sebagai pod.

Strukturnya berubah dalam dua cara. spec stage menggunakan blok infrastructure alih-alih platform dan runtime. Dan pada infrastruktur Kubernetes, setiap langkah Run harus mendeklarasikan connectorRef dan image, karena langkah tersebut berjalan di dalam kontainer yang Anda tentukan.

        spec:
          cloneCodebase: false
          infrastructure:
            type: KubernetesDirect
            spec:
              connectorRef: YOUR_K8S_CONNECTOR
              namespace: harness-ci
          execution:
            steps:
              - step:
                  type: Run
                  name: Run Apidog CLI Tests
                  identifier: run_apidog_cli_tests
                  spec:
                    connectorRef: YOUR_DOCKER_CONNECTOR
                    image: node:20
                    shell: Sh
                    command: |-
                      npm install -g apidog-cli
                      apidog run \
                        --access-token '<+secrets.getValue("apidog_token")>' \
                        -t 605067 -e 1629989 -r cli,junit --out-dir ./apidog-reports
                    reports:
                      type: JUnit
                      spec:
                        paths:
                          - apidog-reports/*.xml

Baris image: node:20 memberi Anda Node.js dan npm di dalam pod. Nilai connectorRef menunjuk ke konektor Kubernetes dan Docker Anda yang terdaftar. Jangan mencampur dua gaya infrastruktur dalam satu stage. Sebuah stage adalah Harness Cloud (platform ditambah runtime) atau didukung delegate (infrastructure), tidak pernah keduanya.

Memilih Harness Cloud vs delegate

Pilih berdasarkan di mana API Anda berada dan siapa yang memiliki mesin build.

Faktor	Harness Cloud	Delegate yang di-hosting sendiri
Pengaturan	Tanpa infrastruktur, npm sudah terinstal	Anda mengelola kluster atau VM
Jangkauan jaringan	Endpoint publik	Endpoint pribadi dan internal
Langkah Run memerlukan image	Tidak	Ya, pada infrastruktur Kubernetes
Model biaya	Menggunakan kredit build	Komputasi Anda sendiri
Terbaik untuk	API Cloud, mulai cepat	API internal, runtime kustom

Mulai dengan Harness Cloud jika lingkungan Apidog Anda mengenai endpoint publik. Pindah ke delegate saat lingkungan pengujian Anda berada di belakang VPN atau membutuhkan runtime yang Anda kendalikan. Langkah Run dan perintah Apidog tetap hampir identik di antara keduanya.

Eksekusi berbasis data

Anda dapat memasukkan file CSV atau JSON ke dalam eksekusi untuk pengujian berparameter. Flag -d (nama panjang --iteration-data) mengambil jalur file data, dan -n mengatur jumlah iterasi.

apidog run --access-token <ACCESS_TOKEN> -t <TEST_SCENARIO_ID> -e <ENVIRONMENT_ID> -d ./data.csv -n 5 -r cli,junit --out-dir ./apidog-reports

Ini menjalankan skenario sekali per baris data. Dalam langkah Run Harness, Anda akan git clone atau menyiapkan file data terlebih dahulu, lalu mengarahkan -d ke jalurnya. Untuk pola lengkap, lihat pengujian berbasis data Apidog CLI dan panduan pengujian API otomatis yang lebih luas.

Mengapa mendesain tes di Apidog terlebih dahulu

CLI hanya menjalankan skenario yang sudah ada di proyek Apidog Anda. Itulah intinya. Apidog adalah platform API all-in-one untuk desain, debugging, pengujian, mocking, dan dokumentasi, jadi Anda membangun suite pengujian Anda sekali dan menggunakannya kembali di mana saja.

Anda mendesain tes dengan pembangun visual, tanpa memerlukan skrip. Anda merangkai permintaan, mengekstrak nilai dari satu respons ke respons berikutnya, dan menambahkan pernyataan melalui UI. CLI kemudian menjalankan suite yang persis sama tanpa kepala di Harness, jadi apa yang Anda debug secara lokal adalah apa yang berjalan di pipeline.

Karena Apidog adalah OpenAPI-native dengan dukungan cabang dan ruang kerja tim, insinyur QA dan pengembang backend Anda berbagi satu sumber kebenaran. Skenario yang disetujui di cabang menjadi skenario yang sama yang dijalankan perintah apidog run Anda. Untuk pola pipeline yang lebih luas, panduan dasar apa itu CI/CD dan panduan alur kerja GitHub Actions mencakup CLI yang sama di sistem lain. Panduan Jenkins dalam mengintegrasikan tes Apidog dengan Jenkins menggunakan bentuk perintah yang identik.

Unduh Apidog secara gratis untuk membangun skenario pengujian pertama Anda, lalu hubungkan ke Harness dengan YAML di atas.

tombol

Pertanyaan yang Sering Diajukan

Apa itu Harness CI/CD?

Harness CI/CD adalah platform pipeline untuk membangun, menguji, dan menyebarkan perangkat lunak. Anda mendefinisikan pipeline sebagai YAML yang terdiri dari stage dan langkah-langkah. Stage CI berjalan pada infrastruktur build, baik mesin Cloud yang dikelola Harness atau delegate yang di-hosting sendiri, dan stage CD menangani deployment.

Bagaimana Harness CI bekerja?

Sebuah pipeline menampung daftar stage. Setiap stage CI memiliki spec yang mendeklarasikan infrastruktur build dan blok eksekusi. Blok eksekusi menjalankan daftar langkah yang berurutan. Langkah Run menjalankan perintah shell, di situlah Anda menginstal dan menjalankan Apidog CLI.

Bagaimana Anda menyimpan dan menggunakan rahasia di Harness?

Buat rahasia Teks di manajer rahasia Harness dan catat pengidentifikasinya. Referensikan dalam YAML dengan <+secrets.getValue("identifier")>, menggunakan pengidentifikasi daripada nama tampilan. Awali dengan org. atau account. untuk cakupan tersebut, dan bungkus ekspresi dalam tanda kutip tunggal di dalam perintah shell.

Bagaimana Anda memublikasikan hasil pengujian di Harness?

Tambahkan blok reports ke langkah Run Anda dengan type: JUnit dan daftar paths yang menunjuk ke file XML Anda. Harness mengurai JUnit XML dan menunjukkan hasil pada tab Tes build. Apidog CLI mengeluarkan XML ini ketika Anda meneruskan -r junit atau -r cli,junit.

Apakah Harness CI gratis?

Harness menawarkan tingkatan gratis untuk CI, dan build Harness Cloud mengonsumsi kredit build yang termasuk dalam paket Anda. Harga dan batas kredit berubah seiring waktu, jadi periksa halaman harga Harness saat ini untuk angka pasti sebelum Anda berkomitmen pada tingkatan.

Bisakah saya menjalankan tes Apidog CLI tanpa mengkloning repo saya?

Ya. Atur cloneCodebase: false pada stage ketika tes Anda berada di cloud Apidog. CLI mengautentikasi dengan token akses Anda dan menarik skenario serta lingkungan berdasarkan ID, sehingga pipeline tidak pernah membutuhkan kode sumber Anda untuk eksekusi tes.