🥋 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

1. What is match in Karate?

2. What is assert in Karate?

3. Key Differences Between match and assert

4. Real-World API Testing Use Cases

5. Practice Exercises (Beginner to Advanced)

6. 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

---

🌐 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

---

🟡 Level 2 JSON Response

* def response = {
  "roles": ["admin", "editor"],
  "email": "test@gmail.com",
  "profile": {
    "name": "Alice",
    "country": null
  }
}

🟡 Level 2: Practice Assertions

---

🔴 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

---

✅ 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.