Contract Testing API: Menjaga Kompatibilitas Antarlayanan

Ketika aplikasi dibangun dari banyak layanan, perubahan kecil pada satu API bisa menimbulkan kegagalan di tempat yang tidak terduga. Tim penyedia mungkin mengganti nama field, mengubah format respons, atau membuat parameter baru menjadi wajib. Endpoint masih merespons permintaan, tetapi aplikasi konsumen yang bergantung pada kontrak lama tiba-tiba gagal. Contract testing membantu mendeteksi masalah kompatibilitas seperti ini sebelum perubahan masuk ke lingkungan produksi.

Pengujian kontrak bukan pengganti seluruh pengujian integrasi. Tujuannya lebih spesifik: memeriksa apakah dua sisi komunikasi—penyedia API dan konsumennya—masih sepakat tentang bentuk permintaan, respons, header, status, serta perilaku yang mereka andalkan. Pendekatan ini sangat berguna pada arsitektur microservices, aplikasi dengan banyak klien, dan tim yang melakukan deployment secara terpisah.

Apa yang dimaksud dengan kontrak API?

Kontrak API adalah kesepakatan mengenai cara sebuah layanan berkomunikasi. Kontrak dapat menjelaskan endpoint, metode HTTP, parameter, struktur JSON, kode status, autentikasi, dan aturan validasi. Dokumentasi OpenAPI merupakan salah satu cara menyatakan kontrak secara eksplisit, tetapi kontrak juga dapat direpresentasikan melalui contoh interaksi yang benar-benar digunakan konsumen.

Misalnya, layanan pesanan mengembalikan objek dengan field order_id, status, dan total. Aplikasi seluler mungkin hanya bergantung pada dua field pertama. Konsumen lain dapat menggunakan ketiganya. Perubahan yang terlihat aman bagi pemilik layanan belum tentu aman bagi semua konsumen, sehingga kebutuhan nyata konsumen perlu menjadi bagian dari pengujian.

Perbedaan contract testing dan integration testing

Integration testing biasanya menjalankan beberapa komponen bersama untuk memastikan alur kerja menyeluruh berjalan benar. Pengujian itu penting, tetapi dapat memerlukan database, broker, kredensial, dan lingkungan yang lebih lengkap. Contract testing berfokus pada batas komunikasi antarkomponen. Pengujiannya cenderung lebih cepat dan membantu menunjukkan pihak mana yang melanggar kesepakatan.

Keduanya saling melengkapi. Tes kontrak dapat memastikan respons sesuai harapan klien, sementara tes integrasi memeriksa apakah layanan benar-benar menjalankan aturan bisnis, menyimpan data, dan berinteraksi dengan dependensi sebagaimana mestinya. Kontrak yang lulus tidak otomatis membuktikan bahwa hasil perhitungan bisnis benar atau bahwa sistem tahan terhadap beban tinggi.

Pendekatan yang umum digunakan

1. Consumer-driven contract

Pada pendekatan ini, konsumen mendefinisikan bagian kontrak yang benar-benar dibutuhkannya. Tim penyedia kemudian memverifikasi bahwa implementasinya memenuhi ekspektasi tersebut. Keuntungannya, pengujian berpusat pada penggunaan nyata dan tidak harus mengunci setiap detail respons yang tidak dipakai konsumen. Tantangannya adalah mengumpulkan kontrak dari seluruh konsumen dan memastikan kontrak tetap diperbarui saat kebutuhan berubah.

2. Pengujian berbasis spesifikasi

Jika API memiliki spesifikasi OpenAPI, pipeline dapat memvalidasi permintaan dan respons terhadap skema tersebut. Cara ini membantu menjaga tipe data, field wajib, format, dan kode respons tetap konsisten. Namun, spesifikasi yang tidak sesuai implementasi hanya akan memberi rasa aman palsu. Jadikan spesifikasi sebagai bagian dari proses pengembangan dan uji terhadap layanan yang benar-benar dijalankan.

3. Provider verification

Setelah kontrak tersedia, penyedia menjalankan verifikasi untuk memastikan respons aktual memenuhi ekspektasi konsumen. Verifikasi dapat dilakukan terhadap build baru sebelum rilis. Untuk sistem yang memiliki banyak konsumen, hasil verifikasi perlu mudah ditelusuri agar pengembang mengetahui kontrak mana yang gagal dan perubahan apa yang memicunya.

Alur penerapan dalam pipeline CI/CD

1. Petakan konsumen. Catat aplikasi atau layanan yang memanggil API, endpoint yang digunakan, dan field yang mereka butuhkan.
2. Rekam ekspektasi. Buat kontrak dari kebutuhan yang terukur, termasuk status sukses, respons kesalahan, autentikasi, dan kasus batas yang penting.
3. Jalankan tes konsumen. Pastikan kode klien berinteraksi sesuai kontrak dan tidak membuat asumsi yang tidak terdokumentasi.
4. Verifikasi penyedia. Jalankan kontrak terhadap versi layanan yang sedang dibangun, bukan hanya terhadap mock yang selalu memberi respons ideal.
5. Pasang pemeriksaan pada pull request. Gagalkan pemeriksaan ketika perubahan mematahkan kontrak yang masih digunakan, lalu tampilkan nama konsumen dan detail perbedaannya.
6. Uji kompatibilitas saat rilis. Periksa versi kontrak yang aktif sebelum deployment dan sediakan strategi migrasi ketika perubahan memang tidak dapat dihindari.

Perubahan yang sering mematahkan kontrak

Perubahan yang jelas berisiko antara lain menghapus field, mengganti nama properti, mengubah angka menjadi string, mengubah arti kode status, atau menambahkan autentikasi wajib tanpa masa transisi. Perubahan yang tampak aditif juga perlu dinilai hati-hati: konsumen dengan parser ketat bisa gagal ketika menerima field baru, sedangkan nilai enum baru dapat merusak logika yang hanya mengenal daftar lama.

Karena itu, jangan menilai kompatibilitas hanya dari perbandingan skema. Perhatikan juga semantik dan perilaku. Field yang tetap bernama sama tetapi berubah satuan, zona waktu, atau maknanya tetap merupakan perubahan kontrak. Untuk perubahan yang tidak kompatibel, pertimbangkan versi endpoint baru, masa deprecasi, dukungan sementara untuk format lama, dan komunikasi kepada pemilik konsumen.

Praktik agar pengujian tetap berguna

Mulailah dari endpoint kritis dan kontrak yang paling sering dipakai, bukan mencoba menguji seluruh API sekaligus. Hindari kontrak yang menyalin semua detail implementasi karena perubahan internal yang tidak relevan akan menghasilkan kegagalan palsu. Sebaliknya, jangan terlalu longgar hingga field penting, kode kesalahan, atau aturan autentikasi tidak diperiksa.

Kontrak harus memiliki pemilik dan proses pembaruan yang jelas. Simpan berkasnya di version control, jalankan pemeriksaan secara otomatis, dan dokumentasikan pengecualian. Data uji juga perlu aman: gunakan nilai sintetis dan rahasia pengujian, bukan token produksi atau informasi pribadi pelanggan. Untuk API eksternal yang tidak dapat diverifikasi langsung, gabungkan validasi spesifikasi dengan pengujian berkala dan pemantauan respons nyata.

Kesimpulan

Contract testing membantu tim mendeteksi ketidaksesuaian antara penyedia dan konsumen API sebelum perubahan merusak layanan lain. Pendekatan consumer-driven, validasi spesifikasi, dan provider verification dapat dipadukan sesuai kebutuhan sistem. Hasil terbaik datang dari kontrak yang mewakili penggunaan nyata, dijalankan otomatis di CI/CD, dan dirawat bersama oleh tim yang terlibat. Dengan demikian, layanan dapat dikembangkan dan dirilis lebih mandiri tanpa mengorbankan kompatibilitas antarlayanan.