Стабільність API-тестів: флак, асинхронність, дебаг

Що таке флак (flaky test) і чому на рівні API він особливо підступний?

Флак — це тест із недетермінованим результатом: код не змінювався, а прогін то червоний, то зелений, і перезапуск «лікує» без жодної правки. В API-тестах це підступніше, ніж в UI: візуального шару немає, збоку кожен фейл схожий на звичайний HTTP-запит, що чомусь не вдався, — тож падінню легко не повірити, списати все на мережу й натиснути Retry. Насправді за таким падінням стоїть або справжня гонка в самому продукті, або те, що тест неправильно дочікується стану системи. Тому перший крок при флаку — не правити тест навмання, а чесно визначити причину.

Назви основні джерела флаку API-тестів.

Канонічний перелік джерел недетермінізму — брак ізоляції, асинхронність, віддалені сервіси, час і витоки ресурсів; на рівні API вони збираються у чотири практичні групи, кожна з характерним почерком. Дані — тест читає не той стан, на який розраховував: спільний запис хтось змінив чи видалив, або передумова, на яку він спирається, вже не виконується (колізії та хибні передумови). Гонки (асинхронність) — читання випереджає асинхронний запис: щойно створене ще не видно, сервер відповідає 202 замість очікуваного 201, послідовність кроків нестабільна. Оточення — фейли прив'язані до місця, а не до коду: тільки в CI, тільки на спільному стенді, тільки під навантаженням (мережа, сусіди, залежні сервіси). Ліміти — раптові 429, обірвані з'єднання й таймаути, коли сюїта біжить паралельно. Дані й гонки — споріднена пара: обидва класи про стан, але перший — про те, чий він, а другий — про те, коли він настане. І варто памʼятати, що чотирма групами перелік не вичерпується: час і витоки ресурсів у них не вкладаються, хоч у канонічному переліку вони є.

Тест створює запис і одразу його не бачить. Поставиш sleep?

Ні — це класична пастка на розуміння асинхронності. Фіксована пауза не масштабується: на завантаженому агенті її не вистачить і флак повернеться, на швидкому стенді вона лише марно розтягне прогін. Спершу варто з'ясувати, синхронна операція чи асинхронна: 201 — ресурс уже створено, 202 — запит лише прийнято в обробку. Якщо операція асинхронна, тактик дві: краща — колбек, коли асинхронний сервіс сам повідомляє про завершення (для цього потрібні і відповідне оточення, і готовність постачальника сервісу), а доступніша — полінг (polling): повторювані читання, що зупиняються, щойно система показала потрібний факт, але не пізніше за верхню межу часу. Орієнтир — спостережувана умова, а не відлік секунд.

Що робить полінг надійним?

Три речі. Перше — умова замість часу: ціль полінгу — конкретний факт (потрібний статус-код, значення поля, елемент у списку), а не «почекати трохи». Друге — верхній таймаут: без стелі полінг, що не дочекався умови, висітиме вічно, а завислий тест гірший за той, що чітко впав із діагнозом. Стелю при цьому ставлять дуже високою — це запобіжник на випадок серйозної поломки, а не бюджет часу; і часові значення не лишають літералами в коді, а виносять у константи чи налаштування оточення. Третє — ідемпотентна перевірка: код усередині циклу мусить лише читати; потрапить туди POST — кожна ітерація створюватиме новий запис. Принцип: тест рушає далі в мить, коли факт настав, а фейлиться лише тоді, коли факту немає непристойно довго.

Які запити можна безпечно ретраїти й чому?

Лише безпечні (safe) та ідемпотентні: GET, HEAD, а також PUT і DELETE — їхній повтор за наміром семантики лишає систему в тому самому стані (а дотримання цього наміру лежить на сервері, тож у конкретному API це перевіряють). Сліпий повтор POST натомість множить сутності: замовлення чи платіж з'явиться двічі; PATCH ідемпотентним теж не гарантований, хоч про нього забувають частіше. Якщо POST треба вберегти від повтору, це відповідальність продукту (механізм Idempotency-Key), а не тесту. Правило просте: ретрай не має змінити стан системи інакше, ніж змінив би єдиний успішний запит.

На які збої ретрай легітимний, а на які — ні?

Легітимно повторювати запит після транзієнтного збою: розірвалося TCP-з'єднання, не відповів DNS, балансувальник віддав 503 посеред деплою — це минуща інфраструктурна негода, а не рішення застосунку. А от повтор запиту, на який продукт свідомо відповів помилкою — 500 від незловленого винятку, 409 від реальної гонки, 400 від невалідних даних — просто ховає дефект від очей. Межа проходить не по бажанню бачити зелене, а по природі збою: шум транспорту ретраїмо, осмислену відмову застосунку — фіксуємо як результат.

У чому класична пастка ретраю на рівні клієнта?

У тому, що мережевий збій і бізнес-помилка приходять різними каналами. Обрив з'єднання чи DNS-таймаут кидається як виняток, а 500 від застосунку — це коректно доставлена відповідь, на яку HTTP-клієнт винятку не кине. Наївний ретрай «повторюємо на будь-якій проблемі» почне мовчки ретраїти й 500, і 409, ховаючи справжній баг. Тому клієнтський ретрай будують на try/catch навколо запиту — реагують на кинуті збої транспорту, а статус-коди відмови продукту лишають тесту як результат, який він зобов'язаний побачити.

Чим небезпечний ретрай усього тесту на рівні ранера?

Ретрай тесту (у Playwright — retries у конфізі) — прийнятна тимчасова страхувальна сітка, але в нього є ціна: тест, що позеленів лише з другої спроби, — це сигнал нестабільності, який щойно заглушили. Якщо такі flaky pass не рахувати окремо й не відправляти в карантин, прогін виглядає здоровим, хоча всередині живе гонка або хитке оточення — третина тестів проходить із другого разу, і ніхто цього не бачить. Тож ретрай — спосіб пережити те, що ти вже дослідив і свідомо визнав транзієнтним, а не спосіб не розбиратися.

Що таке correlation id і навіщо він у дебагу API-флаку?

Після падіння UI-тесту лишаються скріншоти й відео; в API-тесту з доказів — сама лише відповідь, а справжня причина зазвичай на боці сервера. Correlation id (він же request id) — унікальний ідентифікатор, що супроводжує один запит через усі сервіси й потрапляє в кожен рядок логу. Робочий прийом у тесті: взяти id з відповіді або самому проставити його заголовком, а тоді вписати в повідомлення асерту й у звіт. Після фейлу не доводиться гадати — у логах шукаєш за точним ключем, і grep за одним id віддає весь слід запиту. Без цієї нитки дебаг деградує до «перезапущу й подивлюся».

Чим X-Request-Id відрізняється від traceparent (W3C Trace Context)?

Це два рівні однієї ідеї. X-Request-Id чи X-Correlation-Id — домовленість усередині команди: заголовок не стандартизований, імена в різних проєктах різні, id сервіс призначає сам і кладе у власні логи. traceparent описаний специфікацією W3C Trace Context, тому його однаково читають різні трейсинг-системи, і саме він несе ідентифікатор трейсу через межі сервісів. Формат у нього жорсткий — чотири поля: версія, trace-id (32 шістнадцяткові символи нижнього регістру), parent-id (16) і trace-flags; власний ідентифікатор команди туди не вкласти, а якщо всунути — отримувач зобовʼязаний проігнорувати весь заголовок. Практична різниця: власний X-Request-Id легко проставити з тесту й знайти в логах конкретного сервісу, а traceparent дає наскрізну нитку, придатну для розподіленого трейсу.

Що таке спан і як спани складаються в розподілений трейс (distributed tracing)?

Коли запит проходить крізь кілька сервісів, окремих логів уже мало. Спан (span) — один крок обробки: виклик сервісу, запит до бази, звернення до залежного API. Трейс (trace) — усі спани одного запиту, зібрані в дерево викликів із таймінгами: на ньому видно, котрий крок з'їв час і звідки насправді прилетіла помилка. Відкритий стандарт тут — OpenTelemetry, візуалізатори — системи на кшталт Jaeger. Для AQA це передусім навичка читання: взяв trace-id з відповіді, відкрив трейс — і бачиш, що 500 народився не в сервісі замовлень, а в платіжному, який вперся в таймаут.

Навіщо зводити фейл до самодостатнього curl?

Невідтворюваний флак неможливо ні полагодити, ні довести розробнику. curl — спільна мова: один рядок із методом, повним URL, заголовками й тілом однаково зрозумілий бекендеру, девопсу й тобі самому за тиждень. Звідси дисципліна: логувати важливі запити в такому вигляді, щоб фейл відтворювався вставленням рядка в термінал, без реконструкції з пам'яті. Бонус — такий рядок ідеально лягає в баг-репорт: розробник відтворює проблему одним рухом.

Ти звів фейл до curl і ганяєш його наосліп. Як читати результат?

Двома гілками. curl падає щоразу в тому самому оточенні — фейл детермінований: майже напевно дефект продукту (або крива перевірка в самому тесті); голий запит без обгортки фреймворку знімає підозру з фікстур. curl зелений, а червоніє лише сюїта — проблема не в запиті, а в контексті прогону: черговість тестів, спільні дані, змагання воркерів. Це головна розвилка тріажу: за хвилину відокремлює «щось не так із продуктом» від «щось не так із моїм прогоном», не чіпаючи код застосунку.

Тест то падає, то проходить на тому самому коді. Опиши свій метод, а не готову відповідь.

Сильна відповідь — не «додам ретрай», а послідовне зняття підозр. Крок один: запустити тест поодинці — флак зник, отже, винен контекст сюїти (дані чи змагання воркерів), не продукт. Крок два: свіже оточення (докеризована база, ефемерний namespace, окремий акаунт) — зник там, значить, справа у спільному стенді й чужих даних; лишився — причина глибша. Крок три: curl наосліп — стабільне падіння чистого запиту в ізоляції означає детермінований дефект продукту. Крок чотири: логи за correlation id — якщо видно гонку, deadlock чи таймаут залежного сервісу, доказ на руках. Фінал — не зелений колір, а чесна класифікація: баг продукту, баг тесту чи інфраструктура.

Чи кожен плаваючий фейл — це вина тесту?

Ні, і це важлива чесність тріажу. Буває, що хиткість на рівні API — справжня поведінка продукту під навантаженням: гонка на конкурентних записах, яку ніхто не захистив, з'єднання, що витікають лише під паралеллю, рідкісний 500 на одному запиті із сотні. Такий флак — улов, а не шум. Ціна помилки висока в обидва боки: назвеш продуктовий баг «морганням мережі» — випустиш регресію; оформиш інфраструктурний шум як дефект — змарнуєш час команди й підточиш довіру до своїх репортів. Тому мета — не заглушити падіння, а правильно його класифікувати й полагодити те, що зламане насправді.

Чому 429 часто спливає лише в CI під час паралельного прогону?

429 Too Many Requests — відповідь rate limiting-а: клієнт перевищив дозволену частоту звернень. Один тест до ліміту зазвичай не дотягується, а от у CI десятки воркерів разом гатять в один ендпоінт — і сюїта колективно пробиває поріг. Симптом упізнаваний: локально зелено, у паралельному пайплайні — нестабільні падіння з 429. Це не випадковість, а закономірність, і лікується вона системно: поважати Retry-After, знизити паралелізм на гарячих ендпоінтах або замокати ліміт там, де тест перевіряє не його. Головне — бачити в лімітах окреме джерело флаку, а не лише сюжет для одного негативного тесту.

Три кейси, де вирішується, зелений API-тест чи полювання за примарою: заміна sleep на полінг для асинхронної операції, ретрай, що ловить лише транзієнтний збій транспорту й тягне correlation id у звіт, і тріаж флаку через curl наосліп. Скрізь — що робити і чому саме так.

Кейс 1. Полінг на умову замість sleep

Тест створює завдання (POST /api/jobs) і одразу читає результат — а сервер відповів 202 Accepted, тобто запит лише прийнято, обробка триває асинхронно. Наївний фікс — вставити паузу «щоб точно встигло». На завантаженому CI-агенті лаг більший за паузу, і тест починає плавати.

// ХИБНО: фіксована пауза програє в обидва боки
const created = await request.post('/api/jobs', { data: job });
await new Promise((r) => setTimeout(r, 2000)); // 2s мало на CI, багато на порожньому стенді
const res = await request.get(`/api/jobs/${id}`);
expect((await res.json()).status).toBe('done');

Заміна — полінг на бізнес-умову з верхнім таймаутом. Чекаємо не на секунди, а на конкретний спостережуваний факт: поле status стало done.

// значення часу — з налаштувань, а не літералами в тесті
const WAIT_LIMIT_MS = Number(process.env.WAIT_LIMIT_MS ?? 60_000);
const POLL_INTERVALS_MS = [300, 600, 1200];

const id = (await (await request.post('/api/jobs', { data: job })).json()).id;

// ПРАВИЛЬНО: чекаємо на факт, а не на час
await expect.poll(async () => {
  const res = await request.get(`/api/jobs/${id}`); // тільки читання — ідемпотентно
  return (await res.json()).status;
}, { timeout: WAIT_LIMIT_MS, intervals: POLL_INTERVALS_MS }).toBe('done');

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

• 202 проти 201 — це діагноз, а не дрібниця. 201 означає, що ресурс уже створено й наступний GET його побачить; 202 каже «прийнято, обробляю» — читати результат одразу немає сенсу. Побачив 202 — операція асинхронна, потрібен полінг.
• Умова замість часу. Полінг перепитує систему, доки поле status не стане done, і йде далі рівно в цю мить, а не через фіксовані дві секунди. На швидкому стенді тест завершиться за 300 мс, на повільному — почекає, скільки треба.
• Верхній таймаут обов'язковий. WAIT_LIMIT_MS — це стеля: якщо факт не настав, тест чесно падає, а не зависає назавжди. Полінг без стелі гірший за sleep. Дві поправки: стелю ставлять високою, щоб вона спрацьовувала лише на серйозній поломці, а часові значення тримають у константах чи налаштуваннях оточення, а не літералами в коді.
• Функція всередині лише читає. У полінгу — тільки GET. Поклади туди POST — і за десять ітерацій отримаєш десять завдань замість перевірки одного.

Кейс 2. Ретрай лише на транзієнтному збої плюс correlation id у звіті

Мережа між CI-агентом і API іноді рветься — це транзієнтний шум транспорту, який сам не повториться. Його ретраїти можна, але лише для безпечного GET і лише на кинутому винятку. Важлива пастка: 500 від застосунку сюди не прилетить — це звичайна відповідь, а не виняток, тож наш ретрай його не проковтне.

// Ретраїмо лише GET і лише на кинутих мережевих збоях
async function getWithRetry(request, url, tries = 3) {
  for (let i = 0; i < tries; i++) {
    try {
      return await request.get(url); // 500 сюди НЕ кине — це відповідь, а не виняток
    } catch (err) {
      if (i === tries - 1) throw err; // спроби вичерпано — чесний фейл, не мовчазний зелений
      await new Promise((r) => setTimeout(r, 200 * (i + 1))); // лінійний бекоф
    }
  }
}

Коли запит усе-таки впав осмислено, потрібен ключ у логи. Дістаємо correlation id з відповіді (або шлемо свій) і кладемо його в повідомлення асерту — тоді він потрапить у звіт про фейл.

const res = await request.post('/api/orders', {
  data: order,
  headers: { 'X-Request-Id': `qa-${testInfo.testId}` },
});
const requestId = res.headers()['x-request-id'] ?? `qa-${testInfo.testId}`;
// id у месиджі асерту — щоб після падіння одразу було що grep-ати в логах сервісу
expect(res.status(), `request-id=${requestId}`).toBe(201);

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

• Ретрай ловить транспорт, а не коди. try/catch спрацьовує на обриві з'єднання чи DNS-таймауті. Якби ми замість цього аналізували статус і повторювали 5xx, ретрай почав би мовчки ховати 500 через реальний баг гонки.
• Тільки GET. POST через getWithRetry створив би дублікат замовлення. Захист POST від повтору — робота продукту через Idempotency-Key, а не тесту.
• Correlation id у повідомленні асерту, а не в console.log. Повідомлення асерту потрапляє в репорт поруч із фейлом. request-id=... перетворює дебаг із «перезапущу й подивлюся» на точковий пошук у логах сервісу.
• Вичерпав спроби — кидай. if (i === tries - 1) throw err дає чесний фейл. Проковтнути останню помилку й повернути undefined — це замаскувати проблему ще глибше за flaky pass.

Кейс 3. Тріаж: curl наосліп і таблиця рішень

Тест червоніє через раз. Перш ніж заводити баг чи правити локатор, треба відповісти на одне питання: винен продукт, тест чи оточення. Зводимо фейл до самодостатнього curl — його зрозуміє і бекендер, і девопс, і ти сам через тиждень.

curl -i -X POST 'https://api.staging.example.com/v1/orders' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'X-Request-Id: repro-2026-07-17-001' \
  -d '{"sku":"A-100","qty":2}'

Далі — послідовне відсіювання підозрюваних: прогнати curl кілька разів наосліп у тому самому оточенні, потім ізолювати одиничний тест, потім свіже оточення, потім логи за X-Request-Id.

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

• curl — це спільна мова доказу. Стабільне падіння на чистому запиті в ізоляції знімає підозру з фікстур і фреймворку: розробник відтворює його одним рухом, і суперечка «це баг чи флак» закінчується.
• Зелений curl при червоній сюїті вказує вбік від продукту. Винен не сам запит, а те, як влаштований прогін: порядок тестів, спільні дані, гонка між воркерами. Копай усередину тесту, а не в застосунок.
• 429 під паралеллю — не шум, а передбачуваність. Якщо флак зникає при зменшенні кількості воркерів — сюїта сама заганяла себе в rate limit. Це оточення, а не баг продукту.
• Мета — класифікація, а не зелений колір. Тріаж закінчується чесним вироком: баг продукту, баг тесту чи інфраструктура. Гонка під навантаженням, яку зловив тест, — це знахідка, а не привід заглушити падіння ретраєм.

Джерела флаку

• Можу пояснити, що флак (flaky test) — це падіння на незмінному коді, і що перший крок не «додати ретрай», а назвати причину.
• Знаю чотири практичні групи джерел флаку API-тестів: дані, гонки (асинхронність), оточення, ліміти — і характерний симптом кожної; памʼятаю, що канонічний перелік ширший і додає час і витоки ресурсів.
• Розумію, чому дані й гонки — брати: обидва про стан, але дані це колізії й хибні передумови, а гонки це час (читання випереджає асинхронний запис).
• Знаю, що 429, обриви з'єднань і таймаути під паралеллю — це клас «ліміти», а не «моргнула мережа».

Полінг замість sleep

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

Ретраї: рятують чи маскують

• Знаю, що безпечно ретраїти лише safe/ідемпотентні запити (GET, HEAD, PUT, DELETE), а POST і PATCH ідемпотентними не гарантовані; памʼятаю, що дотримання семантики лежить на сервері й перевіряється.
• Можу пояснити межу «на що реагуємо»: транзієнтний збій транспорту ретраїмо, осмислену помилку продукту (500, 409, 400) — ні.
• Розумію класичну пастку: мережевий збій кидається як виняток, а 500 приходить як звичайна відповідь, тож клієнтський ретрай має ловити кинуті помилки, а не коди.
• Знаю ціну ретраю всього тесту на рівні ранера: flaky pass треба рахувати й заводити в карантин, інакше сюїта бреше.

Дебаг: correlation id і трейсинг

• Можу пояснити, чому дебаг API-флаку — це зв'язати впалий запит із логами сервера, а не дивитися лише на відповідь.
• Знаю різницю між конвенційним X-Request-Id/X-Correlation-Id і формальним стандартом W3C Trace Context із заголовком traceparent, і що traceparent має жорсткий формат із чотирьох полів (версія, trace-id, parent-id, trace-flags) — власний id команди туди не всунеш, бо отримувач мусить проігнорувати весь заголовок.
• Вмію дістати correlation id з відповіді (або надіслати свій) і покласти його в повідомлення асерту та артефакти звіту.
• Розумію, що таке спан (span) і як спани складаються в розподілений трейс (distributed tracing), і що для AQA це передусім навичка читання трейсу (OpenTelemetry, Jaeger).

Відтворення і тріаж

• Можу звести фейл до самодостатнього curl (метод, URL, заголовки, тіло) і знаю, навіщо логувати запити саме в такій формі.
• Читаю результат curl наосліп: стабільне падіння — детермінований баг продукту; зелений curl при червоній сюїті — проблема в контексті тесту.
• Знаю метод відсіювання підозрюваних (ізоляція одиничного тесту → свіже оточення → відтворення curl → логи за correlation id) і його мету: не «зробити тест зеленим», а чесно розділити баг продукту, баг тесту й інфраструктуру.
• Розумію, що не кожен плаваючий фейл — вина тесту: гонка під навантаженням буває справжнім багом продукту, а не шумом.