Postman: основи

Що таке колекція в Postman і чим вона відрізняється від простої теки із запитами?

Тека лише групує вміст, а колекція (collection) несе власні налаштування: документацію, авторизацію і змінні, що поширюються вниз по дереву на папки й запити. Ієрархія проста: запит (request) з методом, URL, параметрами, заголовками й тілом → папка (folder) → колекція. Ключова ідея в тому, що саме колекція — одиниця експорту в JSON, шарингу команді й запуску цілком у Collection Runner чи Newman, і разом із нею їдуть і змінні рівня колекції, і налаштована авторизація. Тому «зібрати запит у Postman» і «зібрати колекцію» — різні рівні: перше вміє й curl, друге перетворює разові запити на повторюваний артефакт. Саме за цим розумінням — колекція як артефакт, а не тека — інтерв'юер і відсіює тих, хто лише клікав по кнопках.

Як краще організувати колекцію — за ресурсами чи за сценаріями?

Обидва варіанти робочі, вибір залежить від мети. Організація за ресурсами API (папки Users, Orders, Payments з CRUD-запитами всередині) зручна для дослідження API, регресійного набору й документації. Організація за сценаріями (папки «Реєстрація», «Оформлення замовлення» з кроками флоу) підходить для наскрізних бізнес-флоу, де запити залежать один від одного. Головне — послідовність усередині колекції та осмислені назви: імʼя на кшталт Get user втрачає сенс, щойно запитів стає кілька десятків. Краще називати за перевіркою чи призначенням — «Створення користувача з валідними даними», «GET неіснуючого id → 404», — як і з тест-кейсами: з назви має бути видно суть перевірки, а не маршрут, яким ходить запит.

Навіщо документувати запити в Postman, якщо є Confluence чи OpenAPI?

Бо опис у Postman живе там само, де й робочий запит, — тож у нього значно більше шансів лишатися актуальним, ніж у сторінки Confluence, яку востаннє правили пів року тому. Кожен рівень ієрархії (колекція, папка, запит) має поле опису з підтримкою Markdown: на рівні колекції фіксують, що це за API і як отримати доступ; на рівні папки — контекст ресурсу чи сценарію; на рівні запиту — призначення, обов'язкові параметри, посилання на тікет. З охайної колекції Postman ще й генерує веб-документацію майже безкоштовно. Конкурентом OpenAPI це не робить: за наявності специфікації первинне джерело істини — вона, а колекція працює поруч як робочий інструмент, не заміна.

Що таке збережені приклади (examples) і навіщо вони?

Приклад (example) — прикріплена до запиту пара «запит + відповідь»: зберіг реальну відповідь сервера — і формат тіла тепер видно без виконання запиту й без доступу до стенда. Це знімає класичне питання «а що цей ендпоінт узагалі повертає» без витрат на доступи й без ризику зачепити дані. Приклади також живлять mock-сервери Postman — можна віддавати збережену відповідь ще до того, як бекенд готовий. Для QA це дешевий спосіб зафіксувати контракт відповіді просто в колекції.

Що таке змінні в Postman і як вставити змінну в запит?

Змінна (variable) — іменоване значення, яке підставляється в запит перед надсиланням, щоб не хардкодити одне й те саме в десятках місць. Синтаксис — подвійні фігурні дужки в будь-якому місці запиту: {{baseUrl}}/api/users в URL, Bearer {{token}} у заголовку. Проблема, яку це лікує, — колекція з п'ятдесятьма запитами, де скрізь захардкоджено хост: змінити стенд означало б редагувати всі п'ятдесят руками. Зі змінною хост лежить в одному місці, і його підміна автоматично розходиться по всіх запитах.

Як прогнати одну колекцію на dev і staging без правки запитів?

Через середовища (environments). Середовище — це набір значень змінних для одного стенда: у dev свої {{baseUrl}} і {{token}}, у staging — свої. У запитах скрізь стоять змінні, а не літеральні хости, тож вибір іншого середовища зі списку переводить усю колекцію на інший стенд — самі запити правити не треба. Усе, що відрізняється між dev/staging/prod — хости, облікові дані, токени — живе в environment-змінних. Це і є стандартна відповідь на питання про мультистендовий прогін: різницю виносимо у середовище, запити лишаємо незмінними.

Які рівні змінних є в Postman і який у них пріоритет?

Базових рівнів (scopes) чотири: global, collection, environment, local — і вужчий скоуп завжди перекриває ширший (п'ятий, data, з'являється лише в data-driven прогонах Collection Runner). Global доступні на весь воркспейс — між колекціями, запитами, скриптами й середовищами; тому годяться хіба для справді спільних значень, а для решти небезпечні: «протікають» туди, де їх ніхто не чекає. Collection живуть у колекції та їдуть з нею при експорті — місце для констант самого API. Environment описують конкретний стенд — усе, що відрізняється між dev/staging/prod. Local зʼявляються лише на час виконання запиту чи прогону й задаються зі скриптів. Коли одна назва визначена на кількох рівнях, перемагає вужчий: local перекриває environment, environment — collection, collection — global. Практичний наслідок: симптом «редагую змінну, а значення не змінюється» майже завжди означає, що та сама назва живе у двох скоупах — правиш ширший, а запит читає вужчий.

Яка чинна модель значень змінної в Postman і де зберігати токен?

Кілька незалежних значень для змінних колекції, середовища й глобальних Postman більше не підтримує. Історично їх було два — initial value (спільне, синхронізувалося з воркспейсом і їхало в експорт) і current value (локальне); ці назви лишилися тільки в розширенні Postman для VS Code. Чинна модель: у змінної одне значення, локальне за замовчуванням, і команді воно стає видимим лише після явного шарингу — тобто секрет лишається на твоїй машині, поки ти сам його не поділив. А офіційна рекомендація Postman для чутливих даних сильніша: тримати їх не у змінній, а в Postman Vault як vault secrets. Порушиш це — і робочий токен розʼїдеться командою через шаринг, експорт чи git: класичний випадок «виглядає як зручність, а насправді витік секрету».

Запит летить, а сервер начебто недоступний. З чого почати діагностику в Postman?

Перша підозра — не мережа, а нерозв'язана змінна. Коли середовище не вибране або в ньому немає потрібної змінної, Postman не скаржиться — він просто шле рядок {{baseUrl}} як частину URL, і замість відповіді прилітає помилка з'єднання чи резолвінгу імені, яку легко сплутати з падінням сервера. Нерозв'язану змінну інтерфейс підсвічує червоним, тож перша перевірка при дивних мережевих фейлах — чи підставились змінні і чи вибране потрібне середовище. Друга типова причина того ж симптому — конфлікт скоупів: змінна з тією ж назвою визначена і в environment, і в колекції, редагуєш одну, а запит бере іншу. Звичка дивитися на підсвічування перед натисканням Send економить години «полювання за примарою».

Що таке auth helpers і як працює «Inherit auth from parent»?

auth helper — генератор заголовка авторизації: на вкладці Authorization обираєш схему (Basic Auth, Bearer Token, API Key, OAuth 2.0), вводиш дані, а коректний заголовок Authorization (для API Key — за вибором заголовок або query-параметр) Postman збирає сам під час надсилання. Це не окрема магія, а зручна форма для того самого заголовка, який інакше довелося б писати руками. Ключова можливість — успадкування (inheritance): налаштувати Authorization можна на трьох рівнях — запит, папка, колекція, — і запит з коробки стоїть у режимі «Inherit auth from parent», тобто бере auth у батька. Налаштував авторизацію один раз на рівні колекції — усі запити отримали її автоматично, а окрема папка чи запит за потреби перекриють (папка «Адмінські операції» під іншим токеном, запит «логін без токена» — No Auth).

Де зберігати токен авторизації, щоб не дублювати його в 50 запитах?

Скласти докупи дві теми — змінні та успадкування. Токен кладемо в environment-змінну {{token}} (значення локальне, поки його явно не пошерили; за офіційною рекомендацією — узагалі в Postman Vault), авторизацію налаштовуємо один раз на рівні колекції: тип Bearer Token, значення — {{token}}. Усі запити успадковують її через «Inherit auth from parent», тож токен фізично лежить в одному місці. Коли токен протухає, правиться одна змінна замість п'ятдесяти запитів, а зміна середовища автоматично підтягує токен відповідного стенда. Альтернатива «вписати токен вручну в кожен запит» дає класичний баг: оновили токен — половина запитів повертає 401 через розсинхрон копій. Саме тому відповідь на це питання показує, чи розумієш ти систему зі скоупів і успадкування, чи просто пам'ятаєш, куди клікати.

Як у Postman додати перевірку без написання складного коду?

Через сніпети (snippets) — готові заготовки коду праворуч від редактора тестів, які вставляються одним кліком. Тест — це шматок JavaScript, який Postman виконує щойно прийшла відповідь (історично вкладка Tests, у нових версіях — Scripts → Post-response), і писати його з нуля не обов'язково. Мінімальний набір, з якого всі починають, — сніпет перевірки статус-коду (pm.response.to.have.status(200)) і перевірки поля тіла. Після прогону вкладка Test Results поруч із відповіддю показує, що пройшло (зелений passed), а що впало (червоний failed з текстом помилки). Це перший крок від «глянув очима» до повторюваної перевірки, яка виконується однаково і в тебе, і в колеги, і коли Collection Runner жене всю колекцію.

Що таке pm.test, pm.response і pm.expect, і коли тест вважається пройденим?

Це три опори тестів у Postman. pm.test оголошує іменовану перевірку (перший аргумент — назва, другий — функція з асертами). pm.response дає доступ до відповіді сервера — статус, тіло (pm.response.json()), заголовки. pm.expect приходить із бібліотеки асертів Chai, яку Postman постачає з коробки, — звідси ланцюжковий BDD-синтаксис (pm.expect(body.id).to.be.a("number")). Зеленим тест стає лише тоді, коли всі асерти всередині пройшли. Тому логіка проста: pm.test — обгортка з іменем, а реальну перевірку роблять асерти всередині; без жодного асерта тест нічого не гарантує.

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

Через класичну пастку «200 OK з помилкою в тілі»: сервер віддає успішний статус, а в тілі лежить помилка або порожні чи некоректні дані. Тест, який асертить тільки status(200), таке пропустить і створить фальшиву впевненість. Тому мінімальна змістовна перевірка додає асерт на конкретне поле тіла — що id числовий, що email дорівнює очікуваному, — і саме поле тіла ловить розбіжність автоматично. Це та сама дисципліна, що з негативними тестами: успішний статус — необхідна, але не достатня умова коректної відповіді.

Чому pm.test без асерта всередині гірший за відсутній тест?

Бо він бреше про покриття. Червоним pm.test робить падіння асерта всередині — а якщо асертів немає взагалі, перевірка нічого не контролює, залишаючись при цьому рядком у звіті. Це гірше за відсутній тест, бо створює фальшиву впевненість. Мінімальна вимога: всередині кожного pm.test — хоча б один справжній асерт (pm.expect чи pm.response.to...). Порожня обгортка — це «виглядає як покриття, а насправді порожня обгортка».

Коли Postman перестає вистачати і команда переходить на код?

Postman перевіряє відповіді, але тест-фреймворк не замінює — межа настає, коли з'являються складні ланцюжки запитів, спільні хелпери й потреба в code review тестової логіки. Тоді команди переходять на код: Playwright APIRequestContext, supertest тощо — там є нормальна структура, версіонування, рев'ю й перевикористання. При цьому сильні сторони Postman нікуди не зникають: дослідження API, ручні перевірки, швидка регресія без розгортання інфраструктури. Сильна відповідь на співбесіді чесно окреслює цю межу замість «Postman вміє все» — це питання на зрілість, а не на знання кнопок.

Три кейси, які складають базу Postman у робочий патерн: налаштувати авторизацію один раз через environment і рівень колекції, діагностувати «сервер недоступний», що насправді є нерозв'язаною змінною, і перетворити ручний перегляд відповіді на повторювану перевірку зі сніпета — а потім перенести ту саму перевірку в код. Скрізь — що робити і чому саме так.

Кейс 1. Авторизація один раз: environment + рівень колекції

Колекція з п'ятдесятьма запитами, кожен ходить під Bearer-токеном. Спокуса — вписати заголовок Authorization у кожен запит; наслідок — токен протух, і половина колекції червоніє 401, бо оновити п'ятдесят копій руками ніхто не встигне. Правильний патерн складає докупи змінні та успадкування: токен лежить в одному місці, авторизація налаштована теж в одному.

Що і де налаштувати:

Далі в самих запитах URL пишеться через змінну, а не через літеральний хост:

GET  {{baseUrl}}/api/users/42
POST {{baseUrl}}/api/orders

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

• Токен не шериться з командою. Кілька незалежних значень (initial/current) Postman більше не підтримує: значення одне й локальне за замовчуванням, і командним воно стає лише за явним шарингом. Пошерене чи вписане в експорт значення поїде всій команді або в git; офіційна рекомендація для чутливих даних — Postman Vault.
• Auth — на рівні колекції, запити успадковують. Один раз обраний Bearer Token зі значенням {{token}} на колекції автоматично застосовується до всіх запитів, бо в них стоїть «Inherit auth from parent». Токен протух — оновлюєш одну змінну; перемкнув середовище на dev — під'їхав token і baseUrl іншого стенда.
• Виняток перекривається локально. Папка «Адмінські операції» ставить собі власний Bearer з іншою змінною, запит «логін без токена» — No Auth. Успадкування задає дефолт, а не жорстке правило.

Кейс 2. «Сервер недоступний» — таблиця рішень

Симптом упізнаваний: натиснув Send, а замість відповіді — помилка з'єднання або дивний резолвінг імені. У Postman перша підозра тут не мережа, а підстановка змінних: якщо середовище не вибране або змінної в ньому немає, Postman не падає з помилкою, а надсилає запит із літеральним текстом у URL.

# Так виглядає запит, коли змінна не підставилась:
GET {{baseUrl}}/api/users/42
    └─ Postman шле це буквально, хоста немає → «сервер недоступний»

Порядок діагностики:

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

• Нерозв'язана змінна підсвічена червоним. Це найдешевша перевірка: перед Send кинь оком на URL і заголовки — червоне означає, що підстановки не буде. Звичка дивитися сюди економить години «полювання за примарою».
• Конфлікт скоупів дає симптом «Postman ігнорує мою змінну». Одна назва визначена і в environment, і в колекції — редагуєш одну, а запит бере іншу, бо вужчий скоуп (environment) перекриває ширший (collection). Ліки: одна змінна — один дім, дублікати між скоупами не заводити.

Кейс 3. Перша перевірка зі сніпета — і місток у код

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

// Сніпет "Status code: Code is 200", адаптований під створення (201)
pm.test("Статус-код 201", () => {
    pm.response.to.have.status(201);
});

// Сніпет "Response body: JSON value check", адаптований під конкретні поля
pm.test("Створений користувач має числовий id і правильний email", () => {
    const body = pm.response.json();
    pm.expect(body.id).to.be.a("number");
    pm.expect(body.email).to.eql("qa@example.com");
});

Та сама перевірка мовою Playwright APIRequestContext — коли колекція переростає в код:

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

test('POST /users створює користувача з валідними даними', async ({ request }) => {
  const res = await request.post('https://staging.example.com/api/users', {
    headers: { Authorization: `Bearer ${process.env.TOKEN}` },
    data: { email: 'qa@example.com', name: 'QA' },
  });

  expect(res.status()).toBe(201);
  const body = await res.json();
  expect(typeof body.id).toBe('number');
  expect(body.email).toBe('qa@example.com');
});

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

• Перевірка поля тіла ловить «200 OK з помилкою в тілі». Асерт лише на статус пропустив би успішну відповідь з порожнім чи неправильним тілом. Перевірка id і email робить статус необхідною, але не достатньою умовою — розбіжність спливає автоматично.
• pm.test без асерта — порожня обгортка. Червоним тест робить падіння асерта всередині; коли асертів немає взагалі, перевірка нічого не гарантує, лишаючись рядком у звіті. Кожен pm.test має містити хоча б один pm.expect або pm.response.to....
• Токен у коді береться з оточення, а не хардкодиться. У Postman секрет живе в непошереному значенні або у Vault, у коді — у process.env.TOKEN. Принцип той самий: секрет не потрапляє в артефакт, який шариться чи їде в git.
• Це та сама перевірка, інша інфраструктура. У Postman вона повторювана в Collection Runner і Newman; у коді — версіонована, з рев'ю й спільними хелперами. Межу переходять, коли з'являються складні ланцюжки й потреба ревʼювати тестову логіку.

Колекція, папки, запити

• Розумію, що колекція — не тека з файлами, а артефакт: структура, документація, авторизація і змінні їдуть разом з нею при експорті, шарингу й прогоні; саме колекцію запускають у Collection Runner чи Newman.
• Можу пояснити два підходи до організації (за ресурсами vs за сценаріями) і коли який доречний.
• Розумію, чому запити називають за перевіркою чи призначенням, а не Get user — той самий принцип, що й з іменуванням тест-кейсів: назва описує, що перевіряємо.

Документування

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

Змінні та середовища

• Можу вставити змінну через {{baseUrl}} / Bearer {{token}} і пояснити, який біль це лікує (хардкод хоста в 50 запитах).
• Розумію, що environment — іменований набір змінних під стенд, і як перемиканням середовища прогнати колекцію на dev/staging без правки запитів.
• Знаю рівні змінних (global, collection, environment, local; у Collection Runner додається data), правило «вужчий скоуп перекриває ширший» і чому дублікат назви у двох скоупах — джерело плутанини («редагую одну, а запит бере іншу»).
• Знаю чинну модель значень (одне значення, локальне за замовчуванням; спільним стає лише за явним шарингом) і що офіційний дім чутливих даних — Postman Vault.
• Розумію, чому нерозв'язана змінна дає літеральний {{baseUrl}} в URL, виглядає як «сервер недоступний» і підсвічена червоним.

Авторизація й успадкування

• Можу пояснити, що auth helper — генератор заголовка Authorization (Basic, Bearer, API Key, OAuth 2.0), а не окрема магія.
• Знаю, як працює «Inherit auth from parent», і що авторизацію налаштовують один раз на колекції, а папка чи запит можуть її перекрити.
• Можу скласти робочий патерн: токен у {{token}} (непошерене значення) + Bearer на рівні колекції + успадкування = одна точка оновлення.
• Розумію, чому ручне дублювання токена в кожному запиті дає 401 на половині після оновлення (розсинхрон копій).

Перевірки зі сніпетів

• Знаю, що тести — це JS після відповіді (Tests / Scripts → Post-response) і що сніпети вставляють заготовки одним кліком.
• Можу пояснити роль pm.test (іменована перевірка), pm.response (доступ до відповіді), pm.expect (асерти Chai) і коли тест зелений.
• Розумію пастку «200 OK з помилкою в тілі» і чому перевірки лише статусу недостатньо.
• Знаю, чому pm.test без асерта гірший за відсутній тест: він нічого не перевіряє, але лишається рядком у звіті.
• Можу окреслити межу Postman: перевірки відповідей, не фреймворк; складні ланцюжки й рев'ю коду → перехід на код (Playwright APIRequestContext, supertest).