๐ฅ KarateBDD: Understanding `match` vs `assert`


In API test automation, match
and assert
are two of the most powerful features of KarateBDD. While both validate data, they do so in fundamentally different ways.
In this guide, you'll:
Understand their differences
See real-world usage in component, integration, and E2E testing
Practice with 3 levels of hands-on exercises
๐ Table of Contents
What is
match
in Karate?What is
assert
in Karate?Key Differences Between
match
andassert
Real-World API Testing Use Cases
Practice Exercises (Beginner to Advanced)
Conclusion
1๏ธโฃ What is match
in Karate?
match
is used to compare actual vs expected data โ especially JSON or XML structures.
It returns pass
if the comparison succeeds and fail
otherwise.
โ Simple Examples
* def response = { name: 'Alice', age: 30 }
* match response.name == 'Alice' # โ
Pass: exact match
* match response.name == 'Bob' # โ Fail: value mismatch
* match response == { name: 'Alice', age: 30 } # โ
Pass: full object match
* match response == { name: 'Alice' } # โ Fail: partial match is not allowed with `==`
๐ match
Variants
contains
โ Partial match allowed
* match response contains { name: 'Alice' } # โ
Pass
* match response contains { name: 'Bob' } # โ Fail
contains only
โ Must contain exactly these values (order doesn't matter)
* def roles = ['admin', 'editor']
* match roles contains only ['editor', 'admin'] # โ
Pass
* match roles contains only ['admin'] # โ Fail
contains any
โ At least one value must match
* def tags = ['karate', 'api', 'testing']
* match tags contains any ['dev', 'karate'] # โ
Pass
* match tags contains any ['qa', 'ops'] # โ Fail
!contains
โ Asserts absence of value
* def roles = ['user', 'guest']
* match roles !contains 'admin' # โ
Pass: 'admin' not present
* match roles !contains 'guest' # โ Fail: 'guest' is present
2๏ธโฃ What is assert
in Karate?
assert
is used for boolean condition validation.
It evaluates the condition and returns pass
if true, otherwise fail
.
โ Simple Examples
* def age = 25
* assert age > 18 # โ
Pass
* assert age < 10 # โ Fail
๐ง More Use Cases
* def price = 150
* assert price >= 100 && price <= 200 # โ
Pass
* def user = { name: 'Lannister' }
* assert typeof user.name == 'string' # โ
Pass
* def name = 'karate'
* assert name.length > 3 # โ
Pass
* assert name.startsWith('k') # โ
Pass
๐ Key Differences
Feature | match | assert |
Purpose | Data structure comparison | Boolean condition check |
Best For | JSON/XML/API response validation | Logical rules, numeric/string checks |
Output | Detailed diff | Pass/fail with message |
Style | Karate BDD DSL | JavaScript-style syntax |
๐ Real-World API Testing Use Cases
๐งฉ Component Test (Microservice level)
* def response = call read('get-user.feature')
* match response == { id: '#number', name: '#string' } # โ
Validate structure
* assert response.id > 0 # โ
Check value rule
๐ Integration Test (Multiple APIs)
* def user = call read('get-user.feature')
* def orders = call read('get-orders.feature') { userId: user.id }
* match orders contains { userId: user.id } # โ
Data relationship
* assert orders.length > 0 # โ
Business expectation
๐ End-to-End Test (Full business flow)
* def user = call read('register-user.feature')
* def order = call read('create-order.feature') { userId: user.userId }
* match order contains { status: 'confirmed', userId: user.userId } # โ
Flow integrity
* assert order.totalAmount > 0 # โ
Rule enforcement
๐งช Practice Exercises
๐ข Level 1 JSON Response
* def response = {
"name": "Bob",
"age": 28,
"active": true
}
๐ข Level 1: Practice Assertions
# | Task | Answer |
1 | Match a string value | match response.name == 'Bob' |
2 | Assert number is > 10 | assert response.age > 10 |
3 | Match full object | match response == { name: 'Bob', age: 28, active: true } |
4 | Match with contains | match response contains { active: true } |
5 | Assert a boolean is true | assert response.active == true |
๐ก Level 2 JSON Response
* def response = {
"roles": ["admin", "editor"],
"email": "test@gmail.com",
"profile": {
"name": "Alice",
"country": null
}
}
๐ก Level 2: Practice Assertions
# | Task | Answer |
1 | Match role list with contains only | match response.roles contains only ['admin', 'editor'] |
2 | Assert email ends with "@gmail.com" | assert response.email.endsWith('@gmail.com') |
3 | Match nested JSON with optional key | match response.profile contains { country: #null } |
4 | Assert exclusion with !contains | match response.roles !contains 'banned' |
5 | Combine multiple asserts | assert response.email != null && response.roles.length == 2 |
๐ด Level 3 JSON Response
* def response = [
{ "id": 1, "name": "Item1", "quantity": 50 },
{ "id": 2, "name": "Item2", "quantity": 75 },
{ "id": 3, "name": "Item3", "quantity": 25 }
]
๐ด Level 3: Practice Assertions
# | Task | Answer |
1 | Match each array object structure | match each response == { id: '#number', name: '#string', quantity: '#number' } |
2 | Assert unique IDs | assert karate.distinct(response, x => x.id).length == response.length |
3 | Match using regex | match response[0].name == '#regex ^Item\\d$' |
4 | Assert total quantity > 100 | assert response[0].quantity + response[1].quantity + response[2].quantity > 100 |
5 | Validate chained object integrity | assert response[0].id == 1 && response[1].id == 2 && response[2].id == 3 |
โ Conclusion
Use
match
for validating structures and values.Use
assert
for logic, math, conditions, and expressions.Together, they build expressive, testable, and maintainable API checks.
Subscribe to my newsletter
Read articles from Himanshu Pandey directly inside your inbox. Subscribe to the newsletter, and don't miss out.
Written by
