Apa itu Specmatic?

Jika Anda menyimpan berkas OpenAPI tetapi layanan yang berjalan perlahan menyimpang darinya, Specmatic dibangun persis untuk mengisi celah tersebut. Ini memperlakukan spesifikasi Anda sebagai kontrak yang dapat dieksekusi, lalu menguji layanan nyata terhadapnya dan menjalankan spesifikasi yang sama sebagai stub cerdas. Panduan ini menjelaskan apa yang dilakukan Specmatic, bagaimana pengujian kontrak berbeda dari pengujian berbasis contoh, dan di mana alat ini cocok, dengan catatan tentang perbandingannya dengan pendekatan platform yang lebih luas seperti pengujian kontrak API Apidog. Untuk format spesifikasi di baliknya, Spesifikasi OpenAPI adalah sumber kebenaran yang dibaca Specmatic.

button

Apa itu Specmatic

Specmatic adalah alat sumber terbuka untuk pengembangan berbasis kontrak. Ide intinya singkat: spesifikasi API Anda adalah kontrak, dan Specmatic membuat kontrak tersebut dapat dieksekusi. Arahkan ke berkas OpenAPI dan ia dapat melakukan dua tugas pelengkap.

Jalankan spesifikasi sebagai pengujian terhadap layanan langsung, memeriksa bahwa layanan mematuhi setiap jalur, kode status, dan skema yang dijanjikan spesifikasi.
Jalankan spesifikasi sebagai server stub, sehingga konsumen dapat mengembangkan terhadap mock yang merespons persis seperti yang dikatakan kontrak.

Kedua tugas membaca berkas yang sama. Tidak ada "definisi pengujian" dan "spesifikasi" terpisah yang perlu disinkronkan, itulah intinya. Specmatic juga melampaui OpenAPI. Versi 2.0 menambahkan GraphQL dan gRPC, dan mendukung AsyncAPI untuk kontrak event bergaya Kafka, ditambah format seperti WSDL dan Avro. Namun, bagi sebagian besar tim, titik masuknya adalah berkas YAML atau JSON OpenAPI biasa.

Anda menjalankannya dari baris perintah atau citra Docker, sehingga mudah diintegrasikan ke CI tanpa banyak kerumitan. Perusahaan di baliknya menawarkan add-on komersial, tetapi mesin kontrak itu sendiri gratis dan sumber terbuka.

Pengujian kontrak vs pengujian berbasis contoh

Ini adalah perbedaan yang membingungkan kebanyakan orang, jadi penting untuk menjadi tepat.

Pengujian berbasis contoh adalah yang Anda lakukan di sebagian besar klien API. Anda menulis permintaan, Anda menegaskan respons yang Anda terima, mungkin Anda memeriksa kode status dan satu atau dua bidang. Setiap pengujian adalah contoh yang ditulis tangan. Jika spesifikasi Anda memiliki 40 titik akhir, Anda menulis dan memelihara banyak contoh, dan celah mudah terlewatkan.

Pengujian kontrak membalik modelnya. Alih-alih menegaskan contoh-contoh spesifik, Anda menegaskan bahwa layanan sesuai dengan kontrak. Specmatic membaca skema dan menghasilkan pengujian darinya. Ini memeriksa bahwa respons sesuai dengan tipe yang dideklarasikan, bahwa bidang yang diperlukan ada, bahwa kode status selaras, dan bahwa layanan menolak permintaan yang salah bentuk seperti yang diisyaratkan spesifikasi. Anda tidak menulis penegasan satu per satu. Spesifikasi adalah penegasannya.

Aspek	Pengujian berbasis contoh	Pengujian kontrak dengan Specmatic
Sumber kebenaran	Kasus pengujian yang ditulis tangan	Spesifikasi OpenAPI itu sendiri
Apa yang Anda pelihara	Setiap permintaan dan penegasan	Spesifikasi, yang Anda simpan bagaimanapun juga
Cakupan	Hanya yang Anda ingat untuk ditulis	Setiap operasi yang dideklarasikan spesifikasi
Deteksi penyimpangan	Manual	Otomatis ketika spesifikasi berubah
Kegagalan tipikal	Contoh spesifik rusak	Layanan tidak lagi sesuai dengan kontrak

Ada sumbu kedua yang patut disebutkan. Pengujian kontrak hadir dalam berbagai jenis, dan Specmatic berada dalam jenis yang spesifik. Pengujian kontrak berbasis konsumen gaya Pact meminta konsumen mempublikasikan harapan mereka ke broker, dan penyedia memverifikasinya. Specmatic justru melakukan pengujian berbasis kontrak: spesifikasi adalah satu-satunya kontrak yang disepakati kedua belah pihak, dan Specmatic memvalidasi penyedia terhadapnya serta membuat stub penyedia untuk konsumen. Ini bukan broker Pact, dan tidak mengelola pakta yang dipublikasikan konsumen. Jika Anda menginginkan gambaran yang lebih luas, lihat ikhtisar alat pengujian kontrak dan mocking API ini.

Cara Specmatic berjalan

Anda dapat menginstal CLI secara langsung atau menarik citra Docker. Docker adalah pilihan umum di CI karena menghindari penyiapan runtime lokal.

Menjalankan pengujian kontrak

Perintah test mengarahkan Specmatic ke spesifikasi dan layanan yang berjalan. Jalankan lokal minimal terlihat seperti ini.

# Native CLI
specmatic test api.yaml --testBaseURL=http://localhost:8080

# Docker
docker run -v "$(pwd):/usr/src/app" specmatic/specmatic \
  test api.yaml --testBaseURL=http://host.docker.internal:8080

Specmatic membaca api.yaml, menghasilkan permintaan untuk operasi yang dijelaskannya, mengirimkannya ke URL dasar, dan memvalidasi setiap respons terhadap skema. Pengujian yang gagal berarti layanan dan kontrak tidak sesuai. Anda memperbaiki salah satunya. Itulah siklusnya.

Menjalankan spesifikasi sebagai stub

Server stub adalah bagian lainnya. Mulai dan Specmatic menyajikan respons yang sesuai dengan kontrak, sehingga front-end atau layanan hilir dapat membangunnya sebelum backend nyata ada.

specmatic stub api.yaml --port=9000

Secara default, ini menghasilkan respons yang valid berdasarkan skema secara cepat. Anda juga dapat menyimpan contoh konkret di direktori _examples di samping spesifikasi, dan stub akan mengembalikan contoh tersebut ketika permintaan cocok. Ini memberi Anda data yang realistis dan terkontrol tanpa harus menyiapkan backend sungguhan. Jika Anda membandingkan opsi stub-and-mock di berbagai alat, rangkuman pengujian kontrak dan server mock menempatkan Specmatic dalam konteks.

Specmatic juga dapat membantu Anda membuat spesifikasi sejak awal. Ia dapat berfungsi sebagai proxy di depan layanan yang ada, menangkap lalu lintas nyata, dan menghasilkan dokumen OpenAPI serta berkas contoh dari apa yang dilihatnya. Itu berguna ketika Anda memiliki layanan yang berfungsi tetapi belum memiliki spesifikasi resmi.

Model spesifikasi sebagai kontrak dan stub

Inilah mengapa menjalankan satu berkas sebagai pengujian dan stub itu penting. Ketika spesifikasi adalah kontrak, sisi pengujian dan sisi stub tidak akan pernah bertentangan, karena keduanya membaca dokumen yang sama.

Tim penyedia menjalankan specmatic test di CI. Jika mereka mengubah API tanpa memperbarui spesifikasi, pengujian kontrak akan gagal.
Tim konsumen menjalankan specmatic stub secara lokal. Mereka mengembangkan terhadap respons yang dijamin sesuai dengan kontrak yang sama.

Jadi spesifikasi menjadi perjanjian yang hidup, bukan dokumen usang yang tidak dipercaya siapa pun. Ini adalah perbedaan antara stub dan mock yang lebih kaya, dan penting untuk memahami ide-ide yang mendasari stubbing vs mocking API sebelum Anda merancang alur kerja di sekitarnya.

Specmatic juga menambahkan pemeriksaan kompatibilitas mundur. Perintah backward-compatibility-check memulai stub dari versi baru spesifikasi, menghasilkan pengujian dari versi sebelumnya, dan menjalankannya terhadap stub baru. Jika sesuatu yang dulu berfungsi kini tidak lagi, Anda akan mengetahuinya sebelum Anda mengirimkannya. Itu adalah pelindung yang kuat untuk layanan mikro yang menyebarkan secara independen, dan ini adalah salah satu bentuk gagasan yang lebih luas yang dibahas dalam pengujian kontrak dua arah.

Di mana Specmatic cocok

Specmatic mendapatkan tempatnya ketika hal-hal berikut berlaku untuk tim Anda:

Spesifikasi OpenAPI (atau AsyncAPI, GraphQL, gRPC) Anda nyata dan cukup lengkap.
Anda memiliki tim atau layanan penyedia dan konsumen yang terpisah yang perlu tetap sinkron.
Anda ingin penyimpangan spesifikasi menggagalkan build secara otomatis, bukan tertangkap dalam tinjauan.
Anda nyaman dengan alur kerja yang mengutamakan CLI dan CI.

Ini kurang cocok jika Anda tidak menyimpan spesifikasi, jika Anda menginginkan ruang kerja visual untuk merancang dan menjelajahi API, atau jika Anda menginginkan satu alat untuk juga menangani debugging ad-hoc, dokumentasi, dan kolaborasi tim. Specmatic berfokus pada mesin kontrak, dan ia melakukan pekerjaan itu dengan baik.

Fokus itu juga tempat platform seperti Apidog mengambil bentuk yang berbeda. Apidog digerakkan oleh skema dengan cara yang sama: ia membaca spesifikasi OpenAPI Anda, memvalidasi respons terhadap skema, dan menjalankan server mock dari skema OpenAPI Anda tanpa kode. Perbedaan jujurnya adalah cakupan. Specmatic adalah alat kontrak yang tajam dan bersifat CLI-native. Apidog menggabungkan desain, pengujian, mocking, dan dokumen ke dalam satu ruang kerja dengan editor visual, sehingga spesifikasi, pengujian, dan mock hidup bersama dan tetap sinkron saat Anda bekerja. Apidog juga bukan broker kontrak berbasis konsumen gaya Pact, jadi jika tim Anda secara khusus membutuhkan broker pakta, tidak ada alat yang cocok untuk itu.

Jika Anda ingin menghasilkan pengujian yang dapat dijalankan langsung dari spesifikasi di dalam ruang kerja semacam itu, lihat bagaimana Apidog menangani pembuatan koleksi pengujian API dari spesifikasi OpenAPI.

Pertanyaan yang sering diajukan

Apakah Specmatic gratis?

Ya. Mesin kontrak intinya adalah sumber terbuka dan gratis untuk digunakan dari CLI atau Docker. Ada penawaran komersial di sekitarnya, tetapi Anda dapat menjalankan pengujian kontrak dan server stub dari spesifikasi OpenAPI tanpa membayar. Periksa situs resmi dan GitHub untuk detail terkini tentang tingkatan berbayar.

Apakah Specmatic hanya berfungsi dengan OpenAPI?

Tidak. OpenAPI adalah titik masuk yang paling umum, tetapi Specmatic juga mendukung AsyncAPI untuk kontrak berbasis event, ditambah GraphQL dan gRPC sejak versi 2.0, bersama dengan format seperti WSDL dan Avro. Modelnya sama di antara semuanya: spesifikasi adalah kontrak yang dapat dieksekusi. Jika Anda baru mengenal format itu sendiri, mulailah dengan tutorial Spesifikasi OpenAPI ini.

Apakah Specmatic sama dengan Pact?

Tidak sepenuhnya. Pact digerakkan oleh konsumen: konsumen mempublikasikan harapan ke broker dan penyedia memverifikasinya. Specmatic digerakkan oleh kontrak: spesifikasi adalah kontrak tunggal yang dibagikan, dan Specmatic memvalidasi penyedia terhadapnya sambil membuat stub penyedia untuk konsumen. Keduanya mengurangi kejutan integrasi, tetapi mereka mengatur kontrak secara berbeda.

Bisakah Specmatic menghasilkan spesifikasi OpenAPI untuk saya?

Ya. Specmatic dapat berjalan sebagai proxy di depan layanan yang ada, menangkap lalu lintas permintaan dan respons nyata, dan menghasilkan dokumen OpenAPI ditambah berkas contoh darinya. Itu berguna ketika Anda memiliki layanan yang berfungsi tetapi belum memiliki spesifikasi resmi untuk diuji.

Kesimpulan

Specmatic menjawab masalah spesifik yang nyata: menjaga layanan yang berjalan tetap jujur terhadap spesifikasi OpenAPI yang seharusnya diikutinya. Dengan membuat spesifikasi dapat dieksekusi, ia memberi Anda pengujian kontrak dan stub yang cocok dari satu berkas, dengan pemeriksaan kompatibilitas mundur di atasnya. Jika Anda bekerja di terminal dan CI dan Anda menyimpan spesifikasi yang solid, itu adalah solusi yang cocok.

Jika Anda lebih suka memiliki kontrak, pengujian, mock, dan dokumen dalam satu ruang kerja visual yang membaca berkas OpenAPI yang sama, cobalah Apidog. Ini memvalidasi respons terhadap skema Anda, membuat mock titik akhir tanpa kode, dan mengubah spesifikasi menjadi koleksi pengujian yang dapat dijalankan. Unduh Apidog untuk mengarahkannya ke spesifikasi Anda dan melihat seluruh siklus desain-ke-pengujian di satu tempat.