DEV Community

Cover image for Kiểm thử API Karate: Hướng dẫn thực hành về DSL
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

Kiểm thử API Karate: Hướng dẫn thực hành về DSL

Bạn muốn viết kiểm thử API dễ đọc như tiếng Anh, lưu cùng mã nguồn trong Git và chạy được trong CI. Karate được thiết kế cho việc đó: bạn viết test bằng DSL dạng Given / When / Then trong file .feature, thay vì phải viết nhiều lớp Java. Bài viết này hướng dẫn cách thiết lập Karate, cách tổ chức feature file, cách viết assertion JSON và cách chạy trong CI.

Dùng thử Apidog ngay hôm nay

Karate là gì

Karate là framework kiểm thử tự động mã nguồn mở, chạy trên Java và tập trung mạnh vào API testing. Bạn mô tả mỗi test case trong file .feature bằng Gherkin, với cấu trúc quen thuộc từ BDD: Given, When, Then.

Điểm khác biệt quan trọng so với Cucumber: với Karate, bạn không cần viết step-definition glue code. Karate đã có sẵn các bước HTTP, assertion, xử lý JSON và matcher, nên một API test cơ bản có thể chạy mà không cần viết Java.

Karate không chỉ dùng cho API testing. Dự án còn có module cho mock, performance testing thông qua Gatling và UI automation. Tuy nhiên, trong bài này chúng ta tập trung vào phần cốt lõi: viết và chạy kiểm thử API.

Vì test là file văn bản thuần túy, bạn có thể commit chúng vào Git, review bằng pull request và thấy rõ assertion nào đã thay đổi. Cách này phù hợp với quy trình kiểm thử API dựa trên mã và tích hợp Git.

Nếu bạn mới làm quen với Given / When / Then, hãy xem thêm phần giới thiệu về Phát triển theo hướng hành vi.

Cách Karate hoạt động

Một test Karate thường gồm:

  1. File .feature chứa các scenario.
  2. File karate-config.js chứa cấu hình dùng chung.
  3. Runner hoặc CLI để chạy test trong local/CI.

Cấu trúc tối thiểu của một feature file:

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]'
Enter fullscreen mode Exit fullscreen mode

Ý nghĩa từng dòng:

  • url: đặt base URL.
  • path: thêm endpoint path.
  • method get: gửi HTTP GET request.
  • status 200: kiểm tra HTTP status code.
  • match response == '#[10]': xác nhận response là mảng có đúng 10 phần tử.

#[10] là cú pháp matcher của Karate, không phải JavaScript. Nó giúp kiểm tra cấu trúc dữ liệu mà không cần viết vòng lặp hoặc assertion thủ công.

Nếu bạn muốn hiểu kỹ hơn cú pháp Gherkin, xem hướng dẫn Gherkin cho BDD và kiểm thử API.

Cấu hình môi trường với karate-config.js

Trong dự án thực tế, bạn thường cần nhiều môi trường: dev, qa, staging, prod. Karate xử lý việc này bằng file karate-config.js.

Ví dụ:

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;
}
Enter fullscreen mode Exit fullscreen mode

Sau đó trong file .feature, dùng biến baseUrl thay vì hard-code URL:

Feature: User API

Background:
  * url baseUrl

Scenario: List all users
  Given path 'users'
  When method get
  Then status 200
Enter fullscreen mode Exit fullscreen mode

Khi chạy test, truyền môi trường bằng system property:

java -jar karate.jar -Dkarate.env=qa src/test/java/features
Enter fullscreen mode Exit fullscreen mode

Cách này giúp bạn đổi môi trường mà không sửa feature file.

Viết scenario POST request

Ví dụ dưới đây tạo user mới, kiểm tra status code và xác thực response body:

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'
Enter fullscreen mode Exit fullscreen mode

Các điểm cần chú ý:

  • Background chạy trước mỗi scenario trong file.
  • * là wildcard step, thường dùng cho setup.
  • request nhận trực tiếp JSON payload.
  • #string xác nhận field tồn tại và là chuỗi.
  • Bạn không cần tạo POJO, serializer hoặc client class riêng.

Assertion và JSON matching

Từ khóa quan trọng nhất khi kiểm tra response trong Karate là match.

Match chính xác 

And match response == { id: '#number', name: 'Ada', job: 'engineer' }
Enter fullscreen mode Exit fullscreen mode

Các fuzzy matcher thường dùng:

  • #number: giá trị là số.
  • #string: giá trị là chuỗi.
  • #boolean: giá trị là boolean.
  • #uuid: giá trị là UUID.

Chúng hữu ích khi API trả về ID, timestamp hoặc giá trị động.

Match một phần response

Khi chỉ cần kiểm tra một vài field:

And match response contains { name: 'Ada' }
Enter fullscreen mode Exit fullscreen mode

Assertion này pass nếu response.name bằng Ada, dù response còn nhiều field khác.

Karate cũng hỗ trợ:

And match response !contains { error: true }
And match response contains only { name: 'Ada', job: 'engineer' }
And match response contains any [{ role: 'admin' }, { role: 'user' }]
And match response contains deep { profile: { active: true } }
Enter fullscreen mode Exit fullscreen mode

Validate mảng JSON

Kiểm tra response là mảng có 10 phần tử:

And match response == '#[10]'
Enter fullscreen mode Exit fullscreen mode

Kiểm tra schema cho từng phần tử trong mảng:

And match each response == { id: '#number', name: '#string' }
Enter fullscreen mode Exit fullscreen mode

Dòng này xác nhận mọi object trong mảng đều có:

  • id là số.
  • name là chuỗi.

Trong framework kiểm thử tổng quát, bạn thường phải viết vòng lặp và nhiều assertion. Với Karate, phần này được biểu diễn ngắn gọn trong DSL.

Nếu bạn muốn xem thêm các mẫu kiểm tra response, tham khảo hướng dẫn thực tế về các khẳng định API.

Kiểm thử theo hướng dữ liệu

Khi cần chạy cùng một logic với nhiều input, dùng Scenario Outline và Examples.

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   |
Enter fullscreen mode Exit fullscreen mode

Scenario trên chạy 3 lần, tương ứng 3 dòng dữ liệu.

Với dataset lớn, đưa dữ liệu ra file riêng:

Examples:
  | read('classpath:test-data/users.json') |
Enter fullscreen mode Exit fullscreen mode

Karate có thể đọc JSON và CSV, giúp bạn tách test logic khỏi test data.

Chạy Karate trong CI

Bạn có hai cách phổ biến để chạy Karate.

Cách 1: Chạy qua Maven hoặc Gradle

Trong dự án Maven/Gradle, Karate chạy thông qua JUnit 5. Bạn thêm dependency karate-junit5, tạo runner trỏ đến thư mục feature file, rồi dùng lệnh test quen thuộc:

mvn test
Enter fullscreen mode Exit fullscreen mode

Cách này phù hợp nếu dự án của bạn đã dùng JVM build tool và pipeline CI hiện tại đã có bước test.

Cách 2: Chạy bằng standalone JAR

Nếu không muốn cấu hình Maven hoặc Gradle, dùng karate.jar độc lập từ release của dự án.

Chạy toàn bộ feature trong thư mục:

java -jar karate.jar src/test/java/features
Enter fullscreen mode Exit fullscreen mode

Chạy smoke test, bật parallel và xuất report:

java -jar karate.jar --tags @smoke --threads 4 --output reports src/test/java/features
Enter fullscreen mode Exit fullscreen mode

Chạy theo môi trường:

java -jar karate.jar -Dkarate.env=qa src/test/java/features
Enter fullscreen mode Exit fullscreen mode

Sau mỗi lần chạy, Karate tạo HTML report trong thư mục output. Bạn có thể lưu thư mục này làm artifact trong CI để debug lỗi. Nếu cần bức tranh tổng quát hơn, xem hướng dẫn tự động hóa kiểm thử API trong CI/CD.

Điểm mạnh và đánh đổi của Karate

Karate phù hợp khi bạn muốn API test nằm trong Git và được review như code.

Điểm mạnh:

  • Test dễ đọc với cú pháp Given / When / Then.
  • Không cần viết step definition cho HTTP test cơ bản.
  • JSON assertion mạnh, có fuzzy matcher và match each.
  • Dễ tích hợp CI.
  • Có thể mở rộng sang mock, performance testing và UI automation.

Đánh đổi:

  • Cần Java/JVM để chạy.
  • DSL riêng cần thời gian làm quen.
  • Logic tái sử dụng hoặc setup phức tạp có thể kéo bạn về JavaScript hoặc Java.
  • Người không quen code có thể khó tự tạo hoặc chỉnh sửa test.

Nói ngắn gọn: Karate là lựa chọn tốt cho team ưu tiên test-as-code.

Karate so với cách tiếp cận không mã của Apidog

Karate theo hướng code-first. Bạn viết .feature, commit vào Git và chạy bằng build tool hoặc JAR. Cách này phù hợp với developer muốn test nằm cạnh code ứng dụng.

Apidog đi theo hướng trực quan, không mã. Bạn tạo test scenario trong UI, nối chuỗi request và thêm assertion bằng thao tác chọn/click thay vì viết DSL. Vì thiết kế API, debug, mock, test và tài liệu nằm cùng một nơi, test có thể tái sử dụng endpoint và schema đã định nghĩa.

Các test trực quan vẫn có thể chạy trong CI bằng Apidog CLI.

Cài CLI:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Chạy một scenario hoặc test suite đã lưu:

apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t <scenarioOrSuiteId> -e <environmentId> -r cli,html,junit
Enter fullscreen mode Exit fullscreen mode

Ý nghĩa các flag:

  • -t: chọn scenario, folder hoặc test suite.
  • -e: chọn environment.
  • -r: chọn report format, ví dụ cli, html, json, junit.
  • -d hoặc --iteration-data: truyền file dữ liệu hoặc test data ID cho data-driven run.

Apidog CLI là headless, chạy được trong bất kỳ CI step nào có Node. Nó chạy các scenario Apidog đã lưu; nó không phải công cụ gửi request tương tác hoặc load generator. Xem thêm Apidog CLI cho CI/CD và so sánh Apidog CLI so với Newman.

Cả Karate và Apidog đều hỗ trợ API test tự động trong CI. Khác biệt chính là cách soạn test:

  • Karate: viết DSL trong Git.
  • Apidog: tạo test trong UI và chạy headless qua CLI.

Cách lựa chọn

Chọn Karate nếu:

  • Team của bạn chủ yếu là developer.
  • Bạn muốn test version-control cùng source code.
  • Bạn quen với JVM/Maven/Gradle.
  • Bạn cần assertion JSON mạnh và test-as-code.

Chọn công cụ không mã như Apidog nếu:

  • QA, product hoặc thành viên không chuyên code cũng cần viết test.
  • Bạn muốn test gắn với thiết kế API, mock và tài liệu.
  • Bạn không muốn duy trì project Java chỉ để kiểm thử API.
  • Bạn vẫn cần chạy test trong CI bằng CLI.

Một số team dùng cả hai: Karate cho regression suite sâu do developer sở hữu, và Apidog cho coverage rộng hơn mà QA hoặc non-developer có thể mở rộng nhanh. Nếu vẫn đang đánh giá lựa chọn, xem thêm hướng dẫn chọn một framework kiểm thử tự động hóa API.

Câu hỏi thường gặp

Tôi có cần biết Java để dùng Karate không?

Không cần nếu bạn chỉ viết API test cơ bản. Bạn viết test bằng Gherkin DSL và dùng các step HTTP/assertion có sẵn. Tuy nhiên, bạn cần cài Java để chạy test. Kiến thức Java hoặc JavaScript sẽ hữu ích khi cần helper function hoặc setup phức tạp.

Karate khác Cucumber như thế nào?

Cả hai đều dùng cú pháp Given / When / Then. Với Cucumber, bạn phải viết step definition cho từng bước. Với Karate, các bước HTTP và assertion đã có sẵn, nên bạn không cần glue code cho API test tiêu chuẩn.

Karate có chạy được mà không cần Maven hoặc Gradle không?

Có. Bạn có thể tải karate.jar độc lập và chạy:

java -jar karate.jar <path>
Enter fullscreen mode Exit fullscreen mode

JAR hỗ trợ tag filtering, parallel execution và custom output directory.

#string, #number và #[10] nghĩa là gì?

Đó là fuzzy matcher của Karate:

  • #string: field là chuỗi.
  • #number: field là số.
  • #[10]: response là mảng có 10 phần tử.

Chúng giúp bạn validate cấu trúc response mà không hard-code giá trị động.

API test không mã có chạy được trong CI không?

Có. Một công cụ trực quan như Apidog có thể chạy scenario đã lưu bằng Apidog CLI. CLI chạy headless trên CI có Node, nên bạn có thể tạo test trong UI nhưng vẫn tự động hóa trong pipeline.

Top comments (0)