Келісімшарттық тестілеу

1) Келісімшарттарды қайда қолдану керек

HTTP REST/JSON: ресурстар, пагинация, сүзгілер, теңсіздік, қате кодтары.
gRPC/Protobuf: хабарлар түрлері, мәндер, семантика 'deadline', backward-compat в.proto.
GraphQL: сызбалар, non-null, директивалар, өрістерге ауыстырылған.
Хабарламалар/ағындар (Kafka/Pulsar/SQS): event-схемалар (Euro/JSON/Protobuf), партияландыру кілттері, тәртіп, демпотенттік кілттер.
Ішкі SDK/кітапханалар: көпшілік функциялары/ерекшеліктері/өнімділік келісімшарттары.

2) CDC моделі: рөлдер мен артефактілер

Тұтынушы күту келісімшартын (болжамды сұраулар/жауаптар, типтердің матчерлері, инварианттар) жариялайды.
Өнім беруші өзінің сервисіне/адаптеріне/handler 's қарсы келісімшарттарды верификациялауды айдап жібереді.
Келісімшарттар брокері (Pact Broker/Backstage/артефакт-репо) нұсқаларын, тегтерін ('prod', 'staging', 'canary') және үйлесімділік матрицасын 'consumer @v → provider @v' сақтайды.
Босату саясаты: егер кез келген «прод-релевантты» келісімшарт бұзылса, провайдердің депласы тыйым салады.

3) Келісімшартта не белгілеу керек (HTTP мысал)

• Әдіс/жол/параметрлер/тақырыптар (auth, теңсіздік кілті қоса).
• Дене және типтік матчерлер (түрі/форматы/регэксп/диапазондары).
• Қателердің кодтары мен құрылымы; тұрақты 'error _ code'.
• Семантикалық инварианттар: сұрыптау, бірегейлік, біркелкілік 'created _ at'.
• Функционалдық емес күтулер (қосымша): p95, өлшем лимиттері, rate-limit тақырыптары.

json
{
"interaction": "GET /v1/users/{id}",
"request": { "method": "GET", "path": "/v1/users/123", "headers": {"Accept":"application/json"} },
"matchers": {
"response.body.id": "type:number",
"response.body.email": "regex:^.+@.+\\..+$",
"response.body.created_at": "format:rfc3339"
},
"response": {
"status": 200,
"headers": {"Content-Type":"application/json"},
"body": {"id": 123, "email": "alice@example.com", "created_at": "2025-10-31T12:00:00Z"}
},
"error_cases": [
{
"name":"not_found",
"request":{"path":"/v1/users/9999"},
"response":{"status":404, "body":{"error_code":"USER_NOT_FOUND"}}
}
]
}

4) Оқиғаларға арналған келісімшарттар (event-driven)

Оқиға схемасы: 'type', 'version', 'id', 'occurred _ at _ utc', 'producer', 'subject', 'payload'.
Инварианттар: 'id' өзгермейтіндігі және '(type, id)' бойынша теңсіздігі, партия кілті шегіндегі тәртіп, 'sequence' біркелкілігі.
Schema Registry: эволюцияны және үйлесімділік ережелерін сақтайды (backward/forward/full).
Келісімшарт-тесттер: «алтын» оқиғалар мен негативтер фазалары (белгісіз өрістер, nullable) репликаланады.

json
{
"type":"record","name":"UserRegistered","namespace":"events.v1",
"fields":[
{"name":"id","type":"string"},
{"name":"occurred_at_utc","type":{"type":"long","logicalType":"timestamp-millis"}},
{"name":"email","type":"string"},
{"name":"marketing_opt_in","type":["null","boolean"],"default":null}
]
}

5) Эволюция және үйлесімділік

Келісімшарттардың нұсқалары: MAJOR семантикасы. MINOR. PATCH '(MAJOR - бұзатын).

• Өрістерді жоймаңыз, 'error _ code' түрін/мәнін өзгертпеңіз.
• Дефолтпен қосымша өрістер қосыңыз; «сиқырдың» орнына жаңа эндпоинттер.
• Депрекация: хабарландыру, қатар қолдау, өлшемдер бойынша алып тастау.
• GraphQL: тек өрістерді қосу, non-null фазалар арқылы енгізу; депрекация директивалары.
• gRPC/Proto: өріс нөмірлерін қайта пайдаланбау; Тек optional бағдарламасымен жаңасын қосу.
• Events: 'vN' сұлбасы; консьюмерлер белгісіз өрістерді елемеуге міндетті.

6) Теріс және инвариантты тексерулер

Negative: дұрыс емес түрлері, тыйым салынған мәндер, қайшылық параметрлері, шектен асып кетуі.
Invariants: жауаптарды сұрыптау, 'id' бірегейлігі, 'next _ cursor' дұрыстығы, қайталау кезіндегі теңсіздік жауабының тұрақтылығы.
Уақытша аспектілердің келісімшарттары: 'created _ at' RFC3339/UTC, жергілікті тәуліктің дұрыс проекциясы көліктік келісімшарттың бөлігі болып табылмайды - бизнес-инварианттарға шығарылады.

7) Стаб-генерация және жергілікті әзірлеу

Келісімшарттардан тұтынушыны әзірлеу үшін провайдер стаптары жинақталады.
Оқиғалар үшін - схема бойынша «валидті/шекаралық» хабарламалардың генераторлары.
Қатарлар келісім-шарттың нұсқасымен және құрастыру күнімен белгіленеді; өнімде жариялауға тыйым салынады.

8) CI/CD (референс-пайплайн) кірістіру

1. Consumer CI:

Линт/құрастыру → келісімшарттарды генерациялау → юнит/келісімшарт-тестілер → contract-broker (tag: 'consumer @ 1. 7. 0`).

2. Provider CI:

Сервисті жергілікті/контейнерде көтеру → релевантты келісімшарттар фетч ('prod '/' staging') → верификация → мәртебені broker-де жариялау.

3. Release Gate:

Егер орындалмаған келісімшарттар болса, провайдердің депласы бұғатталады.

4. Nightly Matrix:

'consumer versions × provider versions' сыйысымдылық матрицасы; есептер мен дабылдар.

9) Домендер бойынша практика мысалдары

9. 1 REST: курсормен пагинация (келісімшарттық инвариант)

Жауабында 'items []', 'next _ cursor' (nullable), 'limit', 'total' (қосымша) бар.
Инварианттар: 'len (items) ≤ limit', сол 'cursor' → іспеттес жиынтығымен қайта шақыру.
Егер 'cursor' және 'page' бір уақытта берілсе, қате пайда болды.

9. 2 POST ұқсастығы

Келісімшарт «Idempotency-Key» тақырыбын талап етеді.
Инвариант: сол кілтпен қайта сұрау сол 'id '/мәртебені қайтарады.

9. 3 Оқиғалар: тәртіп кепілдіктері

Келісімшарттағы партияландыру кілті: 'partition _ key = user_id'.
Инвариант: 'sequence' кілттің ішінде біркелкі өседі; консьюмер қайталауларды өңдеуге міндетті.

10) Келісімшарттардағы қауіпсіздік және құпиялылық

ПДн/құпияларды мысалдарға қоспау - тек синтетика.
'Authorization', 'X-Signature', 'Replay-Prevention' деген міндетті қауіпсіздік тақырыптарын тіркеу.
Вебхуктар үшін - '2хх '/ретрайлардың қол қою және жауап беру келісімшарты.
Тест-келісімшарттарда - сезімтал алаңдарды бүркемелеу.

11) Құралдар

Pact/Pactflow/Pact Broker - HTTP/Message келісімшарттары, сыйысымдылық матрицасы.
OpenAPI/AsyncAPI - спецификациялар + тест-генераторлар (Dredd, Schemathesis).
Karate/REST Assured - REST келісімшарттарын сценарийлік тексеру.
Protobuf/gRPC - 'buf', 'protolint', сыйысымдылық тестілері; Ағындардағы Euro/JSON/Proto үшін Schema Registry.
GraphQL (graphql-compat) үшін Conformance-тесттер, snapshot схемалар тесттер.

12) Провайдерді тексерудің жалған құжаты (оңайлатылған)

python def verify_contract(provider, contract):
for case in contract["cases"]:
req = build_request(case["request"])
res = provider.handle(req) # локально/контейнер assert match_status(res.status, case["response"]["status"])
assert match_headers(res.headers, case["response"].get("headers", {}))
assert match_body(res.body, case["matchers"], allow_extra_fields=True)
for neg in contract.get("error_cases", []):
res = provider.handle(build_request(neg["request"]))
assert res.status == neg["response"]["status"]
assert res.json.get("error_code") == neg["response"]["body"]["error_code"]

13) Қарсы үлгілер

«Postman скриншоттары - бұл келісімшарт»: нұсқалар/типтік матчерлер/автоматты валидация жоқ.
Оверснейпинг: келісімшарт типтердің/паттерндердің орнына нақты мәндерді белгілейді → жалған құлдыраулар.
Әртүрлі өңірлер/арналар үшін бір ортақ келісімшарт: вариативтілікті елемейді (жалаулар, geo-ережелер).
Брокерсіз/матрицасыз келісімшарттар: қандай нұсқалар үйлесімді екенін түсіну мүмкін емес.
Келісімшарттардың орнына e2e мөлшерлеме: баяу, қымбат, тұрақсыз.
Теріс/инвариантты кейстердің болмауы: тек «жасыл жол» тестіленеді.

14) Бақылау және пайдалану

Мәртебені broker + дашборд «health келісімшарттарына» экспорттау.
Тәуекелдер: провайдердің 'prod' келісімшарттарына қарсы жаңа құлдырауы, оқиғаларда «unknown field» өсуі.
Тексеру логындағы 'contract _ id', 'version', 'decision _ id'.

15) Депрекация процесі

1. Өрісті/ендпоинтті қосу (бұзбайды).
2. Ескісін спецификацияда 'deprecated' деп белгілеу, мерзімін жариялау.
3. Тұтынушыларды логтар/брокер бойынша қадағалау; көші-қон гайдтары.
4. Стейджде «көлеңкелі» deny қосу (dry-run), содан кейін enforce.
5. Нөлдік пайдалану үлесінен кейін және сыйысымдылық расталғаннан кейін жою.

16) Сәулетшінің чек-парағы

1. Тұтынушылар мен олардың иелері анықталды ма? Келісімшарттар нұсқаланады ма?
2. Ортаның тегтерімен үйлесімділігі бар ма?
3. Келісімшартқа негативтер мен инварианттар (идиемпотенттілік, курсорлар, сұрыптау) кірді ме?
4. Оқиғалар үшін Schema Registry және сыйысымдылық режімі теңшелді ме?
5. Пайплайн прод-келісімшарттар бұзылған кезде провайдердің шығарылымын бұғаттай ма?
6. Депрекация процесі мен эволюция саясаты сипатталды ма?
7. Келісімшарттардан қатарлар пайда болады, оқиғаның жергілікті генераторлары бар ма?
8. ПД бүркемелеу және міндетті қауіпсіздік тақырыптары құжатталған ба?
9. Келісімшарттар бойынша метриктер/алерттар қосылған, дрифт бойынша есептер бар ма?
10. Келісімшарттар СІ-де екі тараптан да (consumer және provider) тексеріледі ме?

Қорытынды

Келісімшарттық тестілеу өзара іс-қимыл туралы «ақиқатты» нұсқаланатын артефактілерге көшіреді және интеграцияны болжауға болады. CDC, келісім-шарт брокері және схемалар эволюциясының тәртібі басқарылатын процеске «сындыратын тосын сый» ауыстырады: жылдам тексерулер, айқын инварианттар және нұсқалардың мөлдір үйлесімділігі. Бұл e2e құнын төмендетеді, релиздерді жылдамдатады және бүкіл платформаның сапасын жақсартады.