🖼️ See the drawing + lab 🏠 Course home 🌿 Branch on GitHub ✏️ View source

🖼️ आकृती आणि labThe drawing + lab पूर्ण पानावर उघडा ↗Open full page ↗

🤝 धडा 07 — Contract tests: consumer च्या अपेक्षा विरुद्ध provider चे response

📍 तुम्ही इथे आहात: 12 पैकी धडा 07 · मागे: lesson-06-integration · पुढे: lesson-08-e2e-pyramid

📦 या ब्रँचमध्ये काय आहे

धडे 01–06, आणि contract tests: report-card code (consumer) attendance service (provider) कडून त्याला नेमके काय लागते ते लिहून ठेवतो, आणि provider प्रत्येक release ship होण्यापूर्वी त्या यादीशी तपासतो. exam/lab.py मधले CONTRACT आणि verify_contract(); exam/demo.py मधले contract().

🧒 5 वर्षांच्या मुलाला समजावल्यासारखे

कतरिनाच्या report cards ना attendance office कडून दोन आकडे लागतात: उपस्थित दिवस आणि एकूण दिवस. ती ते एका कार्डवर लिहिते आणि attendance office च्या भिंतीवर लावते: 🤝

"मी विद्यार्थिनी 42 बद्दल विचारते तेव्हा मला परत हवे: days_present (पूर्ण संख्या) आणि days_total (पूर्ण संख्या)."

ते कार्ड म्हणजे contract.

Attendance office आपला form बदलण्यापूर्वी, तो form कतरिनाच्या कार्डशी तपासते.

v2 एक नवी चौकट जोडते, "late days". कतरिनाने ती कधीच मागितली नव्हती, म्हणून तिला हरकत नाही. ✅
v3 "days_present" चे नाव बदलून "present" करते. कतरिनाचा code "days_present" शोधेल आणि crash होईल. नवा form बाहेर जाण्याच्या आधीच कार्ड ते पकडते. ❌
v4 "200" आकड्याऐवजी शब्दांत लिहिते. पकडले. ❌

दोन्ही offices एकत्र चालवण्याची कोणालाच गरज पडली नाही. प्रत्येक बाजूने स्वतःला त्याच कार्डशी तपासले.

🗺️ आकृती

flowchart LR
    c["📇 consumer: report cards<br/>needs days_present:int, days_total:int"] -->|"writes the contract"| k["🤝 contract<br/>GET /attendance/42 → 200"]
    k -->|"replayed in the provider's CI"| p["🏢 provider: attendance"]
    p --> v1["v1 as today ✅"]
    p --> v2["v2 adds late_days ✅"]
    p --> v3["v3 renames to present ❌<br/>missing field days_present"]
    p --> v4["v4 days_total as text ❌<br/>str, expected int"]

🗺️ काढलेली आवृत्ती + एक lab: https://school-edh.pages.dev/testing/lesson-diagrams.html#l07

❓ काय

Consumer / provider — API ला call करणारी बाजू आणि ती API पुरवणारी बाजू.
Contract — consumer करत असलेल्या requests आणि responses चे ते भाग ज्यांवर तो अवलंबून असतो: status, fields, types. संपूर्ण API नाही — फक्त हा consumer जे वापरतो तेवढेच.
Consumer-driven contract testing — consumers आपले contracts प्रकाशित करतात; provider चा build प्रत्येक contract खऱ्या provider code वर पुन्हा चालवतो आणि कोणताही consumer मोडणार असेल तर fail होतो. Pact हे सर्वात प्रसिद्ध साधन आहे; त्याच्या contract files ना pacts म्हणतात.
Provider verification — तपासणीची provider बाजू: provider सुरू करा (प्रत्येक case साठी test data तयार करून — Pact यांना provider states म्हणते), नोंदवलेली प्रत्येक request पाठवा, response ची तुलना करा.
Tolerant reader — consumer ने न मागितलेल्या fields कडे तो दुर्लक्ष करतो. म्हणूनच field जोडणे (v2) सुरक्षित आहे आणि नाव बदलणे (v3) नाही.
Matching by type — consumer ला खरोखर काय लागते तेच contract ने पक्के करावे: बहुतेक वेळा "एक integer", "नेमके 172" नाही. जास्त कडक contract निरुपद्रवी बदलही अडवतो.
Schema-first पर्याय — दोन्ही बाजू एकाच shared schema वर test करतात (OpenAPI, JSON Schema, protobuf). Schemathesis सारखी साधने OpenAPI file वरून requests तयार करतात.

🤔 का

कारण धडा 05 चे stubs हे दुसऱ्या team च्या service बद्दलचे दावे आहेत, आणि दोन्ही services एकत्र चालवणाऱ्या end-to-end tests हळू आणि flaky असतात (धडा 08). Contract त्या दाव्याचे रूपांतर दोन्ही teams ज्यावर test करतात अशा file मध्ये करते: consumer च्या unit tests ती stub म्हणून वापरतात, आणि provider चा build सिद्ध करतो की तो अजूनही तसेच उत्तर देतो. मोडणारा बदल deployment आधी, provider च्या pipeline मध्ये, तो बदल करणाऱ्या team कडूनच पकडला जातो.

🔧 कसे (या repo मध्ये)

exam/lab.py मधले CONTRACT एक dict आहे: consumer आणि provider ची नावे, request (GET /attendance/42) आणि अपेक्षित response (status 200, int type चे days_present आणि days_total असलेली body). verify_contract(contract, provider) request path देऊन provider ला बोलवते आणि अडचणींची यादी परत देते: चुकीचा status, हरवलेले field, किंवा चुकीच्या type चे field. रिकामी यादी म्हणजे provider contract पाळतो. जास्तीच्या fields कडे मुद्दाम दुर्लक्ष केले जाते.

🧪 करून पाहा

python3 exam/demo.py contract
python3 - <<'EOF'
from exam.lab import CONTRACT, verify_contract
from exam.grades import AttendanceClient
v5 = lambda p: (200, {"days_present": 172})
v6 = lambda p: (404, {"error": "moved"})
v7 = lambda p: (200, {"days_present": 172.0, "days_total": 200})
for name, prov in (("v5 drops days_total", v5), ("v6 moved the path", v6), ("v7 sends a float", v7)):
    print(f"{name:<20} → {verify_contract(CONTRACT, prov)}")
try: AttendanceClient(v5).attendance_percent("42")
except KeyError as e: print("without the contract, production sees: KeyError", e)
print("contract request:", CONTRACT["request"])
EOF

✅ तपासा — तुम्हाला काय दिसायला हवे

contract छापते:

   provider v1 as today                  → ✅ honours the contract
   provider v2 adds 'late_days'          → ✅ honours the contract
   provider v3 renames to 'present'      → ❌ missing field 'days_present'
   provider v4 sends days_total as text  → ❌ 'days_total' is str, expected int

तुमचा snippet छापतो:

v5 drops days_total  → ["missing field 'days_total'"]
v6 moved the path    → ['status 404, expected 200', "missing field 'days_present'", "missing field 'days_total'"]
v7 sends a float     → ["'days_present' is float, expected int"]
without the contract, production sees: KeyError 'days_total'
contract request: {'method': 'GET', 'path': '/attendance/42'}

🏁 तुम्ही आत्ताच काय सिद्ध केले

प्रत्येक मोडणाऱ्या बदलाचे नेमके नाव सांगितले गेले — कोणते field, कोणता type — consumer अजिबात न चालवता. Contract नसता तर v5 production पर्यंत पोहोचला असता आणि report-card code मध्ये KeyError म्हणून fail झाला असता, तो कारणीभूत बदलापासून खूप दूर. आणि v7 हा कडकपणाचा धडा आहे: AttendanceClient 172.0 अगदी व्यवस्थित हाताळू शकला असता. जर एखादा contract consumer ला पर्वा नसलेले बदल नाकारत असेल, तर teams त्याकडे दुर्लक्ष करू लागतात; तुम्हाला लागते तेवढेच पक्के करा, जास्त नाही.

⚠️ नेहमीच्या चुका

consumer जे वापरतो त्याऐवजी provider चे संपूर्ण response copy करणारा contract
type पुरेसा असताना नेमक्या किमती ("एक integer" ऐवजी "172")
provider team ने लिहिलेले contracts — मग ते गरजा नव्हे, provider चे वर्णन करतात
contracts फक्त consumer च्या build मध्ये तपासणे, जिथे provider चा बदल कधीच चालत नाही
contract tests ना provider च्या business logic च्या functional tests सारखे वागवणे

🏭 प्रत्यक्ष वापरात

खऱ्या project वर — consumer च्या tests लिहितात तशी एक pact file (Pact specification v3). Matching rules "नेमके 172" ऐवजी "कोणताही integer" सांगतात:

{
  "consumer": {"name": "report-cards"},
  "provider": {"name": "attendance"},
  "interactions": [{
    "description": "attendance for pupil 42",
    "providerStates": [{"name": "pupil 42 exists"}],
    "request": {"method": "GET", "path": "/attendance/42"},
    "response": {
      "status": 200,
      "body": {"days_present": 172, "days_total": 200},
      "matchingRules": {"body": {
        "$.days_present": {"matchers": [{"match": "integer"}]},
        "$.days_total":   {"matchers": [{"match": "integer"}]}
      }}
    }
  }],
  "metadata": {"pactSpecification": {"version": "3.0.0"}}
}

Pact कडे Python, JavaScript, Java, Go, .NET आणि इतर भाषांसाठी libraries आहेत. Pacts सहसा Pact Broker (किंवा PactFlow) मधून share केले जातात, जो "हे version deploy करणे सुरक्षित आहे का?" याचेही उत्तर देतो:

pact-broker can-i-deploy --pacticipant attendance --version 2.3.0 --to-environment production

इतर पद्धती: Spring Cloud Contract (JVM), आणि OpenAPI वर आधारित checks जसे Schemathesis किंवा Dredd, जिथे shared schema contract ची भूमिका बजावते.

🏭 Production मध्ये हे का महत्त्वाचे: तुमची service ज्या ज्या API ना call करते त्यांची यादी करा. प्रत्येकासाठी विचारा "त्यांनी उद्या एखाद्या field चे नाव बदलले, तर कोणता build लाल होईल?" उत्तर "आमचा, production मध्ये" असेल, तर तुम्हाला contract हवा.

⏭️ पुढे

Unit, integration, contract — आणि सर्वात वर, सगळ्यात हळू आणि सगळ्यात पूर्ण test: end-to-end. Suite मध्ये प्रत्येक प्रकारच्या किती असाव्यात? Pyramid आणि trophy.

git checkout lesson-08-e2e-pyramid

🤝 Lesson 07 — Contract tests: consumer expectations vs provider response

📍 You are here: Lesson 07 of 12 · Previous: lesson-06-integration · Next: lesson-08-e2e-pyramid

📦 What's in this branch

Lessons 01–06, plus contract tests: the report-card code (the consumer) writes down exactly what it needs from the attendance service (the provider), and the provider checks every release against that list before it ships. CONTRACT and verify_contract() in exam/lab.py; contract() in exam/demo.py.

🧒 Explain like I'm 5

Katrina's report cards need two numbers from the attendance office: days present and days total. She writes them on a card and pins it on the attendance office wall: 🤝

"When I ask for pupil 42, I need back: days_present (a whole number) and days_total (a whole number)."

That card is the contract.

Before the attendance office changes its form, it checks the form against Katrina's card.

v2 adds a new box, "late days". Katrina never asked for it, so she does not mind. ✅
v3 renames "days_present" to "present". Katrina's code would look for "days_present" and crash. The card catches it before the new form goes out. ❌
v4 writes "200" as words instead of a number. Caught. ❌

Nobody had to run both offices together. Each side checked itself against the same card.

🗺️ Diagram

flowchart LR
    c["📇 consumer: report cards<br/>needs days_present:int, days_total:int"] -->|"writes the contract"| k["🤝 contract<br/>GET /attendance/42 → 200"]
    k -->|"replayed in the provider's CI"| p["🏢 provider: attendance"]
    p --> v1["v1 as today ✅"]
    p --> v2["v2 adds late_days ✅"]
    p --> v3["v3 renames to present ❌<br/>missing field days_present"]
    p --> v4["v4 days_total as text ❌<br/>str, expected int"]

🗺️ Drawn version + a lab: https://school-edh.pages.dev/testing/lesson-diagrams.html#l07

❓ What

Consumer / provider — the side that calls an API and the side that serves it.
Contract — the requests a consumer makes and the parts of the responses it relies on: status, fields, types. Not the whole API — only what this consumer uses.
Consumer-driven contract testing — consumers publish their contracts; the provider's build replays each one against the real provider code and fails if any consumer would break. Pact is the best-known tool; its contract files are called pacts.
Provider verification — the provider side of the check: start the provider (with test data set up for each case — Pact calls these provider states), send each recorded request, compare the response.
Tolerant reader — the consumer ignores fields it did not ask for. That is why adding a field (v2) is safe and renaming one (v3) is not.
Matching by type — a contract should pin what the consumer truly needs: often "an integer", not "exactly 172". Too strict a contract blocks harmless changes.
Schema-first alternative — both sides test against one shared schema (OpenAPI, JSON Schema, protobuf). Tools such as Schemathesis generate requests from an OpenAPI file.

🤔 Why

Because lesson 05's stubs are claims about another team's service, and end-to-end tests that run both services together are slow and flaky (lesson 08). A contract turns the claim into a file both teams test against: the consumer's unit tests use it as their stub, and the provider's build proves it still answers that way. The breaking change is caught in the provider's pipeline, before deployment, by the team that made it.

🔧 How (in this repo)

CONTRACT in exam/lab.py is a dict: the consumer and provider names, the request (GET /attendance/42) and the expected response (status 200, a body with days_present and days_total of type int). verify_contract(contract, provider) calls the provider with the request path and returns a list of problems: a wrong status, a missing field, or a field of the wrong type. An empty list means the provider honours the contract. Extra fields are ignored on purpose.

🧪 Try it

python3 exam/demo.py contract
python3 - <<'EOF'
from exam.lab import CONTRACT, verify_contract
from exam.grades import AttendanceClient
v5 = lambda p: (200, {"days_present": 172})
v6 = lambda p: (404, {"error": "moved"})
v7 = lambda p: (200, {"days_present": 172.0, "days_total": 200})
for name, prov in (("v5 drops days_total", v5), ("v6 moved the path", v6), ("v7 sends a float", v7)):
    print(f"{name:<20} → {verify_contract(CONTRACT, prov)}")
try: AttendanceClient(v5).attendance_percent("42")
except KeyError as e: print("without the contract, production sees: KeyError", e)
print("contract request:", CONTRACT["request"])
EOF

✅ Verify — what you should see

contract prints:

   provider v1 as today                  → ✅ honours the contract
   provider v2 adds 'late_days'          → ✅ honours the contract
   provider v3 renames to 'present'      → ❌ missing field 'days_present'
   provider v4 sends days_total as text  → ❌ 'days_total' is str, expected int

Your snippet prints:

v5 drops days_total  → ["missing field 'days_total'"]
v6 moved the path    → ['status 404, expected 200', "missing field 'days_present'", "missing field 'days_total'"]
v7 sends a float     → ["'days_present' is float, expected int"]
without the contract, production sees: KeyError 'days_total'
contract request: {'method': 'GET', 'path': '/attendance/42'}

🏁 What you just proved

Every breaking change was named precisely — which field, which type — without running the consumer at all. Without the contract, v5 would have reached production and failed as a KeyError inside the report-card code, far from the change that caused it. And v7 is a lesson in strictness: AttendanceClient would cope with 172.0 perfectly well. If a contract refuses changes the consumer does not care about, teams start ignoring it; pin what you need, no more.

⚠️ Common mistakes

a contract that copies the provider's whole response instead of what the consumer uses
exact values where a type would do ("172" instead of "an integer")
contracts written by the provider team — then they describe the provider, not the needs
verifying contracts only in the consumer's build, where the provider's change never runs
treating contract tests as functional tests of the provider's business logic

🏭 In production

On a real project — a pact file (Pact specification v3) as the consumer's tests write it. Matching rules say "any integer" instead of "exactly 172":

{
  "consumer": {"name": "report-cards"},
  "provider": {"name": "attendance"},
  "interactions": [{
    "description": "attendance for pupil 42",
    "providerStates": [{"name": "pupil 42 exists"}],
    "request": {"method": "GET", "path": "/attendance/42"},
    "response": {
      "status": 200,
      "body": {"days_present": 172, "days_total": 200},
      "matchingRules": {"body": {
        "$.days_present": {"matchers": [{"match": "integer"}]},
        "$.days_total":   {"matchers": [{"match": "integer"}]}
      }}
    }
  }],
  "metadata": {"pactSpecification": {"version": "3.0.0"}}
}

Pact has libraries for Python, JavaScript, Java, Go, .NET and more. Pacts are usually shared through a Pact Broker (or PactFlow), which also answers "is it safe to deploy this version?":

pact-broker can-i-deploy --pacticipant attendance --version 2.3.0 --to-environment production

Other approaches: Spring Cloud Contract (JVM), and OpenAPI-based checks such as Schemathesis or Dredd, where the shared schema plays the part of the contract.

🏭 Why this matters in production: list every API your service calls. For each one, ask "if they renamed a field tomorrow, which build would go red?" If the answer is "ours, in production", you need a contract.

⏭️ Next

Unit, integration, contract — and at the top, the slowest and most complete test of all: end-to-end. How many of each should a suite have? The pyramid and the trophy.

git checkout lesson-08-e2e-pyramid

← Previousintegration Next →e2e pyramid

This page is the lesson's README from the lesson-07-contract-tests branch, shown here so the whole School stays on one site. Code files open on GitHub at the same branch.