# **Postman — инструмент для работы с API**

## 1. Что такое Postman

**Postman** — это кроссплатформенный инструмент (десктопное приложение и веб-версия), предназначенный для работы с API на всех этапах: от разработки и тестирования до документирования и мониторинга.

Основные возможности Postman:

- отправка HTTP-запросов любых методов (GET, POST, PUT, DELETE, PATCH и др.)
- поддержка REST, GraphQL, WebSocket, gRPC
- управление переменными на разных уровнях (глобальные, коллекции, окружения)
- написание автоматических тестов на JavaScript
- последовательный запуск наборов запросов через Collection Runner
- автоматическая генерация документации
- создание мок-серверов для имитации API
- мониторинг работоспособности API в production
- совместная работа в команде через Workspaces
- интеграция с CI/CD системами через утилиту Newman

Postman — один из самых популярных инструментов среди разработчиков, QA-инженеров и технических писателей.

## 2. Зачем нужен Postman

| Задача                              | Как помогает Postman                                                                 |
|-------------------------------------|---------------------------------------------------------------------------------------|
| Быстрая проверка эндпоинта          | Отправить запрос и увидеть ответ за несколько секунд                                 |
| Отладка API                         | Полная информация: статус-код, заголовки, тело ответа, время, cookies, консоль       |
| Автоматическое тестирование         | Проверки статуса, структуры данных, типов значений, наличия полей                    |
| Регрессионное тестирование          | Запуск всей группы запросов одним действием через Runner                             |
| Работа с разными средами            | Легкое переключение между тестовым, разработческим и продакшен-серверами             |
| Документирование API                | Автоматическое создание читаемой документации по коллекции                           |
| Мониторинг доступности              | Периодические проверки ключевых эндпоинтов                                           |
| Обучение и демонстрация             | Удобно показать заказчику или новому коллеге, как работает API                       |

## 3. Как создать коллекцию

Коллекция — это логически сгруппированный набор запросов, который можно организовать в папки.

Порядок создания:

1. В левой панели перейти в раздел **Collections**
1. Нажать **+** и выбрать **Blank collection**
1. Указать название коллекции
1. Внутри коллекции создать папки для логической группировки запросов
1. В каждой папке создавать новые запросы (New -> HTTP Request)

![](screens/1z.png)

Типичная структура коллекции может включать папки по функциональным блокам системы.

## 4. Как создать переменные и заполнить их

В Postman переменные бывают нескольких типов:

| Уровень          | Где создаётся                     | Приоритет | Типичные примеры                         |
|------------------|-----------------------------------|-----------|------------------------------------------|
| Environment      | Раздел Environments               | Высокий   | базовый URL, токены, ключи API           |
| Collection       | Вкладка Variables коллекции       | Средний   | версия API, общий путь, константы        |
| Global           | Глобальные переменные             | Низкий    | редко используемые общие значения         |

### 4.1 Создание переменной в окружении

![](screens/8z.png)

1. Перейти в левый сайдбар -> **Environments**
2. Нажать **Create new environment** или кнопку +
3. Задать имя окружения
4. Добавить переменную:
   - в поле Variable указать имя (например: `baseURL`)
   - в поле Value указать значение (например: адрес сервера)
5. Сохранить

---

### 4.2 Создание переменной в коллекции

![](screens/2z.png)

1. Открыть нужную коллекцию
2. Перейти на вкладку **Variables**
3. Нажать **Add variable**
4. Указать имя и значение

---

В запросах переменные вставляются в двойных фигурных скобках:  
`{{baseURL}}/endpoint`  

![](screens/9z.png)

---

### 4.3 Как автоматически сохранять значение из ответа

Очень часто после запроса на логин нужно взять `token` (или `access_token`, `id` созданной сущности и т.п.) и сохранить его в переменную, чтобы использовать в последующих запросах.

Это делается в вкладке **Scripts** каждого запроса.

### Пример: сохранение токена после логина

1. Откройте запрос на авторизацию
2. Перейдите во вкладку **Scripts**.
3. Напишите примерно такой скрипт:

```javascript
// 1. Проверяем успешный статус
pm.test("Логин успешен — статус 200", function () {
    pm.response.to.have.status(200);
});

// 2. Получаем тело ответа как объект
const jsonData = pm.response.json();

// 3. Проверяем, что токен пришёл
pm.test("В ответе есть поле token", function () {
    pm.expect(jsonData).to.have.property("token");
    pm.expect(jsonData.token).to.be.a("string").that.is.not.empty;
});

// 4. Сохраняем токен в переменную коллекции
if (jsonData.token) {
    pm.collectionVariables.set("authToken", jsonData.token);
    console.log("Токен сохранён: " + jsonData.token.substring(0, 15) + "...");
}
```

## 5. Как настроить и применить окружение

1. Создать или открыть нужное окружение в разделе Environments
2. В правом верхнем углу интерфейса Postman найти выпадающий список окружений
3. Выбрать требуемое окружение (оно подсвечивается цветом)
4. После выбора все переменные из этого окружения становятся активными

![](screens/4z.png)

Если одна и та же переменная определена и в окружении, и в коллекции — значение из **окружения** имеет приоритет.

## 6. Как выполнять тесты в UI и в Collection Runner

### 6.1. Тесты для отдельного запроса (в интерфейсе)

1. Открыть запрос
2. Перейти на вкладку **Scripts**
3. Написать проверки на JavaScript:

```javascript
pm.test("Статус 200 OK", function () {
    pm.response.to.have.status(200);
});

pm.test("Ответ содержит массив", function () {
    const json = pm.response.json();
    pm.expect(json).to.be.an("array");
});
```

4. Нажать **Send**
5. После ответа посмотреть блок **Test Results** — зелёные PASS / красные FAIL}

![](screens/5z.png)

### 6.2. Запуск всех тестов через Collection Runner

1. Нажать на три точки справа от нужной коллекции
2. Нажать кнопку **Run**

![](screens/10z.png)

3. В окне Runner:
   - выбрать нужное окружение
   - указать количество итераций (обычно 1 для обычного запуска)
   - задать задержку между запросами (Delay), если нужно
   - выбрать режим: Run manually
4. Нажать кнопку запуска

После выполнения отображается сводный результат:
- общее время выполнения коллекции
- количество пройденных / проваленных тестов
- среднее время ответа
- детальный отчёт по каждому запросу (статус, время, размер ответа, результаты тестов)

### 6.3. Запуск тестов в консоли с помощью Newman

Newman — это официальная консольная утилита от команды Postman, которая позволяет запускать коллекции вне графического интерфейса. Это особенно полезно для автоматизации тестирования в CI/CD-пайплайнах (GitHub Actions, GitLab CI, Jenkins и др.), ночных регрессиях и повторяемых проверках без открытия Postman.

**Основная команда запуска:**

```bash
newman run Avtomat.postman_collection.json -e mvavilov.postman_environment.json
```

**Расшифровка команды:**

- `newman run` — команда запуска коллекции  
- `Avtomat.postman_collection.json` — файл экспортированной коллекции (формат v2.1)  
- `-e mvavilov.postman_environment.json` — флаг `-e` указывает файл окружения, из которого берутся все переменные (в том числе `baseURL`, токены и другие настройки)

**Предварительные шаги:**

1. Установить Newman глобально (один раз):

```bash
npm install -g newman
```

2. Экспортировать коллекцию и окружение из Postman:
   - Коллекция -> три точки -> More -> Export -> сохранить как `Avtomat.postman_collection.json`
   - Окружение -> три точки -> More -> Export -> сохранить как `mvavilov.postman_environment.json`

3. Перейти в директорию с файлами:

```bash
cd путь/к/папке/с/экспортированными/файлами
```

**Рекомендуемые варианты запуска:**

- Базовый запуск с подробным выводом:

```bash
newman run Avtomat.postman_collection.json -e mvavilov.postman_environment.json --reporters cli
```

- С сохранением HTML-отчёта (очень удобно для проверки и демонстрации):

```bash
newman run Avtomat.postman_collection.json \
  -e mvavilov.postman_environment.json \
  --reporters cli,html \
  --reporter-html-export report.html
```

После выполнения в терминале отображается:

- список всех запросов коллекции  
- статус-коды ответов  
- количество пройденных / проваленных тестов  
- время выполнения каждого запроса и общее время  
- детальная информация об ошибках (если тесты упали)

![](screens/11z.png)