Jika Anda memiliki skema OpenAPI atau GraphQL, Schemathesis dapat mengubahnya menjadi ribuan kasus uji tanpa Anda menulis satu pun asersi. Ini membaca spesifikasi, menghasilkan input yang liar dan valid, menjalankannya pada API Anda, dan melaporkan di mana respons melanggar kontrak. Panduan ini menjelaskan apa itu Schemathesis, cara menginstal dan menjalankannya, apa sebenarnya arti pengujian berbasis properti, dan bagaimana hal itu sesuai dengan alur kerja pengujian fungsional dan kontrak di Apidog.
Apa itu Schemathesis?
Schemathesis adalah alat Python sumber terbuka yang secara otomatis menghasilkan pengujian API dari sebuah skema. Anda mengarahkannya ke definisi OpenAPI atau GraphQL, dan ia membangun kasus uji dari tipe, format, dan batasan yang sudah Anda deklarasikan. Ini dibangun di atas Hypothesis, pustaka pengujian berbasis properti untuk Python, dan didistribusikan di bawah lisensi MIT.
Ide intinya sederhana. Spesifikasi Anda sudah menjelaskan seperti apa permintaan dan respons yang valid. Schemathesis memperlakukan deskripsi itu sebagai sumber kebenaran dan memeriksa apakah API Anda yang berjalan benar-benar menghormatinya. Ketika API mengembalikan 500, mengirim respons yang melanggar skema yang dideklarasikan, atau menerima input yang seharusnya ditolak, Schemathesis akan menandainya.
Anda menjalankannya dari baris perintah dengan schemathesis run (atau alias yang lebih pendek st run). Ada juga integrasi Python jika Anda ingin menjalankannya dari pytest daripada CLI. Kebanyakan tim memulai dengan CLI karena hampir tidak memerlukan penyiapan.
Apa arti pengujian berbasis properti
Sebagian besar pengujian API berbasis contoh. Anda menulis permintaan, Anda menegaskan respons tertentu, dan pengujian lulus atau gagal pada satu kasus itu. Itu berguna, tetapi Anda hanya menangkap bug yang Anda pikirkan untuk dituliskan pengujiannya.
Pengujian berbasis properti membalik pendekatannya. Alih-alih satu contoh tetap, Anda menjelaskan properti yang seharusnya selalu berlaku, lalu membiarkan alat menghasilkan ratusan input untuk mencoba memecahnya. Untuk Schemathesis, propertinya kira-kira: "tidak ada permintaan yang valid yang seharusnya merusak server atau menghasilkan respons yang melanggar skema."
Schemathesis menghasilkan input dari batasan dalam spesifikasi Anda. Jika sebuah bidang adalah bilangan bulat dengan minimum 1, ia akan mencoba 1, angka besar, nilai batas, dan jenis input yang membuat validasi sederhana bermasalah. Ketika sebuah pengujian gagal, Hypothesis mengecilkan input ke kasus terkecil yang masih mereproduksi bug, sehingga Anda mendapatkan reproduksi minimal dan mudah dibaca alih-alih muatan acak 4KB.
Ini berbeda dari pengujian monyet, yang melemparkan input acak ke antarmuka untuk melihat apa yang rusak. Pengujian berbasis properti terstruktur. Ia menggunakan skema untuk menghasilkan input yang masuk akal dan terarah, dan ia tahu seperti apa hasil yang benar karena spesifikasi memberitahukannya.
Menginstal dan menjalankan Schemathesis
Schemathesis adalah paket Python, jadi Anda memerlukan Python 3 dan pip. Instal dengan cara biasa:
pip install schemathesis
Anda juga dapat menjalankannya tanpa instalasi permanen menggunakan uvx schemathesis jika Anda telah mengatur uv. Setelah diinstal, perintah dasar mengarah ke skema dan URL dasar:
st run http://127.0.0.1:8000/openapi.json
Jika skema Anda berada di disk daripada di belakang URL, berikan jalur file dan beri tahu Schemathesis di mana API langsung berada:
st run ./openapi.yaml --url http://127.0.0.1:8000
Untuk API terautentikasi, tambahkan header:
st run http://127.0.0.1:8000/openapi.json \
--header 'Authorization: Bearer your-token'
Schemathesis menemukan setiap operasi dalam spesifikasi, menghasilkan kasus untuk masing-masing, dan mencetak ringkasan pemeriksaan mana yang lulus dan mana yang gagal. Kegagalan dilengkapi dengan permintaan yang tepat yang dikirimnya, sehingga Anda dapat memutarnya ulang dengan curl atau di klien API mana pun. Nama flag dan default berubah di antara versi utama, jadi periksa st run --help terhadap versi terinstal Anda daripada mempercayai kutipan blog, termasuk yang ini.
Apa yang ditemukan Schemathesis
Pemeriksaan default menargetkan celah antara apa yang dijanjikan spesifikasi Anda dan apa yang dilakukan server Anda. Berikut adalah apa yang cenderung muncul.
| Masalah | Seperti apa bentuknya |
|---|---|
| Galat server | Permintaan memicu 500 alih-alih 4xx yang ditangani atau respons yang valid |
| Pelanggaran skema | Isi respons tidak cocok dengan skema yang Anda deklarasikan untuk kode status tersebut |
| Ketidakcocokan kode status | API mengembalikan kode status yang tidak pernah didokumentasikan dalam spesifikasi |
| Pergeseran tipe konten | Tipe konten respons tidak cocok dengan apa yang diiklankan oleh spesifikasi |
| Bug status | Operasi berfungsi sendiri tetapi gagal dalam alur kerja multi-langkah yang realistis |
Yang terakhir layak untuk dilihat lebih dekat. Schemathesis dapat menjalankan pengujian status, di mana ia merangkai operasi bersama berdasarkan tautan dalam spesifikasi Anda, misalnya membuat sumber daya, lalu mengambilnya, lalu menghapusnya. Bug yang hanya muncul secara berurutan, seperti sumber daya yang melaporkan status yang salah setelah pembaruan, sulit ditemukan dengan pengujian satu permintaan. Fase status tersebut mendorong urutan tersebut sebagai mesin status.
Anda dapat memperluas perilaku default dengan hook. Hook adalah fungsi Python yang memungkinkan Anda menyesuaikan pembuatan data, menambahkan pemeriksaan Anda sendiri, atau memfilter operasi mana yang diuji. Begitulah cara tim mengadaptasi Schemathesis ke API dengan alur autentikasi atau batasan yang tidak jelas yang tidak dapat diungkapkan oleh spesifikasi.
Kapan menggunakan Schemathesis
Schemathesis mendapatkan tempatnya ketika Anda memiliki spesifikasi OpenAPI atau GraphQL yang cukup akurat dan Anda menginginkan cakupan luas dan murah untuk kasus-kasus tepi. Ini kuat dalam menemukan kegagalan yang tidak akan pernah Anda tulis pengujian manualnya: input yang tidak ditangani, bentuk kesalahan yang tidak terdokumentasi, dan pergeseran kontrak antara spesifikasi dan implementasi.
Ini cocok ketika:
- Anda memelihara spesifikasi OpenAPI dan ingin ditegakkan terhadap server nyata.
- Anda khawatir tentang 500 yang tidak ditangani dan menginginkan lapisan fuzzing di CI.
- API Anda memiliki alur kerja status di mana urutan penting.
- Tim Anda sudah bekerja dengan Python dan nyaman dengan
pipdanpytest.
Ini kurang cocok ketika spesifikasi Anda tipis atau kedaluwarsa, karena Schemathesis hanya dapat menguji apa yang dijelaskan oleh skema. Sampah masuk, sampah keluar. Ini juga tidak akan menggantikan pengujian fungsional berbasis contoh Anda. Mengetahui bahwa titik akhir tidak pernah macet tidak sama dengan mengetahui bahwa ia mengembalikan nilai yang benar untuk input yang diketahui. Anda menginginkan keduanya.
Schemathesis dan Apidog: di mana masing-masing cocok
Apidog dan Schemathesis memecahkan masalah yang berbeda, dan mereka bekerja dengan baik secara berdampingan. Apidog adalah platform lengkap untuk merancang, men-debug, menguji, mengejek, dan mendokumentasikan API. Schemathesis adalah fuzzer berbasis properti yang terfokus. Jujur tentang batasan di sini itu penting.
Apidog tidak melakukan fuzzing berbasis properti. Fitur terdekatnya adalah pengujian monyet, yang mengirim input acak untuk memunculkan crash. Itu berguna, tetapi tidak sama dengan pengujian berbasis properti yang digerakkan oleh skema. Schemathesis menghasilkan input dari batasan spesifikasi Anda dan memeriksa respons terhadap skema. Jadi, jika fuzzing berbasis properti adalah yang Anda butuhkan, gunakan Schemathesis, bukan Apidog.
Di mana Apidog cocok adalah sisa siklus hidup di sekitar fuzzing pass itu.
| Tahap alur kerja | Schemathesis | Apidog |
|---|---|---|
| Fuzzing berbasis properti dari spesifikasi | Ya, fitur inti | Tidak |
| Desain API visual dan pengeditan spesifikasi | Tidak | Ya |
| Pengujian fungsional berbasis contoh | Terbatas | Ya, pembuat pengujian visual |
| Pengujian kontrak terhadap spesifikasi | Parsial, melalui pemeriksaan skema | Ya, alur kerja khusus |
| Server tiruan dari skema | Tidak | Ya, tiruan cerdas |
| Pelari pengujian CI | Ya, st run |
Ya, apidog run |
| Dokumen yang dibuat secara otomatis | Tidak | Ya |
Pasangan praktis terlihat seperti ini. Anda merancang dan memelihara spesifikasi di Apidog, menghasilkan kasus uji fungsional dan server tiruan darinya, dan menjalankannya di CI dengan apidog run. Kemudian Anda menambahkan pass Schemathesis yang melakukan fuzzing pada spesifikasi yang sama untuk crash kasus-kasus tepi dan pelanggaran kontrak. Kedua lapisan menangkap kelas bug yang berbeda. Apidog mengonfirmasi API melakukan hal yang benar untuk kasus-kasus yang diketahui; Schemathesis berburu kasus-kasus yang tidak diketahui yang merusaknya.
Jika tujuan Anda adalah mengubah spesifikasi menjadi suite fungsional yang dapat dijalankan daripada fuzzing run, Apidog dapat menghasilkan koleksi pengujian API dari spesifikasi OpenAPI Anda secara langsung, dan Anda dapat mengunduh Apidog untuk mencoba alur tersebut.
Pertanyaan yang sering diajukan
Apakah Schemathesis gratis?
Ya. Schemathesis adalah sumber terbuka di bawah lisensi MIT, dan CLI gratis untuk diinstal dan dijalankan melalui pip install schemathesis. Ada juga penawaran komersial yang di-hosting untuk tim yang menginginkan pengalaman terkelola, tetapi alat inti yang Anda jalankan secara lokal dan di CI tidak dikenakan biaya.
Apa perbedaan antara schemathesis run dan st run?
Keduanya adalah perintah yang sama. st adalah alias singkat untuk schemathesis, jadi st run dan schemathesis run melakukan hal yang sama persis. Gunakan mana saja yang Anda suka. Keduanya mengambil jalur atau URL skema ditambah opsi seperti --url dan --header.
Bisakah Schemathesis menggantikan pengujian API fungsional saya?
Tidak, dan memang tidak dimaksudkan untuk itu. Schemathesis memeriksa bahwa API Anda tidak macet dan bahwa respons cocok dengan skema. Ini tidak memverifikasi logika bisnis, seperti apakah perhitungan diskon benar. Anda masih menginginkan pengujian fungsional dan kontrak berbasis contoh untuk itu, yang dapat Anda bangun dan jalankan di Apidog. Perlakukan Schemathesis sebagai lapisan fuzzing tambahan, bukan pengganti.
Apakah Schemathesis berfungsi dengan GraphQL?
Ya. Schemathesis mendukung skema OpenAPI dan GraphQL. Untuk GraphQL, ia menghasilkan kueri dari definisi tipe skema dan memeriksa respons dengan cara yang sama seperti untuk REST API yang didefinisikan dalam OpenAPI.
Kesimpulan
Schemathesis adalah alat yang tajam untuk satu pekerjaan: mengambil spesifikasi OpenAPI atau GraphQL Anda dan menguji coba API langsung Anda terhadapnya dengan pembuatan berbasis properti. Ini menemukan crash dan pelanggaran kontrak yang dilewatkan oleh pengujian berbasis contoh, dan hampir tidak memakan biaya untuk menambahkannya ke CI. Yang tidak dilakukannya adalah merancang, mengejek, mendokumentasikan, atau memverifikasi logika bisnis.
Di situlah Apidog melengkapinya. Rancang spesifikasi, hasilkan pengujian fungsional dan mock, jalankan di CI dengan apidog run, dan dokumentasikan hasilnya, semuanya di satu tempat, lalu lapisi Schemathesis di atasnya untuk fuzzing. Unduh Apidog untuk membangun sisi desain dan fungsional dari alur kerja itu, dan biarkan Schemathesis menangani pencarian kasus-kasus tepi.