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

1) Неге келісімшарттық тестілеу

Келісімшарт клиенттің күтулерін және провайдердің уәделерін белгілейді: маршруттар/әдістер, тақырыптар, дене сызбалары, мәртебелер, қателер семантикасы және шектеулер. Мақсаты - интеграцияға дейін үйлеспейтін өзгерістерді ұстау және нұсқаларын қауіпсіз, ауыр E2E шығармай шығару.

2) Тәсілдер

Consumer-Driven Contracts (CDC): клиент күтулерді қалыптастырады (Pact және аналогтар); провайдер оларды үнемі верификациялайды.
Спецификациялық: келісім-шарт ақиқаттың бірыңғай көзі ретінде (OpenAPI/Protobuf/GraphQL SDL); тестілер спецификацияға қарсы іске асыруды валидациялайды.
Оқиғалық: хабарламалар схемасы (Euro/JSON Schema/Protobuf) + брокер/тізілімдегі үйлесімділік қағидалары.

3) HTTP/REST: спецификациялық ағын

1. Келісім-шарт: OpenAPI 3. x (схемалар, мысалдар, кодтар).
2. Линт және статанализ: стиль, міндетті өрістер, бірыңғай кодтар.
3. Іске асыруды валидациялау: OpenAPI-ге қарсы тест генераторы (schemathesis/Dredd-тәсіл) + қол негативтері.
4. Снапшоттар: жауап мысалдарын, ETag семантикасын, іспеттілік тақырыптарын жазыңыз.

yaml paths:
/v1/payments:
post:
responses:
"201": { $ref: "#/components/responses/PaymentCreated" }
"409": { description: Duplicate by Idempotency-Key }
"422": { description: Schema/Business validation failed }

4) CDC (Pact-тәсіл)

1. Consumer тест жазады, pact-файлын қалыптастырады (күту).

2. Брокерге жариялау (артефакт).

3. Provider CI-де сервисті (немесе келісімшарт бағанын) көтереді, pact 'терін тексереді.

4. Брокер can-i-deploy үйлесімділік матрицасын есептейді.

js pact
.given("wallet exists")
.uponReceiving("get wallet")
.withRequest({ method:"GET", path:"/v1/wallets/w123", headers:{ "Authorization": term({generate:"Bearer x", matcher:/^Bearer\s.+/}) }})
.willRespondWith({
status: 200,
headers: { "Content-Type": "application/json" },
body: like({ id:"w123", currency: "EUR", balance: 0 })
});

5) gRPC/Protobuf келісімшарттары

Келісімшарт - пакеттерді/қызметтерді нұсқалаумен '.proto'.
Сыйысымдылық: тегтерді қайта пайдаланбаңыз, тек optional-мен жаңаларын қосыңыз, пайдаланылатын өрістерді жоймаңыз; нөмірлерді сақтау.
Тесттер: сервер/клиент тұрақтылығын генерациялау, автогенерленген кейстерді прокаттау + негативтер (unknown fields, size-limits).

6) Оқиғалық келісімшарттар (Kafka/NATS/...)

Схемы: Avro/JSON Schema/Protobuf в Schema Registry.
Сыйысымдылық саясаты: 'BACKWARD' (көбінесе жеткілікті) немесе 'FULL'.
Продьюсер тестілері: хабарламаны схемаға қарсы валидациялайды; консьюмер тестілері: ескі және жаңа нұсқасын қабылдайды.
Инварианттар: ұқсастық кілттері, тәртібі/қайталануы, дедупликация семантикасы.

json
{"type":"record","name":"PayoutCreated","fields":[
{"name":"payoutId","type":"string"},
{"name":"amount","type":"double"},
{"name":"currency","type":{"type":"string","logicalType":"iso-4217"}}
]}

7) Үйлесімділік және нұсқалар

Backward-compatible (ұсынылатын минимум): міндетті емес өрістерді қосыңыз, бар өрістерді бұзбаңыз.
Forward-compatible: тұтынушылар белгісіз өрістерді елемейді.
Full: екеуі де.
Нұсқалау: 'path (/v1)', 'Accept: application/vnd. brand. v2+json`, `proto package v2`.
Deprecation-саясат: тақырыптарды/оқиғаларды ескертетін шығару терезесі (мысалы, 90 күн).

8) Теріс және қателер - бұл да келісімшарт

400/401/403/404/409/422/429/5xx кодтарын стандарттаңыз, міндетті өрістер 'code', 'message', 'trace _ id'.
Мөлшері/лимиттері - келісімшарттың бір бөлігі (413/414/431).
Теңсіздік: қайталау кезіндегі мінез-құлық (409 vs 201 same id).
Тақырыптар: 429/503 кезінде 'Retry-After', 'Idempotency-Key', 'Content-Language' және т.б.

json
{ "code":"validation_error", "message":"amount must be ≥ 1", "trace_id":"..." }

9) Деректерді келісімшарт басқарады

Мысалдар/өлшемдік жауаптар (examples) - тірі, CI-де валидацияланады.
CDC үшін фикстуралар - ең аз, детерминацияланған.
Деректер генерациясы - сандар/күндер үшін property-based; бірақ снапшоттардың тұрақтылығын бұзбау керек.

10) Пайплайн в CI/CD (референс)

1. Lint/validate: OpenAPI/Proto/Avro (`validate`, style-линер).
2. Publish: келісімшарт артефакт ретінде (брокер/тізілім).
3. Verify: Провайдер CDC пакеттерін/спецификациялық тесттерді жібереді.
4. can-i-deploy gate: жасыл матрицасыз шығаруға тыйым салынады.
5. Diff: өзгерістердің үйлесімді екенін тексеру (semantic diff).
6. Есеп: JUnit/HTML, бұзушылықтар/дефинициялар тізімі.

yaml jobs:
lint:...
publish-contract: needs: [lint]
verify-provider: needs: [publish-contract]
can-i-deploy:
if: always()
steps: [run: pact-broker can-i-deploy...]

11) Құралдар (міндеттер класы бойынша)

Линт/валидаторлар: openapi-linters, protobuf-lint, euro-tools.
CDC: Pact-отбасы/брокер, Spring Cloud Contract, Hoverfly (HTTP жазбалар/репликалар).
Спецификациялық раннерлер: schemathesis/Dredd-ұқсас тәсіл, Postman test + JSON Schema.
Diff: semantic-diff OpenAPI/Proto/Euro (breaking-өзгерістерді анықтайды).
Контейнерлер: Testcontainers провайдерді/келісім-шарттарды көтеруге арналған.

12) Антипаттерндер

«Арнайы док» кодтан бөлек → рассинхронизация. Келісімшартты сервистің жанында сақтаңыз.
Келісімшарттың орнына бөгде сервистің моктері → апдейт кезіндегі морт.
Кездейсоқ жауаптар/сұлбаға байланыссыз генерация → флейка.
Нұсқасыз өрістердің түрлерін/міндеттілігін өзгерту.
Ескертусіз/депрекациясыз Silent-кеңейтулер.
Теріс келісімшарттар мен қателер кодтарының болмауы.

13) iGaming/Қаржы ерекшелігі

Ақша өрістерін ресімдеңіз: 'amount' - масштабы бар decimal, валюта - ISO-4217, сомалардың инварианттары.
Төлем/вебхук келісімшарттары: HMAC/mTLS, anti-replay ('X-Timestamp' терезе), демпотенттілік, 'Retry-After'.
Аймақтық/тенанттар: 'X-Tenant/X-Region' деген міндетті тақырыптар, хабарларды оқшаулау.
Оқиғалар: өзгермейтін журналдар (audit), дедупликация кілттері, жеткізу кепілдіктері (at least once + демпотенттік хендлерлер).

14) Тест «скелеттерінің» үлгілері

14. 1 Schemathesis-стиль (псевдо)

bash schemathesis run openapi. yaml --checks all --hypothesis-deadline=200

14. 2 Postman спецификациялық раннер ретінде

js pm. test ("Scheme/v1/wallets/{ id} is valid," () => {
const schema = pm. collectionVariables. get("wallet_get_schema");
pm. expect(ajv. validate(JSON. parse(schema), pm. response. json())). to. be. true;
});

14. 3 Provider-CDC тексеру (жалған)

bash pact-broker can-i-deploy --pacticipant wallets --version $SHA --to-environment staging

15) Prod-дайындық чек-парағы

• Репозиторийдегі келісімшарттар, CI артефактілерді валидациялайды және жариялайды.
• CDC күрделі интеграциялар үшін қосылған; broker/matrix «can-i-deploy» жұмыс істейді.
• Үйлесімділік саясаты (HTTP/gRPC/Events) құжатталған; автоматты semantic-diff.
• Теріс келісімшарттар: қателер, өлшем лимиттері, іспеттілік, 'Retry-After'.
• Тест-деректер детерминацияланған; үлгілердің қармауыштары қолдау табады.
• Нұсқалау және deprecation: мерзімдер, хабарламалар, тақырыптар.
• Оқиғалар үшін - Schema Registry және сыйысымдылық режимі; продьюсер/консьюмер екі нұсқаны да тестілейді.
• Артефакттар: JUnit/HTML, diff/verify есептері, үйлесімділік матрицасы.
• Инцидент-рәсім: тез rollback келісімшарт/фича-жалауы, интеграторларға хабарлама.

16) TL; DR

Келісімшарттардағы күтулерді белгілеңіз және оларды автоматты түрде: клиенттік күтулерге арналған CDC, іске асыруға сәйкес келетін спецификациялық тесттер, оқиғалар үшін схемалар тізілімі. Қатаң үйлесімділік саясатын және теріс келісімшарттарды (қателер, лимиттер, іспеттілік) ұстаңыз. Жасыл can-i-deploy матрицасыз және semantic-diff breaking-өзгерістерсіз шығаруға болмайды.