Anda menginginkan tes API yang mudah dibaca seperti bahasa Inggris biasa, berada di Git di samping kode Anda, dan berjalan di pipeline CI mana pun. Karate dibangun untuk tujuan itu. Ia menggunakan domain-specific language (DSL) sehingga Anda menulis tes sebagai langkah-langkah Given / When / Then alih-alih metode Java. Panduan ini menjelaskan apa itu Karate, bagaimana file fiturnya bekerja, dan contoh yang dapat dijalankan.
Apa Itu Karate
Karate adalah framework otomatisasi pengujian berbasis Java open-source untuk API. Anda menjelaskan setiap tes sebagai skenario dalam file .feature menggunakan Gherkin, struktur Given/When/Then yang sama yang berasal dari Behavior-Driven Development. Perbedaannya dari alat seperti Cucumber adalah Anda tidak menulis kode lem perekat (glue code) definisi langkah (step-definition). Karate menyediakan langkah-langkah HTTP, assertions, dan penanganan JSON secara built-in, sehingga tes API yang berfungsi sama sekali tidak memerlukan Java.
Proyek ini mencakup lebih dari sekadar pengujian API. Repositori ini menyertakan modul untuk mocks, pengujian kinerja (melalui Gatling), dan otomatisasi UI. Untuk panduan ini, fokusnya adalah inti pengujian API, yang pertama kali banyak dicari oleh sebagian besar tim.
Karena tes adalah file teks biasa, versinya mudah dikelola. Perbedaan pull request menunjukkan dengan tepat assertion mana yang berubah. Itu berjalan baik dengan code review dan dengan workflow berbasis kode yang Git-native.
Jika Anda baru mengenal gaya Given/When/Then, pengantar kami tentang Behavior-Driven Development menjelaskan asal-usulnya dan mengapa tim menggunakannya.
Cara Kerjanya: File Fitur dan karate-config.js
Tes Karate dimulai dengan file fitur. Setiap file memiliki satu blok Feature: dan satu atau lebih blok Scenario:. Di dalam skenario, Anda menyiapkan permintaan dengan Given, menjalankannya dengan When, dan memverifikasi dengan Then.
Berikut adalah struktur yang ditunjukkan oleh panduan cepat Karate:
Feature: User API
Scenario: List all users
Given url 'https://jsonplaceholder.typicode.com'
And path 'users'
When method get
Then status 200
And match response == '#[10]'
Baca dari atas ke bawah. url mengatur alamat dasar. path menambahkan sumber daya. method get mengirimkan permintaan. status 200 memeriksa kode HTTP. Baris terakhir memverifikasi bahwa respons adalah array JSON dengan tepat 10 item. #[10] adalah penanda Karate, bukan JavaScript. Lebih lanjut tentang penanda-penanda tersebut di bagian assertions.
Gherkin di sini adalah Given/When/Then standar. Jika Anda ingin melihat lebih dalam sintaks tersebut, lihat panduan Gherkin untuk BDD dan pengujian API kami.
Sebagian besar proyek memerlukan nilai-nilai spesifik lingkungan: URL dasar dev, token staging, endpoint prod. Karate menanganinya dengan satu file bernama karate-config.js. File ini berjalan sekali sebelum tes Anda dan mengembalikan objek konfigurasi yang dapat dibaca oleh setiap skenario.
function fn() {
var env = karate.env || 'dev';
var config = {
baseUrl: 'https://jsonplaceholder.typicode.com'
};
if (env === 'qa') {
config.baseUrl = 'https://qa.example.com';
}
return config;
}
karate.env berasal dari properti sistem yang Anda berikan saat runtime. Ganti lingkungan tanpa menyentuh satu pun file fitur. Dalam skenario, Anda kemudian akan menulis Given url baseUrl alih-alih meng-hardcode alamatnya.
Contoh Skenario
Mari kita tulis sesuatu dengan request body. Skenario ini membuat pengguna, memeriksa status, dan memvalidasi bentuk respons.
Feature: Create user
Background:
* url baseUrl
Scenario: Create a new user returns 201
Given path 'users'
And request { name: 'Ada', job: 'engineer' }
When method post
Then status 201
And match response.name == 'Ada'
And match response.id == '#string'
Beberapa hal yang perlu diperhatikan. Blok Background: berjalan sebelum setiap skenario dalam file, sehingga Anda menetapkan URL dasar sekali. Tanda * adalah langkah wildcard; Karate memperlakukan * sama dengan Given, When, atau Then, yang memungkinkan Anda menulis langkah-langkah penyiapan tanpa mengkhawatirkan tata bahasa. Kata kunci request mengambil payload JSON secara langsung. Tidak ada serializer, tidak ada POJO. Dan #string adalah fuzzy matcher yang menyatakan bahwa bidang id ada dan berupa string, tanpa mengaitkannya dengan nilai tertentu.
Assertions dan Pencocokan JSON
Assertions adalah tempat Karate menunjukkan keunggulannya. Kata kunci utamanya adalah match. Ia membandingkan nilai aktual dengan nilai yang diharapkan dan akan menggagalkan tes jika ada ketidakcocokan.
Pencocokan persis memeriksa kesamaan:
And match response == { id: '#number', name: 'Ada', job: 'engineer' }
Token #number, #string, #boolean, dan #uuid adalah fuzzy matchers. Mereka menyatakan tipe dan keberadaan tanpa menuntut nilai literal, yang menjaga stabilitas tes ketika server mengembalikan ID atau timestamp yang dihasilkan.
Jika Anda hanya peduli pada subset bidang, gunakan contains:
And match response contains { name: 'Ada' }
Itu akan berhasil selama name sama dengan Ada, bahkan jika respons memiliki sepuluh bidang lainnya. Karate juga mendukung !contains, contains only, contains any, dan contains deep untuk kontrol yang lebih baik atas pencocokan sebagian.
Anda juga dapat memvalidasi array. match response == '#[10]' memverifikasi array dengan panjang 10. Anda dapat menerapkan skema ke setiap elemen dengan each:
And match each response == { id: '#number', name: '#string' }
Baris tunggal ini memeriksa bahwa setiap objek dalam array memiliki id numerik dan name berupa string. Validasi bentuk semacam itu akan memerlukan loop dan beberapa assertion dalam framework pengujian tujuan umum. Jika Anda ingin gambaran yang lebih luas tentang memvalidasi respons, panduan praktis kami untuk assertion API mencakup pola-pola di berbagai alat.
Pengujian Berbasis Data dan CI
Test suite yang sebenarnya menjalankan logika yang sama terhadap banyak input. Karate menanganinya dengan Scenario Outline dan tabel Examples. Placeholder dalam tanda kurung siku akan diisi dari setiap baris.
Scenario Outline: Create users from a table
Given url baseUrl
And path 'users'
And request { name: '<name>', job: '<job>' }
When method post
Then status 201
And match response.name == '<name>'
Examples:
| name | job |
| Ada | engineer |
| Grace | scientist |
| Alan | analyst |
Itu menjalankan skenario tiga kali, sekali per baris. Anda juga dapat membaca baris dari file eksternal alih-alih tabel inline, yang menjaga set data besar keluar dari file fitur Anda:
Examples:
| read('classpath:test-data/users.json') |
Karate membaca file JSON dan CSV dengan cara ini, sehingga data pengujian Anda dapat berada di mana pun tim Anda lebih suka mengelolanya.
Untuk continuous integration, Anda memiliki dua jalur. Dalam proyek Maven atau Gradle, Karate berjalan melalui JUnit 5. Anda menambahkan dependensi karate-junit5 dan mengarahkan runner ke file fitur Anda, sehingga mvn test menjalankannya seperti unit test lainnya. Itu berarti langkah CI Anda yang sudah ada tidak memerlukan alat khusus.
Jalur kedua adalah jar mandiri, yang tidak memerlukan alat build. Unduh karate.jar dari rilis proyek dan jalankan file fitur secara langsung. Perhatikan bahwa jar memerlukan versi Java terbaru, jadi periksa catatan rilis untuk versi minimumnya.
java -jar karate.jar src/test/java/features
Anda dapat memfilter berdasarkan tag, berjalan secara paralel, dan memilih direktori output:
java -jar karate.jar --tags @smoke --threads 4 --output reports src/test/java/features
Lewatkan lingkungan dengan properti sistem, yang mengalir ke karate.env di dalam karate-config.js:
java -jar karate.jar -Dkarate.env=qa src/test/java/features
Karate menulis laporan HTML ke direktori output setelah setiap kali dijalankan, sehingga kegagalan mudah diperiksa dalam artefak pipeline. Untuk gambaran CI yang lebih luas, lihat cara mengotomatiskan tes API di CI/CD.
Kekuatan dan Pertukaran (Trade-Offs)
Karate memiliki kekuatan yang jelas. Tes mudah dibaca seperti bahasa Inggris biasa, yang menurunkan hambatan bagi orang yang tidak fasih dalam Java. Pencocokan JSON bawaan, termasuk fuzzy matchers dan each, menghilangkan banyak boilerplate assertion. Semuanya berada dalam file teks di bawah Git, sehingga tes dapat di-review dan di-diff seperti kode sumber. Dan itu mencakup lebih dari HTTP, sehingga tim dapat menambahkan mocks atau tes kinerja nanti tanpa mengganti alat.
Pertukaran (trade-offs) juga nyata. Karate berjalan di JVM, jadi Anda memerlukan Java terinstal dan tingkat kenyamanan dengan ekosistem JVM untuk apa pun di luar dasar. DSL-nya adalah hal yang perlu dipelajari tersendiri; sintaksnya mudah dibaca tetapi menulis matcher dan pola penggunaan kembali yang benar memerlukan latihan. Logika yang dapat digunakan kembali, custom helper, dan penyiapan yang kompleks sering kali menarik Anda kembali ke fungsi JavaScript atau interop Java. Dan karena tes adalah kode, non-developer dalam tim biasanya tidak dapat membuat atau mengeditnya tanpa bantuan.
Semua itu bukan celaan. Itu adalah profil framework yang mengutamakan kode. Pertanyaannya adalah apakah profil itu sesuai dengan cara tim Anda ingin bekerja.
Karate vs Pendekatan Tanpa Kode (Apidog)
Karate berbasis kode dan Git-native. Anda menulis file fitur, melakukan commit, dan menjalankannya dari alat build atau jar. Ini cocok untuk insinyur yang menginginkan tes dalam kontrol versi di samping aplikasi dan yang nyaman dengan JVM.
Apidog mengambil jalur visual, tanpa kode untuk tujuan yang sama. Anda membangun skenario pengujian di UI, merangkai permintaan, dan menambahkan assertion dengan mengklik alih-alih menulis DSL. Karena seluruh siklus hidup API (desain, debugging, mocking, dokumentasi) berada di satu tempat, tes dapat menggunakan kembali endpoint dan skema yang telah Anda definisikan. Ini menurunkan hambatan bagi insinyur QA dan orang-orang produk yang tidak ingin mengelola proyek Java.
Suite visual tidak terpaku di UI. Apidog menjalankannya secara headless di CI melalui Apidog CLI, sehingga suite tanpa kode masih cocok dengan pipeline otomatis. Anda menginstalnya dengan Node:
npm install -g apidog-cli
Kemudian picu skenario atau suite yang disimpan berdasarkan ID, menunjuk ke lingkungan dan memilih format laporan:
apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t <scenarioOrSuiteId> -e <environmentId> -r cli,html,junit
Flag -t menargetkan skenario, folder, atau suite; -e memilih lingkungan; -r memilih satu atau lebih reporter (cli, html, json, junit). Untuk eksekusi berbasis data, -d (atau --iteration-data) mengambil jalur file data atau ID data uji. CLI bersifat headless dan berjalan pada langkah CI apa pun yang dapat menjalankan Node. Ini menjalankan skenario Apidog Anda yang tersimpan; ini bukan pengirim permintaan interaktif atau generator beban. Lihat panduan lengkap di Apidog CLI untuk CI/CD, dan perbandingan dengan runner lain di Apidog CLI vs Newman.
Kedua pendekatan menghasilkan tes API otomatis yang berjalan headless di CI. Perbedaannya adalah gaya penulisan: Karate ingin Anda menulis DSL di Git; Apidog ingin Anda mengklik di UI yang juga mengekspor ke pipeline.
Cara Memilih
Pilih Karate ketika tim Anda didominasi developer, nyaman dengan JVM, dan ingin tes di-versioning sebagai kode tepat di samping aplikasi. File fitur teks biasa dan pencocokan JSON bawaan memberikan keuntungan ketika insinyur memiliki suite pengujian secara menyeluruh.
Pilih alat tanpa kode seperti Apidog ketika penulis termasuk orang QA dan produk, ketika Anda ingin tes terikat pada alur kerja desain dan dokumentasi yang ada, atau ketika Anda lebih suka tidak memelihara build Java untuk menjalankan pemeriksaan API. Anda tetap mendapatkan cakupan CI melalui CLI.
Beberapa tim menjalankan keduanya: Karate untuk suite regresi mendalam yang dimiliki kode dan alat visual untuk cakupan luas dan cepat yang dapat diperluas oleh non-developer. Jika Anda masih mempertimbangkan pilihan, ikhtisar kami tentang cara memilih framework pengujian otomatisasi API menyajikan kriteria keputusan.
FAQ
Apakah saya perlu tahu Java untuk menggunakan Karate? Tidak, tidak untuk menulis tes API dasar. File fitur menggunakan Gherkin DSL, dan Karate menyediakan langkah-langkah HTTP serta assertion yang sudah terpasang. Anda perlu Java terinstal untuk menjalankan tes, dan sedikit pengetahuan Java atau JavaScript akan membantu jika Anda membutuhkan helper kustom atau penggunaan kembali yang kompleks.
Apa perbedaan Karate dari Cucumber? Keduanya menggunakan sintaks Given/When/Then dari Gherkin. Dengan Cucumber Anda menulis kode definisi langkah (step-definition) untuk mendukung setiap langkah. Karate menyediakan langkah-langkah pengujian API untuk Anda, sehingga tidak ada kode lem perekat (glue code) yang perlu dipelihara untuk tes HTTP standar.
Bisakah Karate berjalan tanpa Maven atau Gradle? Ya. Unduh karate.jar mandiri dari rilis proyek dan jalankan file fitur dengan java -jar karate.jar <path>. Ini mendukung tag, thread paralel, dan direktori output kustom tanpa alat build apa pun.
Apa arti sintaks #string atau #[10]? Itu adalah fuzzy matchers dari Karate. #string menyatakan bahwa suatu bidang adalah string dengan nilai apa pun, #number adalah angka, dan #[10] menyatakan array JSON dengan panjang 10. Ini memungkinkan Anda memvalidasi bentuk respons tanpa meng-hardcode nilai yang dihasilkan.
Bisakah tes API tanpa kode tetap berjalan di CI? Ya. Alat visual seperti Apidog mengekspor skenario yang disimpan ke Apidog CLI, yang bersifat headless dan berjalan pada langkah CI apa pun dengan Node. Jadi Anda membuat tes di UI dan tetap mendapatkan eksekusi pipeline otomatis.