Cara Menjalankan Tes API Tanpa Boilerplate YAML Tavern

Tavern adalah sebuah karya rekayasa yang cerdas. Ini terhubung ke pytest, memungkinkan Anda mendeskripsikan pengujian API sebagai file YAML, dan menjalankan file tersebut seolah-olah itu adalah pengujian pytest biasa. Anda mendapatkan seluruh ekosistem pytest secara gratis: fixture, plugin, eksekusi paralel dengan pytest-xdist, cakupan, perintah yang sama yang sudah digunakan oleh tim Python Anda. Bagi tim backend yang sehari-hari menggunakan pytest, menulis satu lagi file test_*.tavern.yaml di samping unit test terasa alami.

Gesekan muncul setelah file YAML membesar. Satu permintaan yang mengirimkan body, menyimpan token, dan memeriksa beberapa bidang respons berubah menjadi blok bertumpuk berisi kunci request, response, save, dan verify_response_with yang harus Anda indentasi dengan tepat. Alur multi-tahap (masuk, membuat sumber daya, membacanya kembali, menghapusnya) menumpuk blok-blok tersebut menjadi satu file panjang di mana satu spasi yang salah dapat merusak parsing, dan kontrak API yang diverifikasi oleh pengujian berada di tempat lain: file Swagger, halaman wiki, koleksi Postman yang sudah usang berbulan-bulan yang lalu.

Apa yang Tavern Lakukan dengan Baik

Mulai dengan penghargaan, karena Tavern pantas mendapatkannya.

Ia berjalan di atas pytest alih-alih menggantikannya. Tavern adalah plugin pytest. Anda menginstalnya dengan pip install tavern, menempatkan file YAML di direktori pengujian Anda, dan pytest menemukannya serta menjalankannya seperti pengujian lainnya. Itu berarti Anda mempertahankan setiap kebiasaan pytest yang sudah dimiliki tim Anda: -k untuk memfilter, -x untuk berhenti pada kegagalan pertama, pytest-html untuk laporan, pytest-xdist untuk eksekusi paralel, fixture untuk pengaturan bersama. Tidak ada yang berubah pada runner Anda. Bagi perusahaan Python, ini adalah keuntungan nyata, dan sedikit alat pengujian API yang terintegrasi sebersih ini dengan suite yang ada.

YAML bersifat deklaratif dan mudah dibaca. Pengujian Tavern yang sederhana sangat mudah untuk dipindai:

test_name: Get a single order

stages:
  - name: Fetch order 1042
    request:
      url: https://api.shop.test/orders/1042
      method: GET
    response:
      status_code: 200
      json:
        id: 1042
        status: shipped

Tidak ada kode perekat, tidak ada pustaka assert untuk diimpor, tidak ada harness pengujian untuk ditulis. Permintaan dan respons yang diharapkan berada di samping satu sama lain. Untuk memeriksa kode status dan beberapa bidang, itu lebih mudah dibaca daripada Python requests ditambah assert yang setara.

Penyimpanan dan pengaitan variabel. Tavern dapat mengambil nilai dari satu respons dan menyuntikkannya ke tahap berikutnya dengan substitusi save dan {variable}, sehingga alur login-kemudian-panggil berfungsi tanpa kode kustom:

stages:
  - name: Log in
    request:
      url: https://api.shop.test/auth/login
      method: POST
      json:
        username: tester
        password: hunter2
    response:
      status_code: 200
      save:
        json:
          token: access_token

  - name: Read the profile with the saved token
    request:
      url: https://api.shop.test/me
      method: GET
      headers:
        Authorization: "Bearer {token}"
    response:
      status_code: 200

Ini melakukan lebih dari HTTP. Tavern juga menguji MQTT, yang penting jika Anda bekerja dengan IoT atau sistem berbasis pesan. Dan karena di bawahnya adalah pytest, Anda dapat mencampur pengujian API YAML dan pengujian Python biasa dalam eksekusi yang sama dan laporan yang sama.

Tidak ada yang pemasaran di sini. Tavern adalah alat yang solid. Pertanyaannya adalah apakah asumsinya sesuai dengan Anda.

Di mana Boilerplate YAML Menumpuk

Tiga biaya datang bersama dengan model Tavern, dan apakah itu penting tergantung pada seberapa besar suite Anda.

YAML peka terhadap spasi kosong, dan skemanya dalam. Contoh sederhana di atas bersih. Pengujian yang realistis tidak demikian. Setelah Anda menambahkan header, parameter kueri, body permintaan, pernyataan body respons, pemeriksaan tipe, variabel yang disimpan, dan fungsi eksternal verify_response_with, Anda menumpuk empat dan lima tingkat kedalaman dalam format di mana satu spasi yang salah adalah kesalahan parsing, bukan pesan yang jelas. Editor tidak melengkapi kunci Tavern secara otomatis seperti IDE melengkapi metode Python, jadi Anda harus memeriksa dokumentasi untuk mengetahui apakah itu status_code atau status, json atau body, pada setiap bidang baru.

Pengujian dan kontrak API adalah dua artefak terpisah. YAML Tavern Anda mengodekan URL, metode, bidang yang diharapkan, dan tipenya. Definisi API yang sebenarnya ada di file OpenAPI, dekorator rute kerangka kerja, atau tidak ada yang tahu pasti di mana. Ketika API mengubah nama bidang, tidak ada yang memberi tahu YAML. Pengujian terus menegaskan bentuk lama sampai gagal di CI atau, lebih buruk lagi, terus lulus terhadap ekspektasi yang sudah usang. Seseorang harus menjaga keduanya tetap sinkron secara manual, dan orang itu biasanya adalah siapa pun yang mengalami kegagalan pada pukul 2 pagi.

Ini mengasumsikan toolchain Python dan orang-orang Python. Tavern sangat bagus jika penguji Anda menulis Python. Jika grup QA Anda, insinyur frontend Anda, atau orang produk Anda ingin menambah atau membaca pengujian, mereka akan bertemu pip, virtualenv, konvensi pytest, dan aturan skema YAML sekaligus hanya untuk mengirim permintaan HTTP dan memeriksa respons. Jalur masuknya sulit bagi siapa pun di luar dunia Python.

Jalur Lewati-YAML

Alternatifnya adalah berhenti membuat pengujian sebagai file teks dan mulai membangunnya berdasarkan definisi API yang sudah Anda miliki.

Di Apidog, spesifikasi API, permintaan, dan pengujian adalah objek yang sama. Anda mengimpor atau mendesain API Anda sekali (OpenAPI, Swagger, atau impor koleksi Postman dalam sekali klik), dan setiap endpoint membawa skema aslinya. Anda membangun skenario pengujian dengan mengaitkan endpoint-endpoint tersebut secara visual: seret panggilan login, seret panggilan yang membutuhkan token, dan teruskan nilai tanpa menulis blok save: atau string {variable} secara manual. Pernyataan adalah kotak centang dan ekspresi di panel, bukan kunci YAML berindentasi yang harus Anda ingat.

Karena pengujian dibangun berdasarkan spesifikasi, spesifikasi adalah satu-satunya sumber kebenaran. Mengubah bidang respons dalam desain dan skenario pengujian yang mereferensikannya akan menampilkan perubahan alih-alih melayang secara diam-diam. Itulah bagian yang Tavern secara struktural tidak dapat lakukan: YAML-nya tidak memiliki tautan kembali ke kontrak.

Dan ketika saatnya untuk mengotomatisasi, Anda tidak kehilangan properti headless yang ramah CI yang membuat Tavern menarik. Apidog CLI menjalankan skenario yang sama dari baris perintah, di CI, tanpa GUI, persis seperti pytest menjalankan file Tavern Anda hari ini.

Menginstal dan Menjalankan Apidog CLI

Runner adalah paket npm gratis bernama apidog-cli. Instal secara global:

npm install -g apidog-cli

Kemudian jalankan skenario pengujian dengan perintah apidog run:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

Berikut adalah fungsi setiap bagian:

• --access-token mengautentikasi eksekusi terhadap akun Apidog Anda. Hasilkan token dari tab CI/CD skenario dan simpan sebagai rahasia, jangan pernah dalam file.
• -t adalah ID skenario pengujian.
• -e adalah ID lingkungan (dev, staging, prod), sehingga skenario yang sama mencapai URL dasar dan variabel yang tepat.
• -r memilih reporter. cli mencetak output yang mudah dibaca ke terminal.

Anda tidak perlu menghafal ID tersebut. Buka skenario pengujian di Apidog, beralih ke tab CI/CD-nya, pilih opsi baris perintah, dan klik Hasilkan token. Apidog membangun perintah apidog run lengkap untuk Anda dengan ID skenario dan ID lingkungan yang sudah terisi. Salin, lalu pindahkan token ke rahasia CI.

Jika Anda tidak ingin menginstal secara global, terutama pada runner CI sementara, jalankan dengan npx:

npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

Reporter mencakup cli, html, json, dan junit. Untuk CI, kombinasi yang berguna adalah -r html,junit: junit mengeluarkan XML standar yang hampir setiap dasbor CI parse menjadi pohon lulus/gagal, dan html menghasilkan laporan yang dapat dijelajahi yang dapat Anda arsipkan sebagai artefak build. Tambahkan --out-dir untuk mengontrol di mana mereka mendarat:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r html,junit --out-dir ./apidog-reports

Untuk daftar flag lengkap pada versi yang Anda instal, jalankan apidog run --help.

Perbandingan

Tavern unggul jika tim Anda sepenuhnya menggunakan Python dan Anda ingin pengujian berada di repo yang sama dan eksekusi pytest yang sama dengan unit test Anda. Apidog unggul jika Anda ingin menghilangkan pemeliharaan YAML, menjaga kontrak dan pengujian sebagai satu kesatuan, dan membiarkan orang yang tidak menulis Python berkontribusi dalam pengujian.

Menghubungkannya ke CI

Eksekusi headless adalah inti dari perpindahan dari file pengujian lokal ke pipeline. Berikut adalah bentuk GitHub Actions:

name: API tests
on: [push, pull_request]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Run API test scenario
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -r html,junit \
            --out-dir apidog-reports
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: apidog-report
          path: apidog-reports

Token berasal dari rahasia repositori dan mencapai langkah sebagai variabel lingkungan. if: always() pada langkah unggah berarti Anda masih mendapatkan laporan saat pengujian gagal, yang merupakan saat Anda ingin membacanya. Jika ada pernyataan yang gagal, langkah apidog run keluar dengan kode non-nol, pekerjaan menjadi merah, dan permintaan tarik menunjukkan pemeriksaan yang gagal.

Perilaku kode keluar ini adalah gerbang kualitas, dan ia berfungsi sama seperti Tavern: CI membaca kode keluar setiap langkah, keluar non-nol membuat pekerjaan gagal, dan pekerjaan yang gagal memblokir penggabungan atau penyebaran. Anda tidak mengonfigurasi apa pun secara ekstra. Untuk pengaturan pipeline yang lebih dalam, Apidog CLI dalam pipeline CI/CD Anda dan panduan GitHub Actions juga mencakup varian GitLab CI dan Jenkins.

Catatan tentang Pytest dan Dunia Pengujian Python yang Lebih Luas

Beranjak dari YAML Tavern tidak berarti meninggalkan pytest. Banyak tim mempertahankan unit test dan integration test Python murni mereka di pytest dan menggunakan Apidog untuk lapisan kontrak API, bagian di mana pengujian harus melacak spesifikasi dan berjalan juga untuk kontributor non-Python. Keduanya tidak saling eksklusif. Nilai Tavern selalu terletak pada membiarkan orang pytest menulis pengujian API dalam format yang lebih ringan daripada kode requests mentah; nilai Apidog adalah membuat pengujian API tersebut melacak kontrak dan tetap mudah dibaca seiring pertumbuhan suite melewati beberapa file.

Jika Anda juga mempertimbangkan runner lain, logika yang sama berlaku untuk kisah baris perintah Postman di Postman CLI vs Newman dan untuk menjalankan koleksi tanpa alat tambahan di Pengujian API tanpa Postman.

FAQ

Apakah Apidog CLI gratis? Ya. Paket npm apidog-cli gratis untuk diinstal dan dijalankan dengan npm install -g apidog-cli. Ini menjalankan skenario pengujian dari proyek Apidog Anda, jadi apa yang dapat Anda jalankan tergantung pada paket Apidog Anda, tetapi runner baris perintah itu sendiri bukanlah produk berbayar terpisah.

Bisakah saya tetap menggunakan pytest bersama Apidog? Ya. Pertahankan unit test dan integration test Python Anda di pytest dan gunakan Apidog untuk lapisan pengujian kontrak API. Banyak tim menjalankan keduanya. Perbedaannya adalah pengujian Apidog melacak spesifikasi alih-alih mengodekannya secara langsung dalam file terpisah.

Bagaimana Apidog memblokir penggabungan yang buruk di CI? Melalui kode keluar. Ketika ada pernyataan yang gagal, apidog run keluar dengan kode non-nol. CI membaca kode keluar itu, menandai langkah sebagai gagal, dan memblokir penggabungan atau penyebaran. Anda tidak perlu mengonfigurasi apa pun secara ekstra agar ini berfungsi.

Reporter mana yang harus saya gunakan untuk CI? Gunakan junit untuk hasil yang dapat dibaca mesin yang akan diparse oleh dasbor CI Anda menjadi pohon lulus/gagal, dan tambahkan html jika Anda menginginkan laporan yang dapat dijelajahi yang disimpan sebagai artefak. Pilihan umum adalah -r html,junit, dengan cli tetap diaktifkan untuk output log build yang mudah dibaca.

Apakah Apidog hanya menguji HTTP, seperti mode HTTP Tavern? Tidak. Apidog mencakup HTTP ditambah SOAP, WebSocket, Server-Sent Events, dan gRPC. Tavern menambahkan MQTT ke HTTP, yang merupakan satu-satunya tempat cakupan protokolnya melampaui Apidog, jadi ingatlah itu jika MQTT adalah pusat tumpukan Anda.

Kesimpulan Jujur

Tavern adalah cara yang bersih untuk menulis pengujian API jika Anda sudah terbiasa dengan pytest dan YAML, dan integrasi pytest adalah fitur terbaiknya. Biayanya adalah YAML itu sendiri: ia menjadi dalam dan rapuh saat suite berkembang, dan tidak memiliki tautan kembali ke kontrak API yang diverifikasinya. Jika Anda menginginkan perilaku headless, gagal-keras-di-CI yang sama tanpa mengindentasi YAML secara manual dan tanpa mempertahankan salinan kedua dari spesifikasi Anda, membangun pengujian berdasarkan kontrak dan menjalankannya dengan apidog run adalah jalur yang lebih ringan.

Unduh Apidog dan impor API yang ada untuk merasakan alur kerja "spesifikasi adalah pengujian" sebelum Anda berkomitmen. Ini gratis untuk memulai.