Контрактне тестування і сумісність версій

Що таке контракт між сервісами і навіщо робити його явним?

Контракт — це домовленість про формат обміну на межі двох сторін: споживача (consumer), який викликає API, і постачальника (provider), який його надає. У ній зафіксовано, на які поля й типи у відповіді можна розраховувати, які статуси можливі, які параметри запиту обовʼязкові. Доки домовленість тримається, кожен бік вільний переписувати нутрощі й релізитися незалежно. Біда в тому, що зазвичай вона ніде не записана — розкидана по головах розробників, прикладах зі Swagger і старих інтеграційних тестах. Явним і виконуваним контракт роблять з однієї причини: щоб зміна, яка його порушує, зупинялася в CI автора зміни, а не долітала до проду того, хто нічого не міняв.

Чим контрактне тестування відрізняється від інтеграційного та e2e?

Розрізняє їх обсяг (scope) — кількість реальних компонентів, що працюють одночасно. Контрактний тест свідомо не запускає сервіси разом: кожен бік окремо звіряється зі спільною угодою, тому такий тест дешевий, швидкий і стабільний, але доводить лише збіг форматів. Інтеграційний реально зʼєднує двох сусідів і перевіряє, що вони справді працюють у парі, — за це платиш оточенням. E2e ганяє весь ланцюг (UI, сервіси, БД, зовнішні API) і дивиться на наскрізний бізнес-сценарій очима користувача — це найдорожчий, найповільніший і найбільш флакі рівень. Сильна відповідь одразу називає наслідок: контракту не потрібне спільне оточення, тому він не ловить його гонок; e2e лишають на кілька критичних сценаріїв.

Наведи приклад breaking і non-breaking зміни API.

Non-breaking (зворотно сумісна) — та, після якої старий клієнт працює без правок: додати нове опціональне поле у відповідь, додати новий ендпоінт, додати опціональний параметр запиту, зробити раніше обовʼязкове поле запиту опціональним. Breaking (ламна) — та, після якої клієнт падає або поводиться неправильно: видалити чи перейменувати поле відповіді, змінити тип поля (string на число, обʼєкт на масив), зробити раніше опціональний параметр обовʼязковим, прибрати підтримуваний ендпоінт, звузити валідацію, змінити семантику статус-коду. Критерій «ламна» один: чи покладається на це хтось із живих клієнтів. Слабка відповідь називає «додати поле» безумовно безпечним; сильна одразу згадує, що толерантність клієнта вирішує все.

Чому «додати поле у відповідь» — не завжди безпечна зміна?

Бо вирок «breaking чи ні» виносить не API сам по собі, а пара API плюс його клієнти. Дві найпідступніші пастки. Перша — additionalProperties: false у схемі споживача: клієнт, що забороняє зайві поля своєю JSON-схемою, впаде від будь-якого нового поля, тож для нього «безпечне розширення» — повноцінна breaking-зміна. Друга — нове значення enum: формально це теж розширення (скажімо, зʼявився status: "refunded"), але вичерпний switch по відомих значеннях чи строга валідація enum на невідомому варіанті ламаються. Тому та сама зміна безпечна для толерантного споживача й фатальна для строгого. Практичний висновок для AQA: перш ніж називати зміну безпечною, зʼясуй, як саме клієнт читає й валідує відповідь.

Що таке патерн толерантного читача і закон Постела?

Принцип надійності (robustness principle), він же закон Постела: «будь консервативним у тому, що надсилаєш, і ліберальним у тому, що приймаєш». Його клієнтське втілення — толерантний читач (tolerant reader): бери з відповіді лише потрібні тобі поля, незнайомі пропускай повз, не падай від зайвого. Такий клієнт спокійно переживає розширення API; строго валідуючий — ні. Практичний наслідок: більшість «безпечних» розширень API безпечні тільки для толерантних споживачів, тому, проєктуючи або тестуючи клієнт, варто свідомо не закручувати валідацію відповіді, якщо мета — стійкість до сумісних змін постачальника.

Що таке schema drift і чим він небезпечний?

Schema drift (розсинхрон схеми) — поступове розходження між тим, що обіцяє документація чи угода, і тим, що API віддає насправді. Накопичується він непомітно, дрібними кроками: нове поле поїхало в прод повз специфікацію, формат дати змінили «тимчасово», сервіс під навантаженням почав віддавати null замість обʼєкта. Окремо кожен крок здається невинним, але сумарно специфікація перестає відповідати дійсності — і їй більше не можна довіряти. Небезпека в тому, що незапущена специфікація — це документація, а не контракт: вона тихо бреше, і на неї спираються нові клієнти. Системна страховка проти дрифту — зробити специфікацію виконуваною, тобто валідувати реальні відповіді проти її схем у тестах.

Що таке consumer-driven contract і навіщо він?

Consumer-driven contract (CDC) — підхід, у якому контракт формує споживач, і рівно з того, чим реально користується: не з усієї поверхні API, а з конкретних полів і ендпоінтів, від яких залежить його код. Це знімає з постачальника обовʼязок гарантувати все всім — гарантується лише те, що комусь справді потрібно. Механіка (канонічний інструмент — Pact): тести споживача ходять у mock-провайдер, і з описаних взаємодій народжується pact-файл; постачальник у режимі верифікації програє ці ж запити проти справжнього сервісу. Перейменував чи прибрав щось потрібне споживачу — верифікація червона в його пайплайні ще до релізу. Бонус до відповіді — згадати can-i-deploy як гейт перед деплоєм.

Як механічно працює Pact — крок за кроком?

У два кроки, на двох боках. Бік споживача: тест клієнта ходить не в реальний API, а у вбудований mock-провайдер від Pact; кожна описана взаємодія (запит плюс очікувана відповідь) осідає у pact-файлі (JSON). Тобто контракт — побічний продукт тестів споживача, його не пишуть руками окремо. Бік постачальника: він у режимі верифікації програє записані з pact-файлу запити проти справжнього сервісу й звіряє, чи реальні відповіді вкладаються в контракт. Зазвичай між боками стоїть Pact Broker: споживач публікує туди pact із тегом гілки, вебхук запускає верифікацію постачальника, результат публікується назад. Головне — боки перевіряються окремо, спільне оточення не піднімається.

Що таке матчери в контракті й навіщо вони?

Матчери (matchers) — правила гнучкої звірки: контракт фіксує форму значення (тип, відповідність регулярному виразу, присутність ключа), а не саму величину. Без них контракт червонів би від кожного нового id чи мітки часу, бо живі відповіді щоразу трохи інші. Приклад: асертимо, що total — число, а не що воно дорівнює конкретним 42. Саме матчери відрізняють робочий Pact від наївного порівняння двох JSON. Практичний наслідок: контракт без матчерів — антипатерн; команда швидко починає його ігнорувати або постійно «підганяти» під фактичні дані, і він перестає ловити реальні поломки формату.

Що таке Pact Broker і команда can-i-deploy?

Pact Broker — центральне сховище pact-файлів і звітів верифікації. Він уміє версіонувати контракти по гілках, смикати вебхуки (нова публікація pact запускає верифікацію постачальника) і відповідати на команду can-i-deploy — передрелізний гейт, який дивиться в матрицю сумісності: чи верифікована ця версія споживача проти тієї версії постачальника, що реально стоїть у цільовому оточенні. Саме can-i-deploy перетворює контракти з «ще одних тестів» на справжній запобіжник несумісного релізу: без нього маєш зелені контракти, але не маєш гарантії, що конкретні дві версії сумісні між собою в конкретному оточенні.

Коли consumer-driven підхід не працює і що замість нього?

CDC добре працює, коли ти контролюєш обидва боки (внутрішні сервіси однієї компанії) і споживачів скінченна, відома кількість. Для публічного API з тисячами невідомих клієнтів consumer-driven підхід не масштабується: неможливо зібрати pact-файли від усіх, і незрозуміло, чиї очікування вважати контрактом. Там доречніший провайдер-центричний контракт зі специфікації — валідація проти власної OpenAPI. Тобто вибір інструмента залежить від того, скільки споживачів і чи ти ними керуєш, а не від моди на Pact. Це типове питання «на межу»: сильний кандидат називає саме умову застосовності, а не просто «Pact — це добре».

Що таке валідація проти OpenAPI як полегшений контракт і в чому її межа?

Це односторонній контракт: у тестах звіряти живі відповіді сервісу зі схемами його ж OpenAPI-специфікації. Координувати два боки не треба, брокер не потрібен — специфікація вже існує як джерело істини, лишається змусити її працювати як перевірку. Так ловиться schema drift: момент, коли сервіс розʼїхався з власною обіцянкою. Свідома межа підходу: він нічого не знає про споживача. Такий тест доводить лише, що постачальник вірний собі, — а не що клієнт читає саме ці поля. Якщо поле, на яке хтось спирається, приберуть одночасно з реалізації і зі схеми, валідація лишиться зеленою. Тому це дешевший, але слабший захист, ніж CDC.

Як тестувати сумісність, якщо API все одно мусить змінитися?

Стратегія — не ламати мовчки й не ламати одразу. Три інструменти. Версіонування (versioning): дати старим клієнтам залишитися на v1, поки вони мігрують на v2 (у шляху, у заголовку/типі медіа або в параметрі запиту); ціна — тепер треба підтримувати й тестувати обидві версії. Expand–contract (parallel change): додати нове поряд зі старим (expand), перевести всіх споживачів (migrate), прибрати старе, коли ним ніхто не користується (contract) — жоден живий клієнт не ламається в жодний момент. Deprecation: проміжок між «хочемо прибрати» і «прибрали», просигналений машиночитно заголовками Sunset і Deprecation, із реальним вікном міграції. Погана відповідь — «просто оновимо клієнтів разом»: це і є ламати мовчки й одразу.

Що таке expand–contract (parallel change)?

Дисциплінована альтернатива різкому «зламали й випустили»: ламну зміну розкладають на три кроки. Expand — поряд зі старим полем чи ендпоінтом зʼявляється нове, старе не чіпають; API тимчасово віддає і те, і те. Migrate — усіх споживачів переводять на нове, поки старе ще живе. Contract — старе прибирають, коли підтверджено, що ним уже ніхто не користується. Сенс: старий контракт тримається, доки не піде останній його споживач, тому зламаних клієнтів немає в жодній точці процесу. Той самий прийом знайомий з міграцій БД (додати колонку, переписати читачів, прибрати стару колонку). Для AQA це означає, що кожен із трьох кроків — окрема перевірна точка, а не один великий реліз.

Які заголовки сигналять про deprecation і що з ними перевіряє AQA?

Стандартний машиночитний спосіб — HTTP-заголовки відповіді. Sunset (RFC 8594) — це HTTP-date, після якої ресурс, як очікується, перестане відповідати. Deprecation (RFC 9745) фіксує сам факт застарівання міткою часу у форматі structured-field-дати (@ плюс Unix-час); дата може бути й майбутньою — «застаріє тоді-то». Поруч часто їде Link з rel="deprecation" на гайд міграції. Для AQA тут три перевірки: сигнал узагалі приходить; дата Sunset не «завмерла» в минулому при живому ресурсі; і головне — ресурс справді працює аж до заявленої дати, а не вимкнений наперед. Якщо реального вікна міграції немає — deprecation стає лише ввічливою назвою для ламної зміни.

Чому контрактні тести дають цінність лише як гейт у CI?

Бо контракт ловить несумісність тільки тоді, коли його порушення падає автоматично в пайплайні того, хто зміну вніс, а не при разовому локальному запуску, який легко забути. Типова розкладка: пайплайн споживача проганяє тести клієнта, генерує pact і публікує його в брокер; пайплайн постачальника за вебхуком підтягує нові pact-файли, верифікує їх і публікує результат; гейт перед деплоєм (can-i-deploy) блокує викочування версії, яка ще не верифікована проти того, що зараз у цільовому оточенні. Для полегшеного OpenAPI-варіанта все простіше — валідація відповідей проти специфікації як звичайний тестовий крок. Головний принцип обох: несумісність має падати в пайплайні автора зміни, а не в проді того, хто нічого не міняв.

Що таке двобічні контракти (bi-directional contracts)?

Проміжний варіант між повним Pact і простою валідацією проти OpenAPI. Інструмент звіряє контракт споживача (що він реально використовує) зі специфікацією постачальника (що той обіцяє), не піднімаючи живий сервіс: постачальник публікує свою OpenAPI-специфікацію, споживач — свій набір очікувань, і система перевіряє їх на сумісність статично. Це дешевше за класичну верифікацію (не треба ганяти запити проти реального постачальника), але спирається на те, що специфікація постачальника правдива — тобто сама має бути під валідацією проти реальних відповідей, інакше повертаємось до дрифту. У GraphQL роль такого машиночитного контракту грає сама схема з інтроспекцією.

Три кейси, де контракт вирішує, зелений реліз чи мовчазна поломка інтеграції: таблиця рішень «breaking чи ні» для тієї самої зміни під толерантного й строгого клієнта, полегшений контракт як валідація відповіді проти OpenAPI в Playwright, і перевірка сигналу deprecation (Sunset) як окремого обʼєкта тестування. Скрізь — що дивитися і чому.

Кейс 1. Таблиця рішень: та сама зміна, різний вирок

Команда постачальника прийшла з переліком змін до релізу й питає QA: «що з цього зламає клієнтів?». Пастка в тому, що на половину з них правильна відповідь — «залежить від клієнта». Розберемо кожну зміну двічі: для толерантного читача (ігнорує невідомі поля, читає лише потрібне) і для строгого клієнта (валідує відповідь JSON-схемою з additionalProperties: false, має вичерпний switch по enum).

Що дивитися і чому:

• Перші два рядки — весь сенс теми. «Додати поле» і «додати enum-значення» виглядають як безпечне розширення, але для строгого клієнта це breaking-зміна. Тому питання «non-breaking чи ні» — не до API окремо, а до пари API плюс його клієнти. Перш ніж давати вирок, QA має знати, як клієнт валідує відповідь.
• additionalProperties: false перетворює будь-яке нове поле на червоне. Якщо ви пишете контрактну схему на боці споживача — це свідомий вибір: строгість ловить «таємно дописані» поля (сигнал drift), але робить постачальника заручником вашої схеми. Для полегшеного контракту схему частіше лишають толерантною.
• Рядки, що ламають обох, — безумовно breaking. Перейменування, зміна типу, звуження вхідних вимог, null замість обʼєкта не рятує жодна толерантність. Їх не роблять мовчки — тільки через версіонування або expand–contract.
• Практичний висновок для тесту. Той самий негативний сценарій «строгий клієнт + нове поле» варто мати в наборі окремо: він документує, що ваша сторона поводиться строго, і чому наступне «безпечне» розширення постачальника впаде саме тут.

Кейс 2. Полегшений контракт: валідація відповіді проти OpenAPI

Не завжди варто піднімати всю машинерію Pact. Часто достатньо одностороннього контракту: перевірити, що постачальник не відхиляється від власної OpenAPI-специфікації. Специфікація вже є джерелом істини — лишається зробити її виконуваною й ловити schema drift прямо в тестах.

import { test, expect } from '@playwright/test';
import Ajv from 'ajv';

const ajv = new Ajv({ strict: false });
// userSchema витягнуто з components.schemas.User у openapi.json
const validateUser = ajv.compile(userSchema);

test('GET /users/1 відповідає OpenAPI-контракту', async ({ request }) => {
  const res = await request.get('/users/1');
  expect(res.status()).toBe(200);

  const body = await res.json();
  const ok = validateUser(body);
  // якщо схема не зійшлася — виводимо самі помилки ajv, а не голе false
  expect(ok, JSON.stringify(validateUser.errors)).toBe(true);
});

Строгість схеми — окремий свідомий вибір. Толерантна схема ловить лише зникнення чи зміну типу обовʼязкових полів; строга — ще й «таємно дописані» поля:

// Толерантний варіант: перевіряємо тільки те, на що спираємось.
// required — обовʼязкові поля контракту; зайві поля дозволені.
const tolerantSchema = {
  type: 'object',
  required: ['id', 'total', 'status'],
  properties: {
    id: { type: 'string' },
    total: { type: 'number' },
    status: { type: 'string' }, // enum свідомо не фіксуємо: нове значення статусу не має валити тест
  },
  // additionalProperties за замовчуванням true — нове поле постачальника не валить тест
};

Що дивитися і чому:

• Ловиться саме drift, а не поломка клієнта. Тест підтверджує, що постачальник вірний власній специфікації. Він НЕ знає, чи клієнт читає саме ці поля: прибрати поле, яким хтось користується, специфікація дозволить, якщо його прибрати й зі схеми. Це дешевший, але слабший захист, ніж consumer-driven contract.
• required — серце толерантного контракту. Зникло обовʼязкове поле чи змінився його тип — тест червоний. Зʼявилося нове поле — тест зелений, бо толерантний читач переживе розширення. Саме так контракт не падає від кожного невинного додавання.
• additionalProperties: false вмикають свідомо. Для полегшеного контракту частіше лишають толерантність; строгість беруть, коли «таємно дописане поле» — це саме той сигнал drift, який треба ловити.
• Це звичайний тестовий крок у CI. Він падає, щойно живий сервіс розійшовся зі своєю схемою, — без брокера, без координації сторін. Головне — щоб несумісність упала в пайплайні того, хто її вніс.

Кейс 3. Deprecation як обʼєкт тестування: сигнал і живий ресурс

Ламну зміну не роблять мовчки. Коли ендпоінт застаріває, постачальник має просигналити машиночитно й лишити реальне вікно міграції. Для QA це готовий обʼєкт перевірки: чи взагалі приходить сигнал, чи не «завмерла» дата Sunset у минулому, і — найважливіше — чи ресурс справді ще працює до заявленої дати, а не вимкнений наперед.

HTTP/1.1 200 OK
Deprecation: @1688169599
Sunset: Thu, 31 Dec 2026 23:59:59 GMT
Link: <https://api.example.com/docs/migrate-v2>; rel="deprecation"

import { test, expect } from '@playwright/test';

test('застарілий /v1/orders ще живий і чесно сигналить про deprecation', async ({ request }) => {
  const res = await request.get('/v1/orders');

  // 1) ресурс НЕ вимкнений наперед: deprecation — це ще не видалення
  expect(res.status()).toBe(200);

  // 2) сигнал застарівання взагалі приходить
  const sunset = res.headers()['sunset'];
  expect(sunset, 'немає заголовка Sunset — застарівання не просигналене').toBeTruthy();

  // 3) дата Sunset не «завмерла» в минулому — вікно міграції ще відкрите
  const sunsetDate = new Date(sunset);
  expect(sunsetDate.getTime(), 'Sunset у минулому, а ресурс ще віддає 200').toBeGreaterThan(Date.now());
});

Що дивитися і чому:

• 200 тут — не формальність, а суть. Deprecation — це проміжок між «хочемо прибрати» і «прибрали». Якщо ресурс уже віддає 404/410 до дати Sunset — його вимкнули наперед, і це breaking-зміна з ввічливою назвою. Тест саме на це й стоїть на сторожі.
• Sunset у минулому — окремий баг. Дата, що вже минула, поки ресурс живий, означає розсинхрон між обіцянкою й реальністю: або забули вимкнути, або забули посунути дату. Обидва варіанти вартують розмови з командою.
• Заголовок Deprecation — про факт, Sunset — про дедлайн. Deprecation (RFC 9745) каже «це застаріло» з міткою часу; Sunset (RFC 8594) — «після цієї дати, як очікується, перестане відповідати». Перевіряти варто обидва: сигнал без дати не дає вікна міграції, дата без сигналу губиться.
• Це не UI-, а контрактна перевірка. Вона живе в API-наборі й падає, тільки-но постачальник поводиться з deprecation недисципліновано, — задовго до того, як реальний клієнт отримає undefined замість замовлення.

Контракт як межа між сервісами

• Можу пояснити, що контракт — це узгоджений формат запиту й відповіді на межі споживач (consumer) / постачальник (provider), і поки він тримається, боки деплояться незалежно.
• Розумію, чому контракт майже завжди неявний (живе в голові, у Swagger-прикладі, у старому тесті) і чому його цінність зʼявляється лише тоді, коли порушення падає в CI, а не в проді.
• Знаю, що таке schema drift і чому незапущена специфікація — це документація, а не контракт.

Breaking vs non-breaking

• Знаю типові non-breaking зміни (нове опціональне поле, новий ендпоінт, опціональний параметр, послаблення валідації) і breaking (видалити/перейменувати поле, змінити тип, зробити параметр обовʼязковим, звузити валідацію).
• Розумію головний принцип: «breaking чи ні» визначає пара API + клієнти, а не API окремо.
• Можу пояснити дві пастки «non-breaking»: additionalProperties: false у схемі споживача (нове поле валить валідацію) і нове значення enum (ламає вичерпний switch чи строгу валідацію).
• Знаю патерн толерантного читача (tolerant reader) і закон Постела: консервативний у тому, що надсилаєш, ліберальний у тому, що приймаєш.

Версіонування і deprecation

• Знаю три способи версіонування REST (у шляху /v1/, у заголовку/типі медіа, у параметрі ?version=) і компроміс кожного.
• Можу пояснити expand–contract (parallel change): expand → migrate → contract, і чому в кожен момент жоден живий клієнт не зламаний.
• Знаю сигнали deprecation — Sunset (RFC 8594, дата виведення ресурсу) і Deprecation (RFC 9745, факт застарівання з міткою часу) — і що перевіряє AQA: чи приходить сигнал, чи не «завмерла» дата Sunset у минулому, чи ресурс живий до заявленої дати.

Рівні тестів: контракт / інтеграція / e2e

• Можу пояснити різницю за обсягом (scope): контракт не піднімає боки разом, інтеграційний зʼєднує двох реальних сусідів, e2e ганяє весь ланцюг.
• Розумію силу й межу контракту: дешевий і стабільний без спільного оточення, але доводить лише збіг форматів — тому не замінює e2e, а зменшує потребу в ньому.

Consumer-driven contracts (Pact)

• Розумію ідею CDC: контракт визначає споживач із того, що реально використовує, а не вся поверхня API.
• Знаю механіку Pact у два кроки: споживач пише pact проти mock-провайдера → постачальник верифікує той самий pact проти реального сервісу.
• Можу пояснити, навіщо матчери (звіряють форму — тип, регекс, наявність ключів — а не точні значення на кшталт конкретного id).
• Знаю роль Pact Broker і команди can-i-deploy як гейта, що звіряє матрицю сумісності версій перед деплоєм.
• Розумію межу CDC: працює, коли контролюєш обидва боки й споживачів мало; для публічного API не масштабується.

OpenAPI-валідація і пайплайн

• Можу пояснити валідацію проти OpenAPI як полегшений односторонній контракт, що ловить schema drift без брокера й координації, і її межу: не знає про споживача — підтверджує, що постачальник вірний собі, але не те, що клієнт читає саме ці поля.
• Знаю, що таке двобічні контракти (bi-directional): звірка контракту споживача зі специфікацією постачальника без живого сервісу.
• Розумію головний принцип пайплайну: несумісність має падати в пайплайні того, хто її вніс, а не в проді того, хто нічого не змінював.