Тестируем REST API с JSON Schema и Postman/Newman

Привет! Если ты хочешь, чтобы твои API не ломались после каждого обновления, а тесты были надёжными и автоматическими — добро пожаловать в мир JSON Schema, Postman и Newman. В этой статье мы:

• Подключим JSON Schema к Postman.
• Напишем тесты для проверки структуры ответов.
• Автоматизируем тестирование с помощью Newman.
• Рассмотрим реальные примеры с комментариями.

Готов? Поехали! 🚀

🧩 Что такое JSON Schema и зачем оно Postman?

JSON Schema — это способ описания структуры JSON-данных. Например, ты можешь описать, что объект должен содержать строку name и число age. Это полезно для:

• Проверки, что API возвращает правильные данные.
• Обнаружения изменений в структуре ответов.
• Автоматического тестирования.

Postman поддерживает валидацию JSON Schema с помощью встроенной библиотеки Ajv (Another JSON Schema Validator). Это позволяет проверять, соответствует ли ответ API заданной схеме.

🔧 Подключаем JSON Schema к Postman

1. Создаём схему. Например, для ответа с полями name (строка) и age (число):{
   "type": "object",
   "properties": {
   "name": { "type": "string" },
   "age": { "type": "number" }
   },
   "required": ["name", "age"]
   }
   
2. Добавляем тест в Postman. Вкладка Tests:const schema = { /* твоя схема */ };
   
   pm.test("Response matches schema", () => {
   pm.response.to.have.jsonSchema(schema);
   });
   
3. Отправляем запрос. Если ответ соответствует схеме, тест пройдёт успешно.

🧪 Примеры тестов с комментариями

1. Проверка пустого объекта

Ответ:

{}

Схема:

{
"type": "object"
}

Тест:

const schema = { "type": "object" };

pm.test("Response is an empty object", () => {
pm.response.to.have.jsonSchema(schema);
});

2. Проверка обязательных полей

Ответ:

{
"name": "Alice",
"age": 30
}

Схема:

{
"type": "object",
"properties": {
"name": { "type": "string" },
"age": { "type": "number" }
},
"required": ["name", "age"]
}

Тест:

const schema = {
"type": "object",
"properties": {
"name": { "type": "string" },
"age": { "type": "number" }
},
"required": ["name", "age"]
};

pm.test("Response matches schema", () => {
pm.response.to.have.jsonSchema(schema);
});

3. Проверка вложенных объектов

Ответ:

{
"user": {
"id": 1,
"name": "Alice"
}
}

Схема:

{
"type": "object",
"properties": {
"user": {
"type": "object",
"properties": {
"id": { "type": "integer" },
"name": { "type": "string" }
},
"required": ["id", "name"]
}
},
"required": ["user"]
}

Тест:

const schema = {
"type": "object",
"properties": {
"user": {
"type": "object",
"properties": {
"id": { "type": "integer" },
"name": { "type": "string" }
},
"required": ["id", "name"]
}
},
"required": ["user"]
};

pm.test("Response matches nested schema", () => {
pm.response.to.have.jsonSchema(schema);
});

4. Проверка массива объектов

Ответ:

[
{ "id": 1, "name": "Alice" },
{ "id": 2, "name": "Bob" }
]

Схема:

{
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "integer" },
"name": { "type": "string" }
},
"required": ["id", "name"]
}
}

Тест:

const schema = {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "integer" },
"name": { "type": "string" }
},
"required": ["id", "name"]
}
};

pm.test("Response matches array schema", () => {
pm.response.to.have.jsonSchema(schema);
});

🧰 Автоматизируем тестирование с Newman

Newman — это командная утилита для запуска коллекций Postman из командной строки.

1. Устанавливаем Newman:npm install -g newman
   
2. Экспортируем коллекцию из Postman:
   В Postman: File → Export → Collection.
3. Запускаем коллекцию с помощью Newman:newman run path/to/your_collection.json
   
4. Просматриваем результаты. Newman выведет в консоль результаты тестов.

🧪 Примеры задач для новичков и профессионалов

🛠️ Хитрости и лучшие практики

1. Используй JSON Schema Draft 7 (или новее)

Postman использует Ajv под капотом, он отлично поддерживает Draft-07. Убедись, что твоя схема начинается с:

{ "$schema": "http://json-schema.org/draft-07/schema#" }

2. Проверяй структуру, а не значения

Postman и JSON Schema отлично подходят для проверки формата, но не логики. Например:

// Это ок
pm.test("Age is a number", () => {
const data = pm.response.json();
pm.expect(data.age).to.be.a("number");
});

// А вот проверка "не старше 100 лет" — лучше в отдельном логическом тесте

3. Делай схемы переиспользуемыми

Если API возвращает одинаковый формат ответа (например, user), выноси это в переменную или внешний файл. Это упрощает поддержку.

const userSchema = {
type: "object",
properties: {
id: { type: "integer" },
name: { type: "string" }
},
required: ["id", "name"]
};

4. Валидация ошибок — тоже важна!

Хорошее API возвращает предсказуемые ошибки. Проверяй, что 400-ые и 500-ые ответы соответствуют формату ошибки:

{
"error": "Bad Request",
"message": "Field 'email' is required"
}

Схема:

const errorSchema = {
type: "object",
properties: {
error: { type: "string" },
message: { type: "string" }
},
required: ["error", "message"]
};

pm.test("Error response matches schema", () => {
if (pm.response.code >= 400) {
pm.response.to.have.jsonSchema(errorSchema);
}
});

🤖 Интеграция в CI/CD с Newman

GitHub Actions пример:

name: Run Postman tests

on: [push]

jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Install Node.js
uses: actions/setup-node@v3
with:
node-version: 18

- name: Install Newman
run: npm install -g newman

- name: Run collection
run: newman run collection.json -e environment.json --reporters cli,junit --reporter-junit-export results.xml

Идеально сочетается с отчётами в CI/CD, где ты можешь даже фейлить сборку, если схема не проходит.

📚 Заключение

Использование JSON Schema в Postman и Newman:

✅ Повышает надёжность тестов

✅ Помогает автоматизировать контроль качества

✅ Защищает от "невидимых" изменений в API

✅ Работает в любом CI/CD пайплайне

🔥 TL;DR (если ты промотал всё это)

• Пиши схемы → вставляй в pm.test() → запускай в Newman → наслаждайся надёжными тестами.
• JSON Schema ≠ страшно. Это твой союзник в борьбе с багами и хаосом в API.