সরাসরি পর্বে যান
পর্ব ৩২ · ৮২-এর মধ্যে · মডিউল ৫

Contract testing — consumer-driven contract আর Pact

Contract Testing — Consumer-Driven Contracts and Pact

Taught in Bangla, this lesson shows why integration tests across two teams' services are slow and brittle and how consumer-driven contracts fill the gap, with matching rules, tolerant readers, brokers and can-i-deploy. A real pact-python 4.2.0 run records three interactions, then verifies them against the real Bazarghar API with provider states; renaming pricing.total turns verification red. It also shows what contracts miss, such as a wrong delivery charge, next to schema, functional and E2E tests.

এই পর্বে যা শিখবেন

  • Service-এর মধ্যে integration test কেন ধীর আর ভঙ্গুর হয়, আর contract test কোন ফাঁক ভরায়
  • Consumer-driven contract, matching rule (type, regex, each-like) আর tolerant reader-এর ধারণা
  • pact-python দিয়ে consumer test লিখে pact ফাইল বানানো, আর provider state দিয়ে provider verification চালানো
  • Broker, deployment matrix আর can-i-deploy দিয়ে release-এর সিদ্ধান্ত নেওয়া
  • Contract test, schema test, functional API test আর E2E test-এর কাজ আলাদা করে চেনা

১ · দুই দল, এক API — integration test কেন যথেষ্ট নয়

পাড়ার দর্জির কাছে প্রথমবার গেলে তিনি একটি খাতায় আপনার মাপ লিখে রাখেন: কাঁধ, হাতা, বুক, লম্বা। পরের ঈদে নতুন নকশার পাঞ্জাবি বানালেও তিনি সেই খাতা দেখে কাটেন। নকশা বদলাক, কাপড় বদলাক; খাতার মাপ মানলে পাঞ্জাবি গায়ে লাগবে। মাপের খাতাটি একটি চুক্তি, আর সেটি লিখেছেন যিনি পরবেন, অর্থাৎ ব্যবহারকারী।

বাজারঘর এখন আর একটি মাত্র app নয়। ওয়েবসাইটের পাশাপাশি আছে একটি mobile app, যেটি আরেকটি দল বানায়, আর একটি courier দলের service, যারা delivery-র জন্য অর্ডারের তথ্য পড়ে। তিনটিই কথা বলে একই বাজারঘর API-র সাথে (এই কোর্সের shared app, JSON API সহ)। API-কে বলা হয় provider, আর যারা তাকে ডাকে তারা consumer.

ধরুন API দলের একজন developer পরিচ্ছন্নতার জন্য অর্ডারের pricing.total-এর নাম বদলে grand_total করলেন। API দলের নিজের সব test তিনি একসাথে ঠিক করে নিলেন, build সবুজ। পরদিন mobile app-এ সব অর্ডারের মোট দাম ফাঁকা। কোথায় ফাঁক ছিল?

  • Mobile দলের unit test: তারা API-কে mock করেছিল (পর্ব ২৪)। Mock এখনো পুরোনো total ফেরত দেয়, তাই সব সবুজ। এটি সেই mock drift.
  • API দলের test: নিজের কোড নিজের প্রত্যাশায় যাচাই করে। কোন consumer কোন field পড়ে, তা তারা জানে না।
  • দুটি একসাথে চালানো integration বা end-to-end test: এটি ধরতে পারত, কিন্তু তার জন্য দরকার সব service-এর ঠিক version একসাথে চালু একটি পরিবেশ, সঠিক test data, আর ধৈর্য। Service যত বাড়ে, এমন পরিবেশ তত ধীর, ব্যয়বহুল আর অস্থির (flaky) হয়; একটি ব্যর্থতা কার দোষে, তা খুঁজতেই দিন যায়। Integration test-এর কৌশল আর test database নিয়ে বিস্তারিত পর্ব ২৮-এ।

Contract test এই তিনের মাঝখানে বসে। এটি দুই পক্ষকে একসাথে চালায় না; বরং দুই পক্ষকে আলাদা আলাদাভাবে একই লিখিত চুক্তির বিরুদ্ধে যাচাই করে। Consumer-এর দিকে চুক্তি নিশ্চিত করে mock আর আসল প্রত্যাশা একই; provider-এর দিকে নিশ্চিত করে আসল API সেই চুক্তি মানে। দুটি test-ই দ্রুত, আর দুটিই নিজের দলের build-এ চলে।

আগে কোথায় দেখেছেন। সফটওয়্যার ইঞ্জিনিয়ারিং ও Git কোর্সের পর্ব ৫১-এ test pyramid-এর ভেতরে contract test-এর পরিচয় আর একটি খেলনা checker আছে; System Design কোর্সের পর্ব ৪৭-এ microservice-এর দিক থেকে আলোচনা। এখানে আমরা যাব হাতে-কলমে: matching rule-এর খুঁটিনাটি, সত্যিকারের Pact tool, provider state, আর release-এর সিদ্ধান্ত।

বাজারঘরের নিয়ম (এই পর্বে)

Order API: GET /api/orders/{id} login করা গ্রাহকের নিজের অর্ডার দেয়; অন্যের বা অস্তিত্বহীন অর্ডারে 404 আর {"detail": {"code": "order_not_found", …}}. Seed data-য় অর্ডার ৬ সুমির, অবস্থা placed, মোট ১০২১ টাকা (১০০১ + ১২০ delivery − ১০০ ছাড়)। Delivery: ঢাকায় ৬০ টাকা, ছাড়ের আগের অঙ্ক ২০০০ বা বেশি হলে ফ্রি; বাইরে ১২০, Plus সদস্যের ৬০. Coupon: ১০০০ টাকার বেশি হলে ১০%, সর্বোচ্চ ৩০০, পূর্ণ টাকায়।

২ · Contract কী, আর কলম কার হাতে

API-র চুক্তি (API contract) সবসময় থাকে, লেখা হোক বা না হোক: কোন ঠিকানায় কোন method, কোন header, উত্তরে কোন field কোন ধরনের। প্রশ্ন হলো কে লেখে আর কীভাবে যাচাই হয়। দুটি প্রধান ধারা:

Provider-driven

Provider একটি নথি প্রকাশ করে, সাধারণত OpenAPI: সব endpoint আর সব field. Consumer-রা মানিয়ে চলে। Public API-তে, যেখানে consumer অচেনা, এটিই স্বাভাবিক।

Consumer-driven

প্রতিটি consumer লেখে নিজে কী পাঠায় আর কী পড়ে। Provider সব consumer-এর চুক্তির যোগফল মানতে বাধ্য, তার বাইরে স্বাধীন। পরিচিত consumer আর আলাদা দলের service-এ এটি সবচেয়ে কাজের।

Consumer-driven contract-এর ধারণাটি Ian Robinson-এর ২০০৬ সালের একটি প্রবন্ধের সাথে যুক্ত। মূল যুক্তি: provider জানে না কোন field কে পড়ে, তাই কোনো field সরানোর সাহস পায় না, ফলে API শুধু বাড়তেই থাকে। Consumer-রা নিজেদের ব্যবহার লিখে দিলে provider জানে ঠিক কোন field “কারও দরকার নেই”, আর কোনটি বদলালে কার সাথে আগে কথা বলতে হবে।

চুক্তিতে কী থাকে, কী থাকে না

বাজারঘরের mobile app অর্ডারের পাতায় দেখায় অবস্থা, মোট দাম, আর “এখন পরিশোধ করুন” বোতাম (যদি pay করা যায়)। তাই তার চুক্তিতে শুধু চারটি field: id, status, pricing.total, allowed_actions. অর্ডারের ঠিকানা, ফোন নম্বর, history: app এগুলো পড়ে না, তাই চুক্তিতে নেই, আর provider চাইলে এগুলো বদলাতে পারে। এটিই tolerant reader নীতি: যা লাগে শুধু তা পড়ুন, অচেনা নতুন field উপেক্ষা করুন।

আর মানগুলো? মোট দাম ১০২১ হবে কি না, সেটি ব্যবসার নিয়ম, চুক্তির নয়। চুক্তি বলে “total একটি পূর্ণসংখ্যা”, আর উদাহরণ হিসেবে ১০২১ রাখে। এই “কতটা কড়া” নিয়মগুলোর নাম matching rule:

Ruleমানেবাজারঘরে
Exact (rule ছাড়া)মান হুবহু মিলতে হবে"code": "order_not_found"; app এই code দেখেই বার্তা বাছে
Type / integerশুধু ধরন মিলবে, মান যেকোনোtotal যেকোনো পূর্ণসংখ্যা
Regexলেখা একটি ধাঁচে মিলবেstatus সাতটি বৈধ অবস্থার একটি
Each-likeঅন্তত একটি উপাদানের তালিকা, প্রতিটি উদাহরণের ধরনেরallowed_actions: string-এর তালিকা

নিচের block-এ একটি ছোট consumer-contract checker: চারটি rule, আর provider-এর পাঁচটি কাল্পনিক version-এর রেকর্ড করা উত্তর (network নেই, উত্তরগুলো সরাসরি dict). কোনটি mobile app-কে ভাঙবে? “চালান” চাপুন; প্রথমবার ব্রাউজারে Pyodide নামতে কয়েক সেকেন্ড লাগে।

import re
STATUS = r"placed|paid|packed|shipped|delivered|cancelled|refunded"
RULES = {"$.id": ("integer",), "$.status": ("regex", STATUS),
         "$.pricing.total": ("integer",), "$.allowed_actions": ("each_like", str)}
def get(doc, path):
    for key in path[2:].split("."):
        if not isinstance(doc, dict) or key not in doc:
            raise KeyError(key)
        doc = doc[key]
    return doc
def check(actual):
    problems = []
    for path, (kind, *arg) in RULES.items():
        try:
            v = get(actual, path)
        except KeyError as e:
            problems.append(f"{path}: missing key {e}"); continue
        ok = {"integer": lambda: type(v) is int,
              "regex": lambda: isinstance(v, str) and re.fullmatch(arg[0], v),
              "each_like": lambda: isinstance(v, list) and len(v) >= 1
                           and all(isinstance(x, arg[0]) for x in v)}[kind]()
        if not ok:
            problems.append(f"{path}: {v!r} fails {kind}")
    return problems
base = {"id": 6, "status": "placed", "district": "Chattogram", "allowed_actions": ["pay", "cancel"],
        "pricing": {"subtotal": 1001, "discount": 100, "delivery": 120, "total": 1021}}
versions = {"v1.0 (today)": base,
    "v1.1 total renamed": {**base, "pricing": {"subtotal": 1001, "grand_total": 1021}},
    "v1.2 new field": {**base, "eta_min": 45, "status": "paid", "allowed_actions": ["pack"]},
    "v1.3 total as text": {**base, "pricing": {"total": "1021"}},
    "v1.4 status renamed": {**base, "status": "PLACED", "allowed_actions": []}}
for name, response in versions.items():
    problems = check(response)
    print(f"{name:20} {'BREAKS' if problems else 'OK'}", *problems, sep="\n    ")

আসল আউটপুট (ব্রাউজারের Python):

v1.0 (today)         OK
v1.1 total renamed   BREAKS
    $.pricing.total: missing key 'total'
v1.2 new field       OK
v1.3 total as text   BREAKS
    $.pricing.total: '1021' fails integer
v1.4 status renamed  BREAKS
    $.status: 'PLACED' fails regex
    $.allowed_actions: [] fails each_like

v1.2-এ নতুন field eta_min এসেছে, অবস্থা আর মোট দাম বদলেছে, তবু OK: চুক্তি নতুন field-এ আপত্তি করে না, আর মান নয়, শুধু ধরন দেখে। v1.1-এ নাম বদল (সেই সকালের ঘটনা), v1.3-এ সংখ্যা হয়ে গেছে লেখা "1021" (JSON-এর পরিচিত data bug), v1.4-এ বড় হাতের PLACED: তিনটিই app ভাঙে। v1.4-এর খালি তালিকাটিও ধরা পড়েছে, কারণ each-like অন্তত একটি উপাদান চায়। আসল Pact-এ এই ধরনের অনেক rule আছে (তারিখ, decimal, null-যোগ্য মান, তালিকায় অন্তত একটি নির্দিষ্ট উপাদান…), কিন্তু মূল কাজ ঠিক এই চারটির মতো।

দুই দিকের ভুল। সব মান exact রাখলে চুক্তি অতি-কড়া হয়: provider-এর test data-য় সুমির অর্ডারের মোট ১০২১-এর বদলে ১০২০ হলেই verification লাল, অথচ app ভাঙেনি। আবার সব কিছু “যেকোনো ধরন” রাখলে চুক্তি অতি-ঢিলা: status-এ “PLACED” এলেও কেউ টের পাবে না। নিয়ম: app যে মান দেখে সিদ্ধান্ত নেয় (error code, অবস্থার নাম), তা exact বা regex; যা শুধু দেখায় (দাম, নাম), তা type.

৩ · Pact-এর চক্র — consumer test থেকে deploy পর্যন্ত

Pact consumer-driven contract testing-এর সবচেয়ে পরিচিত open-source tool. ২০১৩ সালের দিকে Ruby-তে শুরু বলে জানা যায়; এখন JVM, JavaScript, .NET, Go, Python সহ অনেক ভাষায় আছে, আর অনেক ভাষার library ভেতরে Rust-এ লেখা একটি অভিন্ন core ব্যবহার করে। চুক্তির ফাইলের গঠন একটি প্রকাশিত মান (Pact specification, বর্তমানে V4) অনুসরণ করে, তাই Python-এর consumer আর Java-র provider একই ফাইল পড়তে পারে।

Pact-এর পূর্ণ চক্র

Consumer side writes the contract, the broker stores it, the provider side verifies it, can-i-deploy decides

Pact-এর চক্র: consumer test, mock server, pact ফাইল, broker, provider verification, can-i-deploy ১ Consumer test mobile দল, client কোড চালায় ২ Mock server (Pact) request মেলায়, উদাহরণ উত্তর দেয় ৩ Pact ফাইল (JSON) লিখিত, যন্ত্রে পড়া যায় এমন চুক্তি ৪ Broker চুক্তি, version আর ফলের খাতা ৫ Provider verification state বসিয়ে আসল API-তে replay ৬ can-i-deploy হ্যাঁ হলে তবেই deploy
ছবি ৩২.১ — নীল তিনটি ধাপ consumer দলের build-এ, সবুজ দুটি provider দলের build-এ। মাঝখানের broker দুই দলকে একই খাতা দেখায়; কোনো ধাপেই দুটি service একসাথে চালাতে হয় না।

প্রথম তিনটি ধাপ নিচের stepper-এ, mobile app-এর একটি test ধরে। লক্ষ করুন, consumer test একই সাথে দুটি কাজ করে: app-এর client কোড পরীক্ষা করে, আর চুক্তি লেখে।

  1. প্রত্যাশাgiven / upon_receivingtest লেখা
  2. Mock serverpact.serve()localhost-এ
  3. Client চলেorder_summary(6)আসল কোড
  4. Pact ফাইলpacts/*.jsonশুধু সবুজ হলে
test_consumer_pact.pyapp কী পাঠাবে, কী পড়বে
GET /api/orders/6
Authorization: Bearer contract-token-sumi
given: "order 6 is placed and belongs to sumi"
→ 200  id: int(6)  status: regex("placed")
       pricing.total: int(1021)
       allowed_actions: each_like("pay")
Mock serverএকটি র‍্যান্ডম port-এ
listening on http://localhost:7437
expects 1 interaction:
  GET /api/orders/6  (+ Authorization)
any other request → 500 + mismatch
client.order_summary(6)request মিলল
request matched ✓
reply: {"id": 6, "status": "placed",
        "pricing": {"total": 1021},
        "allowed_actions": ["pay"]}
OrderSummary(6, 'placed', 1021, can_pay=True)
with-block শেষmock-এর হিসাব
expected interactions received: 1 / 1
mismatches: 0
test assert: ('placed', 1021, True) ✓
→ PASSED
bazarghar-mobile-bazarghar-api.jsonmatching rule সহ
"providerStates": [{"name": "order 6 is placed…"}],
"request": {"method": "GET", "path": "/api/orders/6"},
"matchingRules": {"body": {
  "$.id": integer, "$.pricing.total": integer,
  "$.status": regex ^(placed|paid|…)$,
  "$.allowed_actions": type }}
  1. প্রত্যাশা লেখা। Mobile দল test-এ লেখে: এই অবস্থায় (given), এই request পাঠালে (upon receiving), এই উত্তর চাই। উত্তরের প্রতিটি মান একটি matcher-এ মোড়া: উদাহরণ মান আর rule দুটিই আছে।
  2. Mock server চালু। pact.serve() localhost-এ একটি আসল HTTP server খোলে। এটি শুধু ঘোষিত interaction চেনে; অন্য যেকোনো request-এ 500 আর mismatch-এর বিবরণ দেয়।
  3. আসল client কোড চলে। App-এর order_summary(6) সত্যিকারের HTTP request পাঠায়, mock-এর উদাহরণ উত্তর পায়, আর OrderSummary বানায়। Client-এর JSON পড়ার কোড এখানেই পরীক্ষিত হলো।
  4. Mock-এর হিসাব। with block শেষ হলে Pact দেখে প্রত্যাশিত সব request এসেছে কি না, আর কোনো mismatch হয়েছে কি না। দুটিই ঠিক, তাই test-এর নিজের assert চলে: PASSED.
  5. চুক্তি লেখা। Fixture-এর শেষে write_file interaction-টি JSON ফাইলে যোগ করে: provider state, request, উদাহরণ উত্তর আর matching rule. এই ফাইলটিই provider দলের কাছে যাবে; mock আর চুক্তি এখন একই উৎস থেকে তৈরি, তাই mock drift-এর সুযোগ নেই।

এবার একই ধারণার একটি ক্ষুদ্র রূপ নিজে চালিয়ে দেখুন, pytest দিয়ে, এই পাতাতেই (Pyodide-এ pytest আছে; ব্যবহার পর্ব ২১-এ)। MockProvider Pact-এর mock server-এর একটি খুদে স্ট্যান্ড-ইন: শুধু একটি interaction চেনে। Client-এর quote function-এ একটি bug বসানো আছে।

import json, os, sys, pytest
os.makedirs("/tmp/p32", exist_ok=True); os.chdir("/tmp/p32")
sys.path.insert(0, os.getcwd()); sys.modules.pop("test_quote32", None)
open("test_quote32.py", "w").write('''
import json, pytest
class MockProvider:                  # a tiny stand-in for Pact's mock server
    def __init__(self, interaction):
        self.i, self.received = interaction, []
    def send(self, method, path, query):        # the client's "network"
        req = {"method": method, "path": path, "query": query}
        self.received.append(req)
        if req != self.i["request"]:
            return 500, {"error": "mismatch", "got": req}
        return self.i["status"], self.i["body"]
def quote(send, subtotal, district):             # consumer code under test
    status, body = send("GET", "/api/pricing/quote",
                        {"subtotal": str(subtotal), "district": district.lower()})
    assert status == 200, body
    return body["delivery"], body["total"]
def test_quote_2000_dhaka():
    i = {"request": {"method": "GET", "path": "/api/pricing/quote",
                     "query": {"subtotal": "2000", "district": "Dhaka"}},
         "status": 200, "body": {"delivery": 0, "total": 1800}}
    mock = MockProvider(i)
    assert quote(mock.send, 2000, "Dhaka") == (0, 1800)
    json.dump({"consumer": "bazarghar-mobile", "provider": "bazarghar-api",
               "interactions": [i]}, open("pact32.json", "w"))   # only if green
''')
if os.path.exists("pact32.json"): os.remove("pact32.json")
pytest.main(["-q", "--no-header", "--tb=line", "-p", "no:cacheprovider", "test_quote32.py"])
print("pact file written:", os.path.exists("pact32.json"))

আসল আউটপুট:

F                                                                        [100%]
=================================== FAILURES ===================================
E   AssertionError: {'error': 'mismatch', 'got': {'method': 'GET', 'path': '/api/pricing/quote', 'query': {'district': 'dhaka', 'subtotal': '2000'}}}
    assert 500 == 200
/tmp/p32/test_quote32.py:15: AssertionError: {'error': 'mismatch', 'got': {'method': 'GET', 'path': '/api/pricing/quote', 'query': {'district': 'dhaka', 'subtotal': '2000'}}}
=========================== short test summary info ============================
FAILED test_quote32.py::test_quote_2000_dhaka - AssertionError: {'error': 'mi...
1 failed in 0.01s
pact file written: False

Client জেলার নাম ছোট হাতের অক্ষরে পাঠিয়েছে ('district': 'dhaka'), চুক্তিতে আছে Dhaka. Mock তাই 500 আর mismatch দিল, client-এর assert status == 200 ভাঙল (লাইন ১৫), test লাল, আর pact ফাইল লেখা হলো না (False). এটি গুরুত্বপূর্ণ নিয়ম: ব্যর্থ consumer test থেকে কখনো চুক্তি প্রকাশ হয় না। বাস্তবেও বাজারঘর API district=dhaka পেলে 422 invalid_district দেয় (ডেস্কটপে চালিয়ে দেখা), তাই bug-টি আসল। নিজে চেষ্টা করুন: district.lower()-কে district করে আবার চালান; test পাস করবে আর শেষ লাইন হবে True.

৪ · ডেস্কটপে সত্যিকারের run — pact-python দিয়ে consumer test

এবার আসল tool. নিচের সবকিছু এই কোর্সের লেখার সময় একটি সাধারণ Windows ডেস্কটপে চালানো: Python 3.12.13, pact-python 4.2.0 (MIT লাইসেন্স; ভেতরে Pact-এর Rust core, pact-python-ffi 0.5.12.1, এটিও MIT), pytest 9.2.0 আর httpx 0.28.1, uv দিয়ে বানানো ছোট প্রকল্পে। Path নিরপেক্ষ করা, লম্বা অংশ “…” দিয়ে ছাঁটা।

cd ~/bazarghar-qa
uv init --vcs none --author-from none
uv add pact-python pytest httpx

Consumer হলো mobile app-এর ছোট API client. তার order_summary চারটি field পড়ে, quote দুটি:

class BazarGharClient:
    def __init__(self, base_url, token=None):
        self.http = httpx.Client(base_url=base_url, timeout=5)
        self.token = token

    def order_summary(self, order_id):
        r = self.http.get(f"/api/orders/{order_id}",
                          headers={"Authorization": f"Bearer {self.token}"})
        if r.status_code == 404:
            raise OrderNotFound(r.json()["detail"]["code"])
        r.raise_for_status()
        d = r.json()
        return OrderSummary(d["id"], d["status"], d["pricing"]["total"],
                            "pay" in d["allowed_actions"])

    def quote(self, subtotal, district):
        r = self.http.get("/api/pricing/quote",
                          params={"subtotal": subtotal, "district": district})
        r.raise_for_status()
        d = r.json()
        return {"delivery": d["delivery"], "total": d["total"]}

Consumer test-এ তিনটি interaction: সুমির placed অর্ডার, অস্তিত্বহীন অর্ডার ৯৯৯ (404), আর ২০০০ টাকার ঢাকার quote. প্রথম দুটি এখানে দেখানো হলো; তৃতীয়টি একই ধাঁচে with_query_parameter দিয়ে লেখা।

from pathlib import Path
import pytest
from pact import Pact, match
from bazarghar_mobile.client import BazarGharClient, OrderNotFound

TOKEN = "contract-token-sumi"
STATUS = r"^(placed|paid|packed|shipped|delivered|cancelled|refunded)$"
PACTS = Path(__file__).parents[1] / "pacts"

@pytest.fixture
def pact():
    p = Pact("bazarghar-mobile", "bazarghar-api")
    yield p
    p.write_file(PACTS)          # merges each test into one pact file

def test_order_summary(pact):
    (pact.upon_receiving("a request for sumi's placed order")
        .given("order 6 is placed and belongs to sumi")
        .with_request("GET", "/api/orders/6")
        .with_header("Authorization", f"Bearer {TOKEN}")
        .will_respond_with(200)
        .with_body({
            "id": match.int(6),
            "status": match.regex("placed", regex=STATUS),
            "pricing": {"total": match.int(1021)},
            "allowed_actions": match.each_like("pay"),
        }, content_type="application/json"))
    with pact.serve() as srv:
        s = BazarGharClient(str(srv.url), TOKEN).order_summary(6)
    assert (s.status, s.total, s.can_pay) == ("placed", 1021, True)

def test_missing_order(pact):
    (pact.upon_receiving("a request for an order that does not exist")
        .given("sumi is logged in")
        .with_request("GET", "/api/orders/999")
        .with_header("Authorization", f"Bearer {TOKEN}")
        .will_respond_with(404)
        .with_body({"detail": {"code": "order_not_found",
                               "message": match.str("অর্ডারটি পাওয়া যায়নি")}},
                   content_type="application/json"))
    with pact.serve() as srv:
        with pytest.raises(OrderNotFound, match="order_not_found"):
            BazarGharClient(str(srv.url), TOKEN).order_summary(999)

Run (এখনো কোনো আসল server চলছে না; consumer test-এর provider শুধু Pact-এর mock):

$ PACT_DO_NOT_TRACK=true uv run pytest tests -v
============================= test session starts =============================
platform win32 -- Python 3.12.13, pytest-9.2.0, pluggy-1.7.0
rootdir: ~/bazarghar-qa
configfile: pyproject.toml
plugins: anyio-4.16.0, pact-python-4.2.0
collecting ... collected 3 items

tests/test_consumer_pact.py::test_order_summary PASSED                   [ 33%]
tests/test_consumer_pact.py::test_missing_order PASSED                   [ 66%]
tests/test_consumer_pact.py::test_delivery_quote PASSED                  [100%]

============================== 3 passed in 0.13s ==============================

তিনটি test-এ ০.১৩ সেকেন্ড; কোনো database, কোনো login, কোনো আসল server নেই। ফল হিসেবে pacts/bazarghar-mobile-bazarghar-api.json তৈরি হলো, যার প্রথম অংশ (ছাঁটা):

{
  "consumer": { "name": "bazarghar-mobile" },
  "interactions": [ …,
    {
      "description": "a request for sumi's placed order",
      "providerStates": [ { "name": "order 6 is placed and belongs to sumi" } ],
      "request": {
        "headers": { "Authorization": [ "Bearer contract-token-sumi" ] },
        "method": "GET", "path": "/api/orders/6"
      },
      "response": {
        "body": { "content": { "allowed_actions": [ "pay" ], "id": 6,
                               "pricing": { "total": 1021 }, "status": "placed" } … },
        "matchingRules": { "body": {
            "$.allowed_actions": { "matchers": [ { "match": "type" } ] … },
            "$.id": { "matchers": [ { "match": "integer" } ] … },
            "$.pricing.total": { "matchers": [ { "match": "integer" } ] … },
            "$.status": { "matchers": [ { "match": "regex",
                "regex": "^(placed|paid|packed|shipped|delivered|cancelled|refunded)$" } ] … } } },
        "status": 200
      },
      "type": "Synchronous/HTTP"
    } ],
  "metadata": { "pactRust": { "ffi": "0.5.12", "models": "1.3.16" },
                "pactSpecification": { "version": "4.0" } },
  "provider": { "name": "bazarghar-api" }
}

PACT_DO_NOT_TRACK=true কেন। প্রথম run-এ Pact নিজেই একটি সতর্কবার্তা ছাপল: এটি বেনামে ব্যবহারের পরিসংখ্যান (Pact version, operating system) পাঠায়, বন্ধ করতে এই environment variable লাগে। Test-এর পরিবেশে অজানা network ডাক রাখা ঠিক নয়, আর অনেক অফিসের CI-তে বাইরের network বন্ধ থাকে। তাই এই পর্বের সব run এই variable দিয়ে চালানো। যেকোনো নতুন tool-এর telemetry-র নিয়ম তার নথিতে দেখে নেওয়া tester-এর অভ্যাস হওয়া উচিত।

Consumer-এর দিকের ব্যর্থতা

§৩-এর ক্ষুদ্র রূপের সেই ভুলটি এবার আসল client-এ বসানো হলো (district.lower()), আর শুধু quote-এর test চালানো হলো:

$ PACT_DO_NOT_TRACK=true uv run pytest tests -q -k quote --tb=short
F                                                                        [100%]
================================== FAILURES ===================================
_____________________________ test_delivery_quote _____________________________
tests\test_consumer_pact.py:62: in test_delivery_quote
    q = BazarGharClient(str(srv.url)).quote(2000, "Dhaka")
…
E   httpx.HTTPStatusError: Server error '500 Internal Server Error' for url 'http://localhost:7437/api/pricing/quote?subtotal=2000&district=dhaka'
…
During handling of the above exception, another exception occurred:
tests\test_consumer_pact.py:61: in test_delivery_quote
    with pact.serve() as srv:
         ^^^^^^^^^^^^
.venv\Lib\site-packages\pact\pact.py:845: in __exit__
    raise MismatchesError(*self.mismatches)
E   pact.error.MismatchesError: Mismatches:
E     (1) Request mismatch: GET /api/pricing/quote
E       (1) Query mismatch: Expected query parameter 'district' with value 'Dhaka' but was 'dhaka'
=========================== short test summary info ===========================
FAILED tests/test_consumer_pact.py::test_delivery_quote - pact.error.Mismatch...
1 failed, 2 deselected in 0.15s

দুটি স্তরে খবর: প্রথমে client নিজেই 500 পেয়ে HTTPStatusError ছুড়েছে, তারপর with block বন্ধ হওয়ার সময় Pact কারণটি স্পষ্ট বলেছে: query parameter district-এ প্রত্যাশা 'Dhaka', এসেছে 'dhaka'. ভুলটি ধরা পড়ল consumer দলের নিজের build-এ, provider-এর কাছে পৌঁছানোর আগেই। ভুল ঠিক করে আবার চালালে তিনটিই পাস।

৫ · Provider verification আর provider state

চুক্তি এখন provider দলের হাতে। Provider verification-এ Pact-এর verifier ফাইলের প্রতিটি interaction নেয়, আসল চলমান API-তে request পাঠায় (replay), আর উত্তরটি matching rule দিয়ে মেলায়। কিন্তু একটি সমস্যা: চুক্তি বলে “অর্ডার ৬ placed আর সুমির”, আর request-এ আছে একটি নির্দিষ্ট token. Provider-এর database-এ যদি অর্ডার ৬ shipped হয়ে থাকে, বা token-টি অচেনা হয়?

সমাধান provider state: চুক্তির given(...) বাক্যগুলো। Provider দল প্রতিটি বাক্যের জন্য একটি ছোট setup function লেখে, আর verifier প্রতিটি interaction-এর আগে সেটি ডাকে। এটি আসলে পর্ব ২৩-এর fixture-এর ধারণা, শুধু নামটি দুই দলের ভাগ করা ভাষা। বাজারঘর app-এর test mode-এ POST /api/test/reset আছে, যা seed data ফেরত আনে; তার পরে state handler সুমির জন্য চুক্তির token-টি provider-এর নিজের test database-এ বসায়।

import os, sqlite3
from datetime import datetime
from pathlib import Path
import httpx
from pact import Verifier

BASE = os.environ.get("PROVIDER_URL", "http://127.0.0.1:8785")
DB = os.environ["BAZARGHAR_DB"]          # the provider's own test database
PACTS = Path(__file__).parents[1] / "pacts"

def reset_and_login_sumi():
    httpx.post(f"{BASE}/api/test/reset").raise_for_status()
    with sqlite3.connect(DB) as conn:     # a known token for user 4 (sumi)
        conn.execute("INSERT INTO sessions VALUES (?, ?, ?)",
                     ("contract-token-sumi", 4, datetime.now().isoformat()))

STATES = {
    "order 6 is placed and belongs to sumi": reset_and_login_sumi,
    "sumi is logged in": reset_and_login_sumi,
}

def test_bazarghar_api_honours_the_mobile_pact():
    verifier = (
        Verifier("bazarghar-api", host="127.0.0.1")
        .add_transport(url=BASE)
        .add_source(PACTS)
        .state_handler(STATES, teardown=False)
        .set_coloured_output(enabled=False)
    )
    verifier.verify()                    # raises if any interaction fails

Provider হিসেবে বাজারঘর app নিজের lab-এর কপি থেকে চালু করা হলো, নিজের database ফাইল আর port 8785-এ, শুধু 127.0.0.1-এ। তারপর verification:

$ BAZARGHAR_TEST_MODE=1 BAZARGHAR_DB=~/bazarghar-qa/shop.db \
    uv run bazarghar --port 8785 --test-mode --reset        # another terminal
$ PACT_DO_NOT_TRACK=true BAZARGHAR_DB=~/bazarghar-qa/shop.db uv run pytest provider_tests -v -s
…
provider_tests/test_provider_pact.py::test_bazarghar_api_honours_the_mobile_pact
127.0.0.1 - - [16/Nov/2026 17:30:13] "POST /_pact/state HTTP/1.1" 200 -
127.0.0.1 - - [16/Nov/2026 17:30:13] "POST /_pact/state HTTP/1.1" 200 -
127.0.0.1 - - [16/Nov/2026 17:30:14] "POST /_pact/state HTTP/1.1" 200 -

Verifying a pact between bazarghar-mobile and bazarghar-api

  a price quote for 2000 taka in Dhaka (0s loading, 342ms verification)
    returns a response which
      has status code 200 (OK)
      includes headers
        "Content-Type" with value "application/json" (OK)
      has a matching body (OK)

  a request for an order that does not exist (0s loading, 426ms verification)
     Given sumi is logged in
    returns a response which
      has status code 404 (OK)
      includes headers
        "Content-Type" with value "application/json" (OK)
      has a matching body (OK)

  a request for sumi's placed order (0s loading, 384ms verification)
     Given order 6 is placed and belongs to sumi
    returns a response which
      has status code 200 (OK)
      includes headers
        "Content-Type" with value "application/json" (OK)
      has a matching body (OK)

PASSED

============================== 1 passed in 1.63s ==============================

প্রথম তিনটি লাইন pact-python-এর নিজের ছোট server-এর log: verifier প্রতিটি interaction-এর আগে /_pact/state-এ state-এর নাম পাঠায়, আর সেই server আমাদের STATES dict থেকে ঠিক function-টি ডাকে। Quote-এর interaction-এ কোনো given নেই, তবু ডাক এসেছে: Pact একটি খালি নামের সাধারণ setup ডাক পাঠায়, dict-এ সেটি না থাকলে নীরবে বাদ যায়। তিনটি interaction, প্রতিটিতে status, header আর body: সব OK. প্রতিটি interaction-এর যাচাইয়ে ০.৩ থেকে ০.৪ সেকেন্ড, পুরো run ২ সেকেন্ডের কম।

নাম বদলানো field — আসল ব্যর্থতা

এবার সেই সকালের ঘটনা। API-র “v1.1” তৈরি করা হলো একটি ছোট মোড়ক (wrapper) দিয়ে, যা shared app-এর কোড না ছুঁয়ে প্রতিটি /api/orders উত্তরে pricing.total-এর নাম বদলে grand_total করে। একই verification:

$ PACT_DO_NOT_TRACK=true BAZARGHAR_DB=~/bazarghar-qa/shop.db uv run pytest provider_tests -s -q --tb=line
…
  a request for sumi's placed order (0s loading, 395ms verification)
     Given order 6 is placed and belongs to sumi
    returns a response which
      has status code 200 (OK)
      includes headers
        "Content-Type" with value "application/json" (OK)
      has a matching body (FAILED)

Failures:

1) Verifying a pact between bazarghar-mobile and bazarghar-api Given order 6 is placed and belongs to sumi - a request for sumi's placed order
    1.1) has a matching body
           $.pricing -> Actual map is missing the following keys: total

There were 1 pact failures

F
================================== FAILURES ===================================
E   RuntimeError: Failed to execute verifier for VerifierHandle(0x1b3575728e0).
~/bazarghar-qa/.venv/Lib/site-packages/pact_ffi/__init__.py:7808: RuntimeError: …
=========================== short test summary info ===========================
FAILED provider_tests/test_provider_pact.py::test_bazarghar_api_honours_the_mobile_pact
1 failed in 1.60s

বার্তাটি খুব নির্দিষ্ট: কোন consumer (bazarghar-mobile), কোন interaction, কোন অবস্থায়, আর JSON-এর কোন জায়গায় ($.pricing) কোন key নেই (total). বাকি দুটি interaction পাস করেছে, কারণ quote আর 404-এর উত্তরে কিছু বদলায়নি। শেষের RuntimeError শুধু pytest-কে লাল করার পথ; পড়ার মতো তথ্য ওপরের Failures অংশে। এখন ব্যর্থতা ঘটল provider দলের build-এ, deploy-এর আগে, আর তারা জানে ঠিক কোন দলের সাথে কথা বলতে হবে। নিজের কাছে নিরীহ পরিচ্ছন্নতা হলেও, এই consumer-এর কাছে এটি একটি breaking change.

Verifier · interaction: sumi's placed order
ধাপ
Provider state
আসল উত্তর
Rule
  1. চুক্তি পড়া। Verifier pacts/ থেকে ফাইলটি নিল: consumer bazarghar-mobile, তিনটি interaction. এখানে আমরা তৃতীয়টি অনুসরণ করছি: সুমির placed অর্ডার।
  2. Provider state. Interaction-এর given “order 6 is placed and belongs to sumi”. Verifier নামটি পাঠাল; handler reset চালিয়ে seed data ফেরাল আর contract-token-sumi বসাল।
  3. Replay. চুক্তির request হুবহু গেল: GET /api/orders/6, Authorization header সহ। উত্তর 200, Content-Type JSON: এই দুই অংশ OK.
  4. Body: প্রথম দুই rule. $.id 6, পূর্ণসংখ্যা ✓. $.status “placed”, regex-এ মেলে ✓. আসল উত্তরের বাড়তি field (address, history…) উপেক্ষিত।
  5. Body: $.pricing.total. pricing map-এ আছে subtotal, discount, delivery আর grand_total, কিন্তু total নেই। Rule-এর মান যাচাইয়ের আগেই key-টি অনুপস্থিত: ✗.
  6. শেষ rule আর রায়। $.allowed_actions একটি তালিকা ✓. তবু body-র একটি ভুলই যথেষ্ট: “has a matching body (FAILED)”, মোট ১টি pact failure, pytest লাল। Provider দল এখন দুটি পথের একটি নেবে: নাম বদল ফেরানো, অথবা কিছুদিন দুটি নামই পাঠিয়ে mobile দলকে নতুন নামে যেতে সময় দেওয়া।

Provider state লেখার সতর্কতা। ওপরের handler সরাসরি provider-এর test database-এ একটি session লিখেছে। এটি গ্রহণযোগ্য, কারণ state handler provider দলের নিজের test কোড আর database-টি এই run-এর জন্যই। তবে নিয়মটি মনে রাখুন: state handler শুধু data সাজাবে, API-র আচরণ বদলাবে না। Handler যদি “উত্তরটিকে চুক্তির মতো বানিয়ে দেয়” (যেমন auth পুরো বন্ধ করে), তাহলে verification আসল সিস্টেম যাচাই করছে না। আর state-এর নাম হোক ব্যবসার ভাষায় (“order 6 is placed and belongs to sumi”), table-এর ভাষায় নয়; তাতে দুই দল একই বাক্য বোঝে।

৬ · Contract কী ধরে না — schema, functional আর E2E-এর সাথে তুলনা

Contract test-এর শক্তি তার সংকীর্ণতায়, আর দুর্বলতাও সেখানেই। পরীক্ষাটি এভাবে: বাজারঘর app চালু করা হলো সুপরিচিত seeded bug delivery_after_discount সহ, যেখানে ২০০০ টাকার free-delivery সীমা ছাড়ের পরের অঙ্কে দেখা হয়। নিয়ম অনুযায়ী ঢাকায় ২০০০ টাকার অর্ডারে delivery ফ্রি, মোট ১৮০০। এই bug-এ:

$ curl -s "http://127.0.0.1:8785/api/pricing/quote?subtotal=2000&district=Dhaka"
{"subtotal":2000,"discount":200,"delivery":60,"total":1860,"district":"Dhaka","plus":false}

$ PACT_DO_NOT_TRACK=true BAZARGHAR_DB=~/bazarghar-qa/shop.db uv run pytest provider_tests -q
.                                                                        [100%]
1 passed in 1.59s

Delivery ৬০ টাকা, গ্রাহকের কাছ থেকে বাড়তি ৬০ টাকা, তবু চুক্তি সবুজ। কারণ চুক্তি বলেছিল “delivery একটি পূর্ণসংখ্যা”, আর ৬০ পূর্ণসংখ্যা। এটি contract test-এর ব্যর্থতা নয়, তার সংজ্ঞা: সে দেখে দুই পক্ষ একই ভাষায় কথা বলছে কি না, কথাটি সত্য কি না নয়। এই bug ধরবে পর্ব ৩১-এর (Code দিয়ে API testing) মতো functional API test, যা ব্যবসার নিয়ম থেকে প্রত্যাশিত মান বের করে। কেউ যদি চুক্তিতে exact "delivery": 0 লিখে এই ফাঁক ভরাতে চান, তাহলে provider-এর প্রতিটি নিয়ম বদলে mobile দলের চুক্তি ভাঙবে: দায়িত্ব ভুল জায়গায় চলে যায়।

OpenAPI দিয়ে schema-ভিত্তিক যাচাই — আরেকটি সত্যিকারের run

বাজারঘর API নিজের /openapi.json প্রকাশ করে (FastAPI এটি কোড থেকে বানায়)। একটি ছোট script (stdlib আর httpx, প্রায় ৪০ লাইন) pact ফাইলের প্রতিটি উদাহরণ উত্তর OpenAPI-র schema-র সাথে মেলায়: প্রতিটি field schema-তে আছে কি না, আর ধরন মেলে কি না। এটি consumer-এর প্রত্যাশা আর provider-এর ঘোষণার তুলনা, আসল উত্তরের নয়। দুটি run: আসল API-তে, আর §৫-এর নাম-বদলানো v1.1-এ।

$ uv run python schema_check.py            # the real API
GET /api/pricing/quote -> 200: OK
GET /api/orders/{order_id} -> 404: OK
GET /api/orders/{order_id} -> 200: OK

$ uv run python schema_check.py            # the v1.1 wrapper (total renamed)
GET /api/pricing/quote -> 200: OK
GET /api/orders/{order_id} -> 404: OK
GET /api/orders/{order_id} -> 200: OK

দুই ক্ষেত্রেই তিনটি OK. v1.1-এ আসল উত্তরে total নেই, অথচ OpenAPI এখনো total ঘোষণা করে, কারণ মোড়কটি শুধু উত্তর বদলেছে, নথি নয়। এই সৎ ফলটি একটি বড় শিক্ষা: schema-ভিত্তিক চুক্তি ততটুকুই বিশ্বস্ত, যতটুকু provider-এর নথি তার আসল আচরণের সাথে মেলে। তাই এই পথে provider-কে আলাদাভাবে প্রমাণ করতে হয় যে তার উত্তর নিজের schema মানে (পর্ব ৩১-এর JSON Schema validation আর schemathesis ঠিক এই কাজ করে)। Pact-এর replay এই দুই ধাপ একসাথে করে, কারণ সে আসল উত্তর দেখে।

Testকী প্রশ্নের উত্তর দেয়কে চালায়, কোথায়এই পর্বের উদাহরণে
Consumer-driven contract (Pact)Consumer যা পাঠায় আর পড়ে, আসল provider কি তা মানে?দুই দলই, নিজের build-এ, দ্রুতনাম বদল ধরল; delivery bug ধরল না
Schema-ভিত্তিক (OpenAPI)উত্তর কি ঘোষিত গঠন মানে? (provider-এর দিক)Provider, অনেক সময় tool দিয়ে স্বয়ংক্রিয়নথি পুরোনো থাকায় নাম বদল ধরেনি
Functional API testনিয়ম অনুযায়ী মান সঠিক কি?Provider দল বা QAdelivery ৬০-এর bug ধরবে
End-to-endপুরো যাত্রা আসল পরিবেশে কাজ করে কি?QA, সব service একসাথে, ধীরদুটিই ধরতে পারে, তবে দেরিতে আর দামি

শিল্পে একটি মাঝামাঝি পথও আছে, যাকে কিছু বাণিজ্যিক broker “bi-directional” contract testing বলে: consumer-এর pact ফাইল আর provider-এর OpenAPI নথি স্বয়ংক্রিয়ভাবে মেলানো হয়, আর provider আলাদাভাবে প্রমাণ দেয় যে তার কোড নিজের নথি মানে। ওপরের script সেই ধারণার একটি খুদে রূপ। Java জগতে Spring Cloud Contract (Apache 2.0) আরেকটি পরিচিত tool, যেখানে চুক্তি সাধারণত provider-এর repository-তে লেখা হয়।

৭ · Broker, deployment matrix আর can-i-deploy

এ পর্যন্ত pact ফাইলটি একই ফোল্ডারে ছিল। বাস্তবে consumer আর provider আলাদা repository-তে, আলাদা CI-তে। তখন ফাইলটি আদান-প্রদান করে Pact Broker (open source, MIT; একটি ছোট web service আর database). Broker তিনটি জিনিস মনে রাখে: কোন consumer-এর কোন version কোন চুক্তি প্রকাশ করেছে, কোন provider-এর কোন version সেটি যাচাই করে কী ফল পেয়েছে, আর কোন version এখন কোন পরিবেশে (test, production) চলছে। প্রথম দুটি মিলিয়ে একটি টেবিল: deployment matrix.

Deploy-এর ঠিক আগে CI প্রশ্ন করে: “আমি যে version deploy করতে যাচ্ছি, সেটি কি production-এ এখন চলা প্রতিটি সঙ্গীর সাথে যাচাইকৃত?” Pact-এর জগতে এই প্রশ্নের tool-এর নাম can-i-deploy. Broker-এর CLI দিয়ে ধাঁচটি এমন (উদাহরণ, চালানো হয়নি: এই lab-এ broker চালানো হয়নি, কারণ তার জন্য আলাদা server আর database লাগে):

# উদাহরণ, চালানো হয়নি
pact-broker can-i-deploy --pacticipant bazarghar-api --version 1.2 \
    --to-environment production
pact-broker record-deployment --pacticipant bazarghar-api --version 1.2 \
    --environment production

প্রথম কমান্ড matrix দেখে হ্যাঁ বা না বলে (না হলে CI থামে); দ্বিতীয়টি deploy-এর পরে broker-কে জানায় production-এ এখন কোন version. Matrix-এর যুক্তিটি নিচের block-এ নিজে চালিয়ে দেখুন: তিনটি app (mobile, courier, api), সাতটি যাচাইয়ের ফল, আর production-এ কোন version চলছে।

# The broker's matrix: (consumer, version, provider, version) -> verified?
matrix = {("mobile", "2.3", "api", "1.0"): True,
          ("mobile", "2.3", "api", "1.1"): False,      # total renamed
          ("mobile", "2.3", "api", "1.2"): True,
          ("mobile", "2.4", "api", "1.2"): True,
          ("courier", "5.0", "api", "1.0"): True,
          ("courier", "5.0", "api", "1.1"): True,
          ("courier", "5.0", "api", "1.2"): True}
production = {"mobile": "2.3", "courier": "5.0", "api": "1.0"}
pairs = {(c, p) for c, _, p, _ in matrix}               # who talks to whom

def can_i_deploy(app, version):
    rows = []
    for c, p in sorted(pairs):
        if app == c:          # I am the consumer: check the live provider
            key, other = (c, version, p, production[p]), p
        elif app == p:        # I am the provider: check every live consumer
            key, other = (c, production[c], p, version), c
        else:
            continue
        rows.append((other, production[other], matrix.get(key)))
    return all(r[2] is True for r in rows), rows

WORD = {True: "verified", False: "FAILED", None: "no result yet"}
for app, version in [("api", "1.1"), ("api", "1.2"), ("mobile", "2.4")]:
    ok, rows = can_i_deploy(app, version)
    print(f"can-i-deploy {app} {version} -> {'YES' if ok else 'NO'}")
    for other, live, result in rows:
        print(f"    with {other} {live} (production): {WORD[result]}")

আসল আউটপুট:

can-i-deploy api 1.1 -> NO
    with courier 5.0 (production): verified
    with mobile 2.3 (production): FAILED
can-i-deploy api 1.2 -> YES
    with courier 5.0 (production): verified
    with mobile 2.3 (production): verified
can-i-deploy mobile 2.4 -> NO
    with api 1.0 (production): no result yet

api 1.1 আটকে গেল, যদিও courier-এর সাথে সব ঠিক: একটি সঙ্গীর ব্যর্থতাই যথেষ্ট। api 1.2 (যেটি হয়তো দুটি নামই পাঠায়) দুই consumer-এর production version-এর সাথেই যাচাইকৃত, তাই হ্যাঁ। সবচেয়ে মজার mobile 2.4: সে যাচাই হয়েছে শুধু api 1.2-এর সাথে, কিন্তু production-এ এখনো api 1.0. “ফল নেই” মানে “না”, কারণ অজানা ঝুঁকি নিয়ে deploy নয়। সঠিক ক্রম তাই: আগে api 1.2 deploy, তারপর mobile 2.4.

Production আর matrix
প্রশ্ন
Production
দেখা সারি
রায়
  1. api 1.1 কি যেতে পারে? Provider হিসেবে তার production-এর consumer দুটি: courier 5.0 (✓) আর mobile 2.3 (✗, total-এর নাম বদল)। একটি ✗ মানেই NO; CI এখানেই থামবে।
  2. api 1.2 কি যেতে পারে? একই দুই consumer, দুটি সারিই ✓. রায় YES.
  3. mobile 2.4 কি যেতে পারে? Consumer হিসেবে তার provider api, production-এ api 1.0. Matrix-এ “mobile 2.4 × api 1.0” সারি নেই, তাই NO. ফল না থাকা আর সবুজ ফল এক নয়।
  4. api 1.2 deploy হলো। CI record-deployment চালিয়ে broker-কে জানাল। Production-এর তালিকা এখন: mobile 2.3, courier 5.0, api 1.2.
  5. mobile 2.4 আবার জিজ্ঞাসা। এবার দেখার সারি “mobile 2.4 × api 1.2”, যা ✓. রায় YES. ক্রমটিই নিরাপত্তা: provider আগে, যে consumer নতুন জিনিস চায় সে পরে।

দুই দলের CI-তে চুক্তি

সব মিলিয়ে দুটি pipeline দেখতে এমন। Consumer (mobile দল): unit test আর consumer test চালানো; সবুজ হলে pact ফাইল broker-এ প্রকাশ, commit-এর hash-কে version ধরে; তারপর can-i-deploy; হ্যাঁ হলে deploy আর record-deployment. Provider (API দল): নিজের unit আর functional test; তারপর broker থেকে প্রাসঙ্গিক চুক্তিগুলো এনে provider verification, আর ফল broker-এ ফেরত পাঠানো; তারপর একই can-i-deploy আর deploy. লক্ষ করুন, কোনো ধাপেই দুই দলের service একসাথে চালু করতে হয়নি, আর প্রতিটি দল শুধু নিজের build-এর মালিক। একটি তৃতীয় trigger-ও থাকে: consumer নতুন চুক্তি প্রকাশ করলে provider-এর verification আলাদাভাবে চালু হয়, যাতে mobile দলকে API দলের পরের commit-এর জন্য অপেক্ষা করতে না হয়।

Broker-এর আরও দুটি সুবিধা নাম হিসেবে জেনে রাখুন (বিস্তারিত tool-এর নথিতে): pending pact, যেখানে একটি নতুন চুক্তি provider-এর build ভাঙায় না যতক্ষণ না provider প্রথমবার সেটি সফলভাবে যাচাই করে; আর webhook, যা নতুন চুক্তি প্রকাশ হলেই provider-এর CI-তে verification চালু করে। দুটিরই লক্ষ্য এক: এক দলের পরিবর্তন যেন অন্য দলের কাজ হঠাৎ আটকে না দেয়, আবার ভাঙা জিনিসও production-এ না যায়।

৮ · কখন contract testing, কখন নয় — আর প্রচলিত ভুল

Contract testing সবচেয়ে কাজের, যখন তিনটি শর্ত একসাথে থাকে: consumer আর provider আলাদা দলের, আলাদা সময়ে deploy হয়, আর consumer-রা পরিচিত। বাজারঘরের mobile app, courier service আর API ঠিক এমন। কিন্তু সব জায়গায় নয়:

  • Public API, অচেনা consumer: কে কী পড়ে জানার উপায় নেই। সেখানে provider-driven পথ: OpenAPI, versioning (SemVer), আর schema test. ওয়েব API-র versioning-এর আলোচনা ফুল-স্ট্যাক ওয়েব ফ্রেমওয়ার্ক কোর্সের পর্ব ৩৫-এ।
  • একই দল, একই repository, একসাথে deploy: চুক্তির আনুষ্ঠানিকতা প্রায়ই বাড়তি; একটি ভালো integration test বা ভাগ করা type/schema যথেষ্ট। এই হালকা পথের আলোচনা ফুল-স্ট্যাক কোর্সের পর্ব ৭৭-এ।
  • বার্তা আর event: HTTP ছাড়া queue-র বার্তাতেও (যেমন “order shipped” event) একই চক্র খাটে; Pact-এ এর নাম message pact. আর schema registry-র compatibility নিয়ম একই কাজ ভিন্ন পথে করে।

প্রচলিত ভুল

ভুলফলপ্রতিকার
উত্তরের সব field চুক্তিতে রাখাProvider কিছুই বদলাতে পারে নাশুধু client যা পড়ে
সব মান exactTest data বদলালেই লালType/regex; সিদ্ধান্তের মান exact
চুক্তিতে ব্যবসার নিয়ম (delivery ০ হবেই)দায়িত্ব ভুল দলে, ভঙ্গুরনিয়ম provider-এর functional test-এ
Consumer test-এ client বাদ দিয়ে সরাসরি HTTPচুক্তি আছে, client-এর আসল ব্যবহার নেইTest সবসময় আসল client কোড চালাবে
State handler-এ auth বা নিয়ম বন্ধ করাযাচাই আসল সিস্টেমের নয়State শুধু data সাজায়
can-i-deploy ছাড়া deployযাচাই হয়, কিন্তু সিদ্ধান্তে লাগে নাCI-র deploy ধাপের আগে বাধ্যতামূলক

আরও গভীরে। Contract testing আসলে বিতরণ করা সিস্টেমে backward compatibility-কে (backward compatibility) যন্ত্রে যাচাইযোগ্য করার কৌশল। Matrix-এর আকার consumer আর provider-এর version-এর গুণফলে বাড়ে, তাই broker শুধু “পরিবেশে চলমান” আর “branch-এর সর্বশেষ” version বেছে যাচাই করে (Pact-এ consumer version selector নামে পরিচিত)। গবেষণা আর শিল্পের আলোচনায় একটি খোলা প্রশ্ন হলো চুক্তি কতটা আচরণ ধরবে: শুধু গঠন, নাকি ক্রম, সময়সীমা আর error-এর অর্থও; Pact ইচ্ছা করে প্রথমটিতে সীমিত থাকে, যাতে চুক্তি স্থিতিশীল থাকে। Event-চালিত সিস্টেমে একই প্রশ্ন schema evolution-এর নিয়মে (backward, forward, full compatibility) উত্তর পায়।

পরীক্ষা ও ইন্টারভিউতে। বিশ্ববিদ্যালয়, চাকরি বা ইন্টারভিউর পরীক্ষায় এমন প্রশ্ন সাধারণ:

  • Contract test আর integration test-এর পার্থক্য? Contract test দুই পক্ষকে আলাদাভাবে একই লিখিত চুক্তির বিরুদ্ধে যাচাই করে; integration test দুটিকে একসাথে চালায়।
  • Consumer-driven কেন? Provider জানতে পারে কোন field কে পড়ে, তাই বাকিগুলো বদলাতে স্বাধীন, আর ভাঙলে ঠিক কাকে জানাতে হবে তা জানে।
  • Provider state কী? চুক্তির given-বাক্য, যা পূরণ করতে provider verification-এর আগে data সাজানো হয়।
  • can-i-deploy কী দেখে? Deploy করতে চাওয়া version লক্ষ্য পরিবেশে চলমান প্রতিটি সঙ্গীর সাথে সফলভাবে যাচাই হয়েছে কি না।
  • Contract test কি business rule যাচাই করে? না; ধরন আর গঠন দেখে। মান সঠিক কি না, তা functional test-এর কাজ।

৯ · AI-এর যুগে contract testing

AI সহকারী Pact-এর test দ্রুত লিখে দেয়, আর এখানে ভুলগুলো বিশেষ ধরনের। প্রচলিত: pact-python-এর পুরোনো (v2) API আর নতুন API মিশিয়ে ফেলা, অস্তিত্বহীন method বা matcher বানানো; আসল উত্তরের সব field কপি করে exact মান দিয়ে চুক্তি বানানো, যা প্রথম test data বদলেই ভাঙে; provider-এর আজকের উত্তর থেকে চুক্তি লেখা (“কোড যা করে তা-ই প্রত্যাশা”), অথচ চুক্তি হওয়া উচিত client যা পড়ে তা থেকে; শুধু happy path, 404 বা 401-এর interaction বাদ; state handler-এ auth বন্ধ করে দেওয়া; consumer test-এ client বাদ দিয়ে সরাসরি HTTP ডাকা; আর না চালিয়েই “verification পাস” দাবি।

AI-কে client কোড আর পড়ার প্রয়োজন দিয়ে চুক্তি চাইতে পারেন:

তুমি একজন অভিজ্ঞ QA engineer, Pact আর pytest-এ দক্ষ। নিচে বাজারঘরের mobile app-এর API client দিলাম। [client.py পেস্ট করুন] ১. Client কোড পড়ে বলো, প্রতিটি method উত্তরের কোন কোন field সত্যিই পড়ে। শুধু সেগুলো চুক্তিতে রাখবে। ২. pact-python (আমার version: 4.2.0) দিয়ে consumer test লেখো: সফল উত্তর, 404 আর 401-এর interaction. প্রতিটি field-এর matcher (type, regex, exact) কেন বাছলে, এক লাইনে লেখো। ৩. ব্যবসার নিয়মের মান (delivery, ছাড়) exact রাখবে না। ৪. প্রতিটি given-বাক্যের জন্য provider state handler-এর একটি খসড়া দাও, যা শুধু data সাজায়; auth বা নিয়ম বন্ধ করবে না। ৫. যে Pact method বা matcher ব্যবহার করবে, তার নাম আলাদা তালিকায় দাও; আমি অফিসিয়াল নথিতে মিলিয়ে নেব। নিজে test চালানোর দাবি করবে না।

AI-এর লেখা contract test হাতে পেলে — চেকলিস্ট

ভাবনার প্রশ্ন

প্রতিটি প্রশ্ন নিয়ে নিজে কিছুক্ষণ ভাবুন — তারপর “→ উত্তর” চাপুন।

প্র ০১Consumer-driven contract-এর ধারণা কোন সমস্যা থেকে এসেছিল, আর Postel-এর নীতির সাথে তার সম্পর্ক কী?

২০০০-এর দশকের মাঝামাঝি বড় প্রতিষ্ঠানগুলো service-oriented architecture-এ যাচ্ছিল, আর একটি সাধারণ যন্ত্রণা দেখা দিচ্ছিল: একটি service-কে অনেকে ব্যবহার করে, তাই তার মালিক কোনো কিছু বদলাতে ভয় পায়। প্রতিটি পরিবর্তনের আগে সব ব্যবহারকারীর সাথে বৈঠক, আর শেষে সিদ্ধান্ত “কিছুই সরাবেন না, শুধু যোগ করুন”। Ian Robinson-এর ২০০৬ সালের প্রবন্ধ এই অবস্থার নাম দিয়েছিল service evolution-এর সমস্যা, আর প্রস্তাব করেছিল উল্টো দিক থেকে ভাবতে: প্রতিটি consumer নিজের প্রত্যাশা লিখে provider-কে দেবে, আর provider-এর আসল দায় সব consumer-এর প্রত্যাশার যোগফল।

এর পেছনে একটি পুরোনো নীতি আছে। Jon Postel ১৯৮০ সালের TCP-র নথিতে (RFC 761) লিখেছিলেন, নিজে যা পাঠান তাতে রক্ষণশীল হোন, অন্যের কাছ থেকে যা নেন তাতে উদার হোন; একে robustness principle বলা হয়। Consumer-এর দিকে এর রূপ tolerant reader: অচেনা field উপেক্ষা করা, শুধু দরকারি অংশ পড়া। Consumer যদি সত্যিই এভাবে পড়ে, তাহলে provider নতুন field যোগ করলে কিছু ভাঙে না, আর পুরোনো field সরানোর আগে চুক্তিগুলো বলে দেয় কেউ তা পড়ে কি না।

Postel-এর নীতির সমালোচনাও আছে: অতি-উদার গ্রহণ অনেক প্রোটোকলে ভুল আচরণকে স্থায়ী করেছে, কারণ ভুল পাঠানো পক্ষ কখনো শাস্তি পায় না। Contract testing এখানে ভারসাম্য আনে। Consumer উদারভাবে পড়ে, কিন্তু যা পড়ে তা কড়াভাবে লিখে রাখে; provider স্বাধীন, কিন্তু লিখিত অংশে বাধ্য। বাজারঘরের mobile app-এর চুক্তি তাই চারটি field-এ সীমিত, আর status-এর মতো সিদ্ধান্তের field-এ regex দিয়ে কড়া।

মূল উপলব্ধি: চুক্তির কলম consumer-এর হাতে দিলে provider-এর অজানা ভয় একটি লিখিত তালিকায় বদলে যায়: কী বদলানো নিরাপদ, আর কী নয়।

প্র ০২“Hyrum-এর সূত্র” কী বলে, আর contract testing তার বিরুদ্ধে কতটা সুরক্ষা দেয়?

সফটওয়্যার প্রকৌশলী Hyrum Wright-এর নামে প্রচলিত একটি পর্যবেক্ষণ বলে: একটি API-র ব্যবহারকারী যথেষ্ট বেশি হলে, চুক্তিতে আপনি কী প্রতিশ্রুতি দিয়েছেন তাতে কিছু যায় আসে না; আপনার সিস্টেমের প্রতিটি দৃশ্যমান আচরণের ওপর কেউ না কেউ নির্ভর করবে। তালিকার ক্রম, error বার্তার হুবহু লেখা, উত্তরের সময়, এমনকি JSON-এ field-এর ক্রম: কেউ হয়তো এগুলো ধরে কোড লিখে ফেলেছে, যদিও নথিতে কোথাও এর প্রতিশ্রুতি নেই।

Consumer-driven contract এই লুকানো নির্ভরতাকে আংশিকভাবে দৃশ্যমান করে। যদি mobile app error বার্তার লেখা দেখে সিদ্ধান্ত নেয়, তাহলে চুক্তিতে সেই মান exact থাকবে, আর provider জানবে বার্তাটি বদলানো নিরাপদ নয়। বাজারঘরের চুক্তিতে আমরা উল্টোটা করেছি: message শুধু type-এ, কারণ app বার্তা দেখায় মাত্র, সিদ্ধান্ত নেয় code দিয়ে। এভাবে চুক্তি লেখার সময়ই দল ভাবতে বাধ্য হয়, কোন আচরণের ওপর তারা সত্যিই নির্ভর করছে।

তবে সুরক্ষা সম্পূর্ণ নয়। চুক্তি শুধু তা-ই ধরে যা consumer test-এ আছে। Client যদি গোপনে তালিকার প্রথম উপাদানকে “সর্বশেষ অর্ডার” ধরে নেয়, অথচ চুক্তিতে ক্রমের কথা নেই, তাহলে provider ক্রম বদলালে verification সবুজ থাকবে আর app ভুল দেখাবে। সময়ের নির্ভরতা (উত্তর ২ সেকেন্ডের মধ্যে আসবে) চুক্তিতে সাধারণত থাকেই না। তাই contract test-এর পাশে consumer দলের নিজস্ব code review দরকার: client কোড এমন অনুমান করছে কি না যা চুক্তিতে লেখা নেই।

আরেকটি দিক: অচেনা consumer-এর বেলায় Hyrum-এর সূত্র সবচেয়ে কঠোর। Public API-র মালিক তাই সাধারণত version নম্বর আর deprecation-এর সময়সীমা দিয়ে নিজেকে রক্ষা করেন, কারণ চুক্তি সংগ্রহের উপায় নেই।

মূল উপলব্ধি: লিখিত চুক্তি নির্ভরতার একটি সৎ তালিকা, কিন্তু সম্পূর্ণ নয়; অলিখিত অনুমান খুঁজে লিখে ফেলাই tester-এর কাজ।

প্র ০৩অনেক service-এর সিস্টেমে শুধু end-to-end test-এর ওপর নির্ভর করা কেন টেকসই নয়?

J. B. Rainsberger ২০০৯ সালের দিকে একটি আলোচিত বক্তৃতায় যুক্তি দিয়েছিলেন যে বড় integrated test-এর ওপর ভর করা একটি ফাঁদ: আত্মবিশ্বাস পেতে আরও test লাগে, আর প্রতিটি test আগেরটির চেয়ে ধীর ও ভঙ্গুর। এর পেছনে সরল গণিত আছে। দশটি service-এর প্রতিটিতে যদি গড়ে পাঁচটি গুরুত্বপূর্ণ পথ থাকে, তাহলে একসাথে সব মিশ্রণ পরীক্ষা করতে পথের সংখ্যা গুণফলে বাড়ে, যোগফলে নয়; কোনো test suite সেই সংখ্যার কাছাকাছি যেতে পারে না।

এর সাথে আছে পরিবেশের সমস্যা। একটি ভাগ করা staging পরিবেশে প্রতিটি দলের সর্বশেষ version চলে, প্রায়ই অর্ধেক-প্রস্তুত অবস্থায়। এক দলের ভাঙা deploy অন্য সব দলের test লাল করে। Test data একে অপরের সাথে সংঘর্ষ করে: একজনের test অর্ডার ৬ বাতিল করল, আরেকজনের test সেটিকে placed ধরে নিয়েছিল। ফলে লাল test-কে মানুষ উপেক্ষা করতে শেখে, আর আসল ব্যর্থতাও শব্দের মধ্যে হারিয়ে যায়।

Contract testing এই গুণফলকে যোগফলে নামিয়ে আনে। প্রতিটি সংযোগ দুই প্রান্তে আলাদাভাবে যাচাই হয়: consumer-এর দিকে mock-এর বিরুদ্ধে, provider-এর দিকে নিজের নিয়ন্ত্রিত data-য়। দশটি service-এর বিশটি সংযোগ মানে চল্লিশটি ছোট, দ্রুত, নিজের দলের build-এ চলা test-গুচ্ছ। কোনটি লাল হলে মালিক স্পষ্ট।

তবু end-to-end একেবারে বাদ নয়। কয়েকটি গুরুত্বপূর্ণ যাত্রা (login, checkout, payment) আসল পরিবেশে চালানো দরকার, কারণ configuration, network, certificate আর deploy-এর ভুল কোনো চুক্তিতে ধরা পড়ে না। Test pyramid-এর ভাষায়: নিচে অনেক unit, মাঝে contract আর integration, ওপরে অল্প কিছু E2E.

মূল উপলব্ধি: সংযোগ যাচাই করতে সব কিছু একসাথে চালানোর দরকার নেই; প্রতিটি সংযোগের দুই প্রান্ত একই চুক্তিতে বাঁধলেই বেশিরভাগ ভুল আগে ধরা পড়ে।

প্র ০৪Provider state-এর নকশা কেন একটি test data-র সমস্যা, আর ভুল নকশা কী ক্ষতি করে?

Provider verification আসলে একটি data-নির্ভর test: চুক্তি বলে “অর্ডার ৬ সুমির আর placed”, আর এটি সত্য না হলে উত্তর মিলবে না। তাই provider state হলো test data-র ব্যবস্থাপনা, যা পর্ব ২৩-এর প্রশ্নগুলোই তোলে: data কে বানায়, কখন মোছে, test-গুলো একে অপরের ওপর নির্ভর করে কি না।

প্রথম ভুল: ভাগ করা, আগে থেকে ভরা database-এর ওপর নির্ভর করা, কোনো state handler ছাড়া। আজ পাস করে, কাল কেউ অর্ডার ৬ বাতিল করলে ব্যর্থ; চুক্তির কোনো দোষ নেই। এই পর্বের run-এ প্রতিটি state reset দিয়ে শুরু হয়েছে, তাই interaction-গুলো ক্রম-নিরপেক্ষ। দ্বিতীয় ভুল: state-এর নাম table-এর ভাষায়, যেমন “orders row 6 status=placed”. এতে consumer দল provider-এর ভেতরের গঠন জেনে ফেলে, আর provider database বদলালে চুক্তির ভাষাও বদলাতে হয়। ব্যবসার ভাষায় লেখা নাম (“order 6 is placed and belongs to sumi”) এই জড়ানো এড়ায়।

তৃতীয় এবং সবচেয়ে বিপজ্জনক ভুল: state handler দিয়ে আচরণ বদলানো। ধরুন token-এর ঝামেলা এড়াতে কেউ handler-এ auth পুরোপুরি বন্ধ করে দিলেন। Verification সবুজ, কিন্তু এখন আর জানা নেই আসল API Authorization header ঠিকভাবে পড়ে কি না। এই পর্বে আমরা উল্টো পথ নিয়েছি: auth চালু রেখে, চুক্তির token-টিকে test database-এ বৈধ session হিসেবে বসিয়েছি। কিছু ভাষার Pact library request filter-এর মতো বিকল্পও দেয় (প্রতিটি request-এ নতুন token বসানো), তবে মূলনীতি একই: আসল নিয়ম চলবে, শুধু data সাজানো হবে।

বড় সিস্টেমে state-এর সংখ্যাও সমস্যা হয়ে ওঠে। প্রতিটি consumer নতুন নতুন given-বাক্য আনলে provider দলের handler-এর তালিকা বেড়েই চলে। তাই দলগুলো প্রায়ই অল্প কিছু ভাগ করা, parameter-যুক্ত state-এ একমত হয় (যেমন “order {id} is {status}”)।

মূল উপলব্ধি: Provider state হলো দুই দলের ভাগ করা fixture-এর ভাষা; এটি data সাজাবে, নিয়ম নয়।

প্র ০৫“Consumer চুক্তি লেখে” মানে কি provider-এর ওপর consumer-এর একনায়কত্ব? এই সম্পর্ক কীভাবে সুস্থ রাখবেন?

শুনতে তাই মনে হয়, আর বাস্তবে এমন অভিযোগ ওঠেও। একটি consumer দল চুক্তিতে এমন field চাইল যা API-তে নেই, বা এমন আচরণ চাইল যা ব্যবসার নিয়মের বিরুদ্ধে; provider-এর build লাল, আর তারা চাপ অনুভব করে। এ কারণেই Pact-এর পরিভাষায় চুক্তিকে আলোচনার শুরু বলা হয়, আদেশ নয়। চুক্তি ভাঙলে প্রথম প্রশ্ন “কে ঠিক?”, “কে দোষী?” নয়।

সুস্থ রাখার কয়েকটি অভ্যাস প্রচলিত। প্রথমত, নতুন চুক্তি provider-এর main build-কে সাথে সাথে ভাঙাবে না: broker-এর pending pact সুবিধা এটিই করে, যতক্ষণ না provider একবার সফলভাবে চুক্তিটি যাচাই করে। দ্বিতীয়ত, consumer দল চুক্তিতে নতুন কিছু চাইলে আগে provider দলের সাথে কথা বলে নেয়; চুক্তির ফাইল একটি পরিবর্তনের প্রস্তাব, যেমন code review-তে একটি pull request. তৃতীয়ত, provider দল ভাঙন দেখলে consumer-এর মালিককে নাম ধরে জানায়, আর পরিবর্তনটি ধাপে ধাপে করে: আগে নতুন field যোগ, consumer নতুন নামে গেলে তবেই পুরোনোটি সরানো। এই expand-then-contract ধাঁচ database migration-এও একই রকম খাটে।

এখানে Conway-এর সূত্রের (১৯৬৮) প্রতিধ্বনি আছে: সিস্টেমের নকশা প্রতিষ্ঠানের যোগাযোগের কাঠামো অনুসরণ করে। Contract testing একটি প্রযুক্তিগত tool, কিন্তু তার আসল কাজ দলের মধ্যে যোগাযোগকে লিখিত, যাচাইযোগ্য আর সময়মতো করা। দুই দল যদি কথাই না বলে, broker শুধু লাল আলো জ্বালাবে।

Tester-এর ভূমিকা এখানে সেতুর মতো: চুক্তিতে কী থাকা উচিত তা নিয়ে consumer দলকে প্রশ্ন করা (“app কি সত্যিই এটি পড়ে?”), আর provider দলকে মনে করানো যে লাল verification একটি তথ্য, অপমান নয়।

মূল উপলব্ধি: চুক্তি দুই দলের মধ্যে কথোপকথনের লিখিত রূপ; consumer প্রস্তাব করে, provider যাচাই করে, আর পরিবর্তন হয় ধাপে ধাপে।

অনুশীলন

উত্তর দেখার আগে কাগজে নিজে করুন। সব ফল scratch-এ চালিয়ে মেলানো।

  1. চুক্তির নকশা: বাজারঘরের courier service GET /api/orders/{id} ডেকে delivery-র কাজ সাজায়। তার কোড পড়ে: অর্ডারের id, status (শুধু “packed” হলে pickup বসায়), district (১২টি জেলার একটি), আর items-এর প্রতিটির qty (পূর্ণসংখ্যা)। ঠিকানা আর ফোন courier অন্য পথে পায়। চুক্তির প্রতিটি field-এর matching rule বাছুন, একটি provider state-এর নাম দিন, আর বলুন কোন দুটি field ইচ্ছা করে বাদ রাখবেন।
    FieldRuleকারণ
    idintegerশুধু দেখায় আর পরের ডাকে পাঠায়
    statusregex (সাতটি অবস্থা)“packed” দেখে সিদ্ধান্ত নেয়, তাই বানান কড়া
    districtregex (১২টি জেলার code)জেলা দেখে রুট বাছে
    itemseach-like, প্রতিটিতে qty integerঅন্তত একটি পণ্য; শুধু qty পড়ে

    State: “order 7 is packed” (seed-এ অর্ডার ৭ paid; state handler reset-এর পরে admin হিসেবে pack transition চালাতে পারে, যাতে আসল নিয়ম মেনেই অবস্থা আসে)। উদাহরণ মান হিসেবে status “packed”. বাদ: address আর phone (courier পড়ে না), সাথে pricing, history. এগুলো রাখলে provider অকারণে বাঁধা পড়ে। একই অর্ডার এন্ডপয়েন্টে courier-এর চুক্তি আর mobile-এর চুক্তি আলাদা field-এ; provider-এর দায় দুটির যোগফল।

  2. আউটপুট অনুমান করুন: §২-এর checker-এর চারটি rule ($.id integer, $.status সাতটি অবস্থার regex, $.pricing.total integer, $.allowed_actions অন্তত একটি string-এর তালিকা) দিয়ে নিচের চারটি উত্তর যাচাই করলে কোনটিতে কী সমস্যা আসবে? (A) {"id": 7, "status": "refunded", "pricing": {"total": 0}, "allowed_actions": []} (B) {"id": "7", "status": "paid", "pricing": {"total": 1800, "currency": "BDT"}, "allowed_actions": ["pack", "cancel"]} (C) {"id": 7, "status": "paid", "pricing": {"total": 1800.0}, "allowed_actions": ["pack"], "note": null} (D) {"id": 7, "state": "paid", "pricing": {"total": 1800}, "allowed_actions": ["pack"]}

    Scratch-এ চালানো ফল: (A) শুধু $.allowed_actions: [] fails each_like; total ০ বৈধ পূর্ণসংখ্যা, refunded বৈধ অবস্থা। (B) শুধু $.id: '7' fails integer; বাড়তি currency সমস্যা নয়। (C) শুধু $.pricing.total: 1800.0 fails integer; বাড়তি note উপেক্ষিত। (D) $.status: missing key 'status', কারণ নাম বদলে state. শিক্ষা: বাড়তি field কখনো ভাঙায় না; নাম বদল, ধরন বদল আর খালি তালিকা ভাঙায়। একটি সতর্কতা: refunded অর্ডারে আসলেই কোনো action বাকি নেই, তাই খালি তালিকা সঠিক আচরণ। চুক্তির each-like যদি সব অবস্থার জন্য লেখা হয়, তাহলে চুক্তিটিই ভুল; এমন interaction-এ allowed_actions-এর rule হওয়া উচিত শুধু “তালিকা” (type), অথবা আলাদা state-এর আলাদা interaction.

  3. Test-এ ভুল খুঁজুন: একজন সহকর্মী mobile app-এর জন্য নিচের consumer test লিখেছেন। App শুধু delivery আর total পড়ে। কয়টি সমস্যা দেখছেন?
    def test_quote(pact):
        (pact.upon_receiving("quote")
            .with_request("GET", "/api/pricing/quote")
            .with_query_parameter("subtotal", "2000")
            .with_query_parameter("district", "Dhaka")
            .will_respond_with(200)
            .with_body({"subtotal": 2000, "discount": 200, "delivery": 0,
                        "total": 1800, "district": "Dhaka", "plus": False}))
        with pact.serve() as srv:
            r = httpx.get(f"{srv.url}/api/pricing/quote",
                          params={"subtotal": 2000, "district": "Dhaka"})
        assert r.json()["total"] == 1800

    চারটি। (১) উত্তরের সব ছয়টি field চুক্তিতে, অথচ app পড়ে দুটি: provider plus বা district বদলালেও মিথ্যা ভাঙন হবে। (২) সব মান exact, কোনো matcher নেই: চুক্তিতে ব্যবসার নিয়ম (২০০০-এ delivery ০) ঢুকে গেছে, আর provider-এর test data বা নিয়মের যেকোনো বদলে mobile দলের চুক্তি ভাঙবে। ঠিক রূপ: {"delivery": match.int(0), "total": match.int(1800)}. (৩) Test app-এর client (BazarGharClient.quote) চালায়নি, সরাসরি httpx.get করেছে: চুক্তি লেখা হলো, কিন্তু app আসলে কী পাঠায় তা যাচাই হলো না; client-এর district.lower()-এর মতো bug এখানে ধরা পড়ত না। (৪) Description “quote” খুব অস্পষ্ট; broker আর verification-এর বার্তায় এটিই দেখা যাবে, তাই লিখুন “a price quote for 2000 taka in Dhaka”. (চাইলে পঞ্চম: content type ঘোষণা নেই।)

  4. Release-এর সিদ্ধান্ত: Production-এ চলছে mobile 3.0, courier 6.1, api 2.0. Broker-এর matrix: mobile 3.0 × api 2.1 ✓, courier 6.1 × api 2.1 ✗, courier 6.2 × api 2.1 ✓, courier 6.2 × api 2.0 ✓, mobile 3.1 × api 2.1 ✓, mobile 3.1 × api 2.0 ✗. api 2.1 আর mobile 3.1 production-এ নিতে চান। কোন ক্রমে কী deploy করবেন, প্রতিটি ধাপে can-i-deploy-এর উত্তরসহ?

    এখনই api 2.1? না: courier 6.1 × api 2.1 ✗. এখনই mobile 3.1? না: production-এর api 2.0-এর সাথে ✗. তাই আগে courier 6.2: সে consumer, তার provider production-এ api 2.0, আর courier 6.2 × api 2.0 ✓, তাই হ্যাঁ। এবার production: mobile 3.0, courier 6.2, api 2.0. তারপর api 2.1: mobile 3.0 × api 2.1 ✓ আর courier 6.2 × api 2.1 ✓, তাই হ্যাঁ। শেষে mobile 3.1: production-এ api 2.1, আর mobile 3.1 × api 2.1 ✓, তাই হ্যাঁ। ক্রম: courier 6.2 → api 2.1 → mobile 3.1. §৭-এর block-এর matrix আর production বদলে প্রতিটি ধাপ চালিয়ে মেলানো হয়েছে।

নিজেকে যাচাই করুন

ভুল হলে কারণসহ ব্যাখ্যা পাবেন, আবার চেষ্টাও করতে পারবেন।

ক্রমConsumer-driven contract testing-এর ধাপগুলো ক্রমে সাজান (▲▼ চেপে সরান)

  1. Consumer test mock server-এর বিরুদ্ধে আসল client কোড চালায়
  2. সবুজ consumer test থেকে pact ফাইল লেখা হয়
  3. Pact ফাইল consumer-এর version সহ broker-এ প্রকাশ হয়
  4. Provider state বসিয়ে verifier আসল API-তে প্রতিটি request replay করে
  5. can-i-deploy matrix দেখে deploy-এর অনুমতি দেয়

একটি API-র নতুন version উত্তরে একটি নতুন field eta_min যোগ করল, আর কিছু বদলাল না। Consumer-রা tolerant reader নীতি মানে। Consumer-driven contract-এর verification কী দেখাবে?

  • ব্যর্থ, কারণ উত্তর চুক্তির সাথে হুবহু মেলে না
  • পাস
  • শুধু MAJOR version বাড়ালে পাস
  • Provider state না বদলালে ব্যর্থ

একটি চুক্তিতে "delivery"-এর rule integer, উদাহরণ মান 0. Provider-এ একটি bug আছে: ২০০০ টাকার ঢাকার অর্ডারে delivery 0-এর বদলে 60 আসে। Verification-এর ফল কী, আর কেন?

  • ব্যর্থ, কারণ 60 উদাহরণ মান 0-এর সমান নয়
  • ব্যর্থ, কারণ provider state নেই
  • পাস, কারণ rule শুধু ধরন দেখে
  • পাস, কারণ Pact delivery-র নিয়ম নিজে হিসাব করে মিলিয়েছে

Pact-এর চুক্তিতে given("order 6 is placed and belongs to sumi") লেখা। Provider verification-এর সময় এই বাক্যটির কাজ কী?

  • Provider-এর state handler-কে বলে ওই interaction-এর আগে কোন data সাজাতে হবে
  • Consumer test-এর mock server-কে database বানাতে বলে
  • শুধু মানুষের পড়ার জন্য একটি মন্তব্য, কোনো কাজ নেই
  • Request-এ Authorization header যোগ করে

Production-এ চলছে mobile 2.3 আর api 1.0. Broker-এ আছে: mobile 2.4 × api 1.2 যাচাইকৃত; mobile 2.4 × api 1.0-এর কোনো ফল নেই। can-i-deploy mobile 2.4 --to-environment production-এর উত্তর কী?

  • হ্যাঁ, কারণ mobile 2.4 অন্তত একটি api version-এর সাথে যাচাইকৃত
  • হ্যাঁ, কারণ mobile 2.3 আগে থেকেই production-এ সফল
  • হ্যাঁ, কারণ consumer-এর deploy-এ যাচাই লাগে না
  • না, কারণ production-এর api 1.0-এর সাথে যাচাইয়ের ফল নেই

Mobile app উত্তরের status দেখে “এখন পরিশোধ করুন” বোতাম দেখায় কি না ঠিক করে, আর customer_name শুধু পর্দায় দেখায়। চুক্তিতে দুটির জন্য কোন rule সবচেয়ে উপযুক্ত?

  • দুটিই type (যেকোনো string)
  • status বৈধ অবস্থার regex, customer_name type
  • দুটিই exact মান
  • কোনোটিই চুক্তিতে রাখার দরকার নেই

একটি দল provider-এর OpenAPI নথির সাথে consumer-এর pact ফাইল মিলিয়ে সব OK পেল। পরে দেখা গেল আসল API একটি field-এর নাম বদলেছে, নথি বদলায়নি। এই ঘটনা থেকে সবচেয়ে সঠিক শিক্ষা কোনটি?

  • OpenAPI নথি কখনো ব্যবহার করা উচিত নয়
  • Pact ফাইলে আরও বেশি উদাহরণ রাখলেই সমাধান
  • Schema-ভিত্তিক চুক্তি তখনই বিশ্বস্ত, যখন provider-এর আসল উত্তরও সেই schema-র বিরুদ্ধে যাচাই হয়
  • শুধু end-to-end test রাখলেই এমন ভুল আর হবে না

Consumer test-এ Pact-এর mock server district=Dhaka প্রত্যাশা করছিল, কিন্তু client পাঠাল district=dhaka. কী ঘটে?

  • Mock mismatch জানায়, consumer test ব্যর্থ হয়, আর চুক্তি প্রকাশ হওয়ার কথা নয়
  • Mock ছোট-বড় হাতের পার্থক্য উপেক্ষা করে, test পাস
  • Consumer test পাস করে, ভুল ধরা পড়ে শুধু provider verification-এ
  • Mock request-টি আসল API-তে পাঠিয়ে উত্তর এনে দেয়

শব্দকোষ

লেখার মধ্যে ডটেড দাগ দেওয়া শব্দে মাউস রাখুন বা চাপুন — অর্থ দেখাবে। এই পর্বের সব নতুন শব্দ এখানে একসাথে:

মনে রাখুন

  1. Contract test দুই service-কে একসাথে চালায় না; প্রত্যেককে আলাদাভাবে একই লিখিত চুক্তির বিরুদ্ধে যাচাই করে, নিজের দলের build-এ।
  2. Consumer-driven: চুক্তিতে শুধু consumer যা পাঠায় আর পড়ে। বাড়তি field ভাঙায় না; নাম বদল, ধরন বদল আর অনুপস্থিত key ভাঙায়।
  3. Matching rule: সিদ্ধান্তের মান exact বা regex, দেখানোর মান type. ব্যবসার নিয়মের মান চুক্তিতে নয়, functional test-এ।
  4. Consumer test আসল client কোড চালায় আর সবুজ হলে pact ফাইল লেখে; provider verification provider state বসিয়ে প্রতিটি request আসল API-তে replay করে।
  5. Broker ফল আর পরিবেশ মনে রাখে; can-i-deploy চলমান প্রতিটি সঙ্গীর সাথে যাচাই চায়, “ফল নেই” মানে না। Provider আগে, নতুন জিনিস চাওয়া consumer পরে।

পরের পর্বে: পর্ব ৩৩ (Database testing — SQL দিয়ে data যাচাই, migration আর integrity). API-র উত্তর ঠিক থাকলেও ভেতরের data কি ঠিক আছে? বাজারঘরের database-এ SQL দিয়ে integrity যাচাই, migration-এর test আর lost update.

আরও পড়ুন · ABCL TECH-এ আপনার পরবর্তী পদক্ষেপ

এই পর্বটি শেয়ার করুন:
এই পর্বে ভুল পেয়েছেন? জানান