API-автотести в коді: клієнти, структура, ланцюжки

Навіщо переносити API-тести з Postman/Newman у код?

Колекція чудово працює, поки запитів десятки чи сотня, але погано масштабується під тисячі перевірок у CI. У коді ти отримуєш той самий мовний стек, репозиторій і рев'ю-процес, що й у продукту: перевикористання авторизації, спільні тестові дані, читабельні падіння в трейсі, нормальна робота з гілками й код-рев'ю. Postman лишається зручним для ручного дослідження й дебагу окремого запиту, а систематичну регресію на кожен PR тримає код. Практичний тригер переходу — момент, коли колекцію вже страшно чіпати, бо її скрипти сплелися між собою.

Якими HTTP-клієнтами ходять в API з коду в JS/TS і чим вони відрізняються?

HTTP-клієнт (HTTP client) — це бібліотека, що відправляє запит і повертає відповідь як об'єкт. У JS/TS реально зустрічаються чотири: fetch (вбудований у браузер і Node.js з 18-ї версії), axios (зовнішня бібліотека), APIRequestContext (з Playwright) і supertest (для тестування свого сервера в процесі). Головна вісь відмінності, яку люблять питати, — поведінка на HTTP-помилку: fetch і APIRequestContext не кидають на 4xx/5xx, axios за замовчуванням кидає, supertest асертиться окремо. Вибір клієнта визначає, як ти обробляєш помилки, таймаути й серіалізацію, тож це не питання смаку.

Чому fetch не впав на статусі 500?

Бо fetch не вважає HTTP-помилку помилкою виконання запиту. Відхилення проміса зарезервоване за збоями транспорту: DNS не резолвиться, з'єднання обірвалось. А відповідь із 404 чи 500 для fetch — запит, що вдався: проміс резолвиться нормальним обʼєктом відповіді, лише response.ok буде false, тож catch навколо нього не спрацює. Тому статус треба перевіряти явним асертом (expect(res.status()).toBe(...)), а не сподіватись, що try/catch зловить 5xx. Хто плутає це, той писав тільки happy-path.

Чим axios поводиться інакше за fetch на помилку?

axios за замовчуванням відхиляє проміс на будь-який статус поза діапазоном 2xx — тобто робить те, чого не робить fetch. Це регулюється опцією validateStatus. Для продакшн-коду зручно (помилка одразу летить у catch), але для тестів радше заважає: ти й так хочеш перевіряти статус явним асертом, а не ловити його через try/catch. Тому в тестах на axios часто налаштовують validateStatus так, щоб він не кидав, і асертять статус вручну.

Що таке APIRequestContext і чим він зручний для API-тестів?

Це вбудований HTTP-клієнт Playwright, доступний у тестах як фікстура request. Поводиться він як fetch — HTTP-помилка не кидає виняток, її треба асертити. Головна вигода — інтеграція з рештою Playwright: свій baseURL, усі виклики видно в трейсі, а варіанти page.request/context.request ділять cookie з браузерним контекстом — залогінився через API, перевіряєш в UI (сама фікстура request ізольована й cookie сторінки не бачить). Якщо стек уже на Playwright, це природний вибір для API-сюїтів і підготовки стану поруч з e2e.

Навіщо supertest і коли він не потрібен?

supertest призначений тестувати HTTP-сервер у тому ж процесі: ти передаєш йому свій застосунок (наприклад, Express), він піднімає його на ефемерному порту й ходить у нього без реальної мережі. Це швидко й ізольовано, тому підходить для компонентних тестів бекенду зсередини. Але працює лише коли сервер під рукою в коді. Для тестування задеплоєного API по URL (стейдж, прод) він не потрібен — там ходять APIRequestContext, axios чи fetch.

Що таке arrange–act–assert і як він читається для API-тесту?

Arrange–act–assert (AAA), «підготуй — дій — перевір» — канонічна структура тесту, однакова для UI та API. Arrange — попередні умови сцени: логін і токен, насіяний через API ресурс, потрібний стан бази — усе, чого головний запит потребує, але що саме по собі не перевіряється. Act — рівно один запит, поведінку якого перевіряє тест. Assert — перевірки відповіді: статус, тіло, заголовки, відповідність схемі. Розділення фаз робить тест читабельним і показує, що саме тестується.

Чому в тесті має бути рівно один головний запит (act)?

Бо якщо в тесті два «головні» запити, поведінку яких ти перевіряєш, — це насправді два тести, злиті в один. Коли такий тест червоніє, незрозуміло, який саме крок зламався, і звіт бреше. Запити на підготовку стану (створити ресурс, залогінитись) не рахуються за act — це arrange. Один act на тест також спрощує назву: вона описує одну конкретну перевірку («повертає 201 зі схемою Order»), а не ланцюжок дій.

Що таке патерн API-клієнта і яку проблему він вирішує?

Патерн API-клієнта (API client) — це клас, який ховає ендпоінт за методом з людською назвою: замість сирого request.post('/orders', { headers: ... }) у кожному тесті — orders.createOrder({ productId, qty }). Проблема, яку він розв'язує, та сама, що й Page Object для UI: без нього базовий URL, заголовок авторизації й розбір відповіді дублюються в кожному тесті, і зміна формату авторизації вимагає правок у ста місцях. Клієнт робить це єдиним джерелом правди, а тест читається як сценарій, а не як HTTP-механіка.

Чому не варто класти асерти всередину API-клієнта?

Бо клієнт із перевірками всередині перетворюється на god object: він змішує транспорт (як сходити в ендпоінт) з перевіркою (що вважати правильним) і ховає, що саме асертиться в конкретному тесті. Клієнт має віддавати «сиру» відповідь, а перевірки лишатись у тесті — тоді один і той самий метод createOrder годиться і для позитивного тесту (очікуємо 201), і для негативного (очікуємо 422). Це та сама дисципліна розділення відповідальностей, що й «локатори в Page Object, асерти в тесті».

Що таке ланцюжки (chaining) в API-тестах?

Ланцюжок — це коли відповідь одного запиту дає вхід для наступного. Частина перевірок неможлива без попереднього стану: GET /orders/{id} нема з чим викликати, поки інший запит не створив замовлення й не віддав його id. Класичний ланцюжок: POST /orders віддає id, який ти підставляєш у POST /orders/{id}/cancel, а потім перевіряєш GET /orders/{id}. Частина ланцюжка — це arrange (підготовка стану), і лише один крок — справжній act, який ти перевіряєш.

Чому тестові дані для API краще готувати через API, а не через UI?

Бо API-сідінг (seeding) на порядок швидший і стабільніший за клікання майстром у браузері. Якщо тесту потрібне замовлення, клацати його через UI означає протягнути в arrange весь фронтенд з його рендером, анімаціями й флаком — і все це заради декорацій, а не заради самої перевірки. Головне правило: готуй стан найдешевшим надійним способом. Відповідь «створюю руками в базі» на співбесіді насторожує (крихко, обходить бізнес-логіку), а «сідж через API» — сильний сигнал.

Що таке teardown і чому його вішають на after-хук?

Teardown (прибирання) — це видалення того, що тест насіяв: створені замовлення, юзери, файли. Без нього середовище засмічується, і сусідні прогони починають бачити чужі дані, а на повторному запуску вилазять конфлікти (409 на зайнятий email). Прибирання вішають на after-хук (afterEach/finally), щоб воно відпрацювало навіть коли основна перевірка впала посередині: інакше кожен червоний тест лишав би за собою сміття. Це та сама пара «створив — прибрав», що й у будь-якому керуванні ресурсами.

Що таке eventual consistency і чому sleep — погане лікування?

Eventual consistency (кінцева узгодженість) — властивість розподілених систем, коли створений ресурс не завжди видно наступним запитом миттєво: репліка ще не наздогнала майстер. Симптом — «баг у продукті, ресурс не з'явився», а насправді наступний запит прийшов раніше, ніж дані узгодились. sleep(3000) — погане лікування одразу з двох причин: на швидкому середовищі він марно гальмує прогін, а на повільному все одно не встигне й тест флакне. Правильно — полінг (polling) з таймаутом: періодично перепитувати until-умову, поки не справдиться або не вийде час (expect.poll у Playwright).

Навіщо валідувати схему відповіді і чим ajv відрізняється від zod?

Перевіряти тіло пополе (expect(body.id).toBeDefined()) виснажливо й дірчасто: забув поле — пропустив регресію. Валідація проти схеми перевіряє всю форму відповіді одним асертом. ajv — валідатор JSON Schema: описуєш структуру мовою JSON Schema, ajv компілює її у швидку функцію й повертає розбіжності; головна вигода — схему можна взяти прямо з OpenAPI-специфікації, перетворивши доку на тест. zod — TS-first: схему описуєш кодом на TypeScript, parse перевіряє в рантаймі, а бонус — з тієї ж схеми виводиться статичний тип. Груба евристика: є OpenAPI й потрібна одна правда для доки й тестів — ajv; пишеш на TS з нуля й хочеш статичні типи — zod.

Чому у схемі важливо забороняти зайві поля?

Бо за замовчуванням валідатор перевіряє лише те, що ти описав, і пропускає все зверху. Якщо бекенд почне повертати нове несподіване поле (наприклад, витік внутрішнього passwordHash чи internalNote), м'яка схема цього не помітить — регресія проскочить. Тому за замовчуванням зайві поля забороняють: у JSON Schema це additionalProperties: false, у zod — .strict(). Тоді будь-яка структурна зміна відповіді — і зникнення поля, і поява зайвого — валить тест дешево, одним асертом.

Навіщо таймаут у тесті і чим загрожують занизьке та зависоке значення?

Таймаут (timeout) — це межа очікування відповіді, після якої запит вважається провальним. Без нього завислий запит тримає весь прогін, аж поки не спрацює глобальний ліміт ранера з малоінформативною помилкою. Тому межу задають свідомо на двох рівнях: для окремого запиту в клієнті й для тесту цілком. Занизьке значення породжує флак на повільному CI (нормальна відповідь просто не встигає прийти), зависоке — ховає деградацію продуктивності (сервіс уже відповідає вдвічі повільніше, а тест мовчить). Значення обирають з голови сервісу, а не наосліп.

Ретраї в тестах — це добре чи погано?

Залежить від того, що саме повторюють — тут перевіряють зрілість. Треба розрізняти три речі. Мережевий ретрай ідемпотентного запиту (повторити GET, що впав через скидання з'єднання) — безпечно, бо повтор не змінює стан сервера; а от наосліп повторювати POST, що щось створює, — ризик дубля (рятує Idempotency-Key, якщо API його підтримує). Полінг для eventual consistency — це не ретрай, а очікування стану з таймаутом, легітимний патерн. Ретрай усього тесту, що впав — червоний прапорець: тест, який проходить лише з другої спроби, лишився зламаним — повтор прибрав симптом зі звіту, а не причину. Одним рядком: таймаут і полінг лікують чесну асинхронність, сліпий ретрай усього тесту мовчки ховає баг.

Що потрібно, щоб запускати API-тести паралельно?

Ключове слово — ізоляція даних (data isolation). Без браузера й рендеру API-тести дешеві, тому їх запускають на десятках воркерів — і прогін скорочується з десятків хвилин до одиниць. Але паралельність безжально карає за спільний стан: два воркери, що правлять один ресурс, дають гонку й «іноді падає» без видимої причини. Тому кожен тест має працювати зі своїми даними: згенерований унікальний email, власне замовлення, а в ідеалі — окремий акаунт чи tenant на воркер. Антипатерн, згадка якого — сильний сигнал: один спільний тестовий юзер на всю сюїту, за стан якого тести стають у чергу.

Чому один спільний тестовий юзер — антипатерн для паралельного запуску?

Бо щойно тести стартують паралельно, вони починають перетирати одне одному стан цього юзера: один змінює його кошик, другий у цей момент його читає й бачить чуже. Виникає прихована залежність через дані, яка маскується під незалежні тести, — вона працює послідовно й розсипається в паралелі. Лікування — ізоляція: генерувати унікальні дані на кожен тест або виділяти окремий акаунт/tenant на воркер. Окрема пастка того ж роду: глобальний лічильник, послідовні id чи спільний кошик в API — такі місця «стріляють» першими, тож їх закладають у дизайн даних одразу.

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

Кейс 1. API-клієнт і чистий arrange–act–assert

Сирий запит у кожному тесті розповзається копіпастою: заголовок авторизації, базовий шлях і розбір відповіді доводиться правити в десятках місць. Виносимо ендпоінти в клас-клієнт, а тест лишаємо про перевірку.

// orders-api.ts — словник ендпоінтів, жодних асертів усередині
import { APIRequestContext } from '@playwright/test';

type OrderInput = { productId: number; qty: number };

export class OrdersApi {
  constructor(private request: APIRequestContext, private token: string) {}

  createOrder(data: OrderInput) {
    return this.request.post('/orders', {
      headers: { Authorization: `Bearer ${this.token}` },
      data,
    });
  }

  getOrder(id: string) {
    return this.request.get(`/orders/${id}`, {
      headers: { Authorization: `Bearer ${this.token}` },
    });
  }

  cancelOrder(id: string) {
    return this.request.post(`/orders/${id}/cancel`, {
      headers: { Authorization: `Bearer ${this.token}` },
    });
  }

  deleteOrder(id: string) {
    return this.request.delete(`/orders/${id}`, {
      headers: { Authorization: `Bearer ${this.token}` },
    });
  }
}

// orders.spec.ts — тест читається як сценарій, а не як HTTP-механіка
import { test, expect } from '@playwright/test';
import { OrdersApi } from './orders-api';

test('POST /orders створює замовлення й повертає 201 зі статусом created', async ({ request }) => {
  // Arrange — декорації сцени, не предмет перевірки
  const token = await auth.loginAs('customer');
  const orders = new OrdersApi(request, token);

  // Act — рівно ОДИН головний запит
  const res = await orders.createOrder({ productId: 42, qty: 2 });

  // Assert — статус і форма відповіді
  expect(res.status()).toBe(201);
  const body = await res.json();
  expect(body).toMatchObject({ productId: 42, qty: 2, status: 'created' });
});

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

• Асерти лишились у тесті, клієнт віддає сиру відповідь. Той самий createOrder годиться і для позитивного тесту (чекаємо 201), і для негативного (чекаємо 422 на биті дані). Занеси перевірку в клієнт — і він стане god object, який ховає, що саме тестується.
• Один act на тест. loginAs і new OrdersApi — це arrange, а не другий головний запит. Якби в тесті було два перевірюваних виклики, червоний звіт не сказав би, який саме зламався.
• Назва описує перевірку, а не дію. «Повертає 201 зі статусом created» у червоному звіті вже розповідає, що зламалось; «тест POST orders» — ні.
• res.status() — явний асерт, а не try/catch. APIRequestContext не кидає на 4xx/5xx, тож статус перевіряється руками. Наївний catch тут не спрацював би на 500.

Кейс 2. Ланцюжок: підготовка стану, прибирання, полінг

Скасування замовлення не перевірити «на порожньому місці» — замовлення спершу треба створити. Це ланцюжок: id зі створеного ресурсу йде у наступні виклики. Стан сіємо через API (не через UI), прибираємо в after-хуці, а на eventual consistency ставимо полінг замість паузи навмання.

import { test, expect } from '@playwright/test';
import { OrdersApi } from './orders-api';

test.describe('скасування замовлення', () => {
  let orders: OrdersApi;
  let orderId: string;

  test.beforeEach(async ({ request }) => {
    const token = await auth.loginAs('customer');
    orders = new OrdersApi(request, token);

    // Arrange — сідж стану найдешевшим надійним способом: запитом, не кліком
    const created = await orders.createOrder({ productId: 42, qty: 2 });
    expect(created.status()).toBe(201);
    orderId = (await created.json()).id;
  });

  test.afterEach(async () => {
    // Teardown на after-хуці — відпрацює навіть коли перевірка впала
    await orders.deleteOrder(orderId).catch(() => {});
  });

  test('POST /orders/{id}/cancel переводить замовлення у cancelled', async () => {
    // Act — те, що справді перевіряємо
    const res = await orders.cancelOrder(orderId);
    expect(res.status()).toBe(200);

    // Assert зі стійкістю до eventual consistency: полінг, а не sleep(3000)
    await expect.poll(async () => {
      const got = await orders.getOrder(orderId);
      return (await got.json()).status;
    }, { timeout: 5000 }).toBe('cancelled');
  });
});

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

• Сідж через API, а не через UI. Замовлення в beforeEach створюється запитом за мілісекунди й без флаку фронтенду. Клацати його майстром у браузері означало б протягнути в arrange весь рендер заради декорацій.
• Teardown у afterEach, а не в кінці тесту. Якби прибирання стояло останнім рядком тесту, воно б не відпрацювало на падінні cancel, і середовище засмічувалось би. .catch(() => {}) глушить помилку клінапу, щоб вона не маскувала справжню причину падіння.
• expect.poll замість sleep. Після cancel репліка може ще не наздогнати, і миттєвий GET віддасть старий статус. Полінг перепитує до 5 секунд і зеленіє щойно узгодилось — на швидкому середовищі не гальмує, на повільному не флакне. sleep(3000) програє в обидва боки.
• Ланцюжок ≠ один тест. Створення в beforeEach — arrange, cancel — act, getOrder — assert. Перевіряється рівно один перехід стану.

Кейс 3. Валідація тіла проти схеми з забороною зайвих полів

Перевіряти тіло пополе (expect(body.id).toBeDefined()) дірчасто: забув поле — пропустив регресію, а зайве поле взагалі не помітиш. Замикаємо всю форму на одну схему zod і забороняємо зайве через .strict().

import { test, expect } from '@playwright/test';
import { z } from 'zod';
import { OrdersApi } from './orders-api';

// .strict() → будь-яке несподіване поле у відповіді провалить parse
const Order = z
  .object({
    id: z.string().uuid(),
    productId: z.number().int(),
    qty: z.number().int().positive(),
    status: z.enum(['created', 'paid', 'cancelled']),
  })
  .strict();

test('GET /orders/{id} повертає тіло, що точно відповідає схемі Order', async ({ request }) => {
  const token = await auth.loginAs('customer');
  const orders = new OrdersApi(request, token);
  const { id } = await (await orders.createOrder({ productId: 42, qty: 2 })).json();

  const res = await orders.getOrder(id);
  expect(res.status()).toBe(200);

  const body = await res.json();
  const order = Order.parse(body); // кине, якщо форма не збіглась; далі order типізований
  expect(order.status).toBe('created');
});

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

• Одна схема замість десятка expect. Order.parse перевіряє всю форму разом: типи, набір полів, допустимі значення status. Зникло поле чи змінився тип — parse кине з описом розбіжності, і жодна регресія не проскочить.
• .strict() ловить зайве поле. Без нього відповідь із витеклим internalNote чи passwordHash мовчки пройшла б валідацію. У JSON Schema (ajv) той самий ефект дає additionalProperties: false.
• Бонус типізації. Після parse змінна order типізована — далі працюєш без ручних as, а редактор підказує поля. Це TS-first перевага zod.
• Коли натомість ajv. Якщо схеми вже описані в OpenAPI й хочеться однієї правди для доки й тестів — беруть JSON Schema прямо зі специфікації й валідують ajv, фактично перетворюючи доку на тест. zod — коли тести пишуться на TS з нуля й потрібні статичні типи.

HTTP-клієнти

• Знаю чотири клієнти в JS/TS (fetch, axios, APIRequestContext, supertest) і чим вони відрізняються за поведінкою на помилку та контекстом застосування.
• Можу пояснити, чому fetch і APIRequestContext не кидають на 4xx/5xx: проміс відхиляється лише на мережевому збої, а 500 — це успішний запит з response.ok === false, тож статус перевіряють асертом.
• Знаю, що axios за замовчуванням кидає на будь-який статус поза 2xx (регулюється validateStatus), а supertest асертить статус окремо.
• Розумію, що APIRequestContext дає baseURL, запис у трейс, а через page.request/context.request — спільні cookie з браузером (фікстура request ізольована), тоді як supertest потрібен для свого сервера в процесі (ефемерний порт), не для задеплоєного API по URL.

Структура тесту (arrange–act–assert)

• Знаю три фази AAA і що для API arrange — це підготовка стану, act — рівно один головний запит, assert — перевірки відповіді.
• Розумію, чому в тесті один act (два «головні» запити — це два тести, і червоний звіт інакше бреше) і чому назва описує перевірку («повертає 201 зі схемою Order»), а не дію («тест POST orders»).
• Знаю, що тест не має залежати від порядку й сам готує свій стан — це передумова паралельного запуску.

Патерн API-клієнта

• Можу пояснити, яку проблему розв'язує патерн API-клієнта: ховає ендпоінт, baseURL і авторизацію за методом з людською назвою, як Page Object для UI; розподіл шарів — HTTP-клієнт про транспорт, API-клієнт про словник ендпоінтів, тест лише про перевірку.
• Розумію, чому асерти не кладуть у клієнт: інакше він стає god object, змішує транспорт з перевіркою і ховає, що саме тестується.

Ланцюжки й підготовка стану

• Знаю, що таке ланцюжок (chaining): відповідь одного запиту (id створеного ресурсу) дає вхід для наступного.
• Можу пояснити, чому стан готують через API-сідінг, а не через UI (швидше, стабільніше, не додає флаку до сценарію, що про інше), і чому teardown вішають на after-хук — щоб прибирання відпрацювало навіть коли основна перевірка впала.
• Знаю різницю між справжнім багом «ресурс не з'явився» та eventual consistency, коли репліка ще не наздогнала, і чому її лікують полінгом із таймаутом, а не sleep(3000).

Валідація схем

• Розумію, чому перевірка всієї форми проти схеми надійніша за перевірку кількох полів пополе.
• Знаю різницю ajv vs zod: ajv — JSON Schema (можна взяти з OpenAPI), zod — TS-first зі статичним типом з тієї ж схеми.
• Можу пояснити, чому за замовчуванням забороняють зайві поля (additionalProperties: false / .strict()), інакше нове поле проскочить повз перевірку.

Таймаути й ретраї

• Розумію, навіщо таймаут (не підвісити прогін) і чому занизьке значення дає флак, а зависоке ховає деградацію продуктивності.
• Знаю різницю між трьома «повторами»: мережевий ретрай ідемпотентного запиту (наосліп POST — ризик дубля, рятує Idempotency-Key), полінг стану й ретрай усього тесту.
• Розумію, чому ретрай усього тесту — червоний прапорець: «зеленіє з другого разу» ховає флак, а не лікує причину.

Паралельний запуск

• Знаю, що єдина передумова безпечної паралельності — ізоляція даних, чому спільний стан дає гонки й чому один спільний тестовий юзер — антипатерн прихованої залежності через дані.
• Розумію, чому глобальні лічильники, послідовні id чи спільний кошик «стріляють» першими в паралелі.