Coffee Break: Postman — валідація схеми за допомогою Tiny Validator for JSON schema

Це перша стаття із циклу Coffee break, котрі, як я сподіваюсь, будуть виходити частіше, і мають одну відмінність — це коротка стаття, ціллю якої є стислий огляд інструменту або навіть лише його однієї частини.

Postman — це чудовий інструмент для тестування API, так як дозволяє достатньо легко вирішити цілу низку проблем, які можуть виникати на початкових єтапах тестування і автоматизації.У цій статті ми не будемо говорити про його переваги і недоліки, а детальніше розглянемо одну із вбудованих бібліотек для валідації схемі відповіді, а а саме TV4.

Screenshot displays the Postman interface where users can add a TV4 snippet to a Test tab.

Ця бібліотека доступна до використяння не тільки в Postman, ви так само можете встановити її за допомогою npm i tv4 і використовувати її для валідації в будь-якому JS фреймворку. Це робить TV4 більш цікавою, так як не прийдеться вивчати її лише для Postman, і перевчатися на щось інше згодом.

Тепер же розглянемо на прикладі, у нас є відповідь від сервера:

{
    "first_name": "Ivan",
    "second_name": "Ivanov",
    "age": 45,
    "married": true
}

Схема валідації для неї буде мати наступний вигляд:

{
    "type": "object",
    "properties": {
        "first_name": {
            "type": "string"
        },
        "second_name": {
            "type": "string"
        },
        "age": {
            "type": "number"
        },
        "married": {
            "type": "boolean"
        }
    },
    "required": [
        "first_name",
        "second_name",
        "age",
        "married"
    ]
}

Швидесенько розглянемо що ж тут написано.

1. Для початку ми вказуємо тип відповіді — обʼєкт у нашому випадку. Далі описуємо властивості (поля) обʼєкта через properties , де спочатку зазначаємо імʼя поля, після чого всередені фігурних дужок вказуємо його тип. Існують наступні типи: object, array, string, boolean, null, number/integer.
2. Порядку полів притримуватись не обовʼязково, хоча для зручності все ж таки варто копіювати порядок, що і у відповіді.
3. В самому низу зазначаються обовʼязкові поля, котрі мають бути у відповіді.

Також ви можете вказати декілька можливих варіантів типу поля, на приклад:

"married": {
   "type": ["boolean", "null"]
}

Розглянемо трохи складніший приклад, котрий, тим не менш, буде зустрічатися доволі часто:

{
    "records": [
        {
            "id": 12345,
            "date": "00.00.0000",
            "license": "some license"
        },
        {
            "id": 12346,
            "date": null
        }
    ]
}

Схема валідації для нього буде виглядати наступним чином:

{
    "type": "object",
    "properties": {
        "records": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "number"
                    },
                    "date": {
                        "type": ["string", "null"]
                    },
                    "license": {
                        "type": "string"
                    }
                },
                "required": [
                    "id",
                    "date"
                ]
            }
        }
    }
}

Декілька моментів, на котрі варто звернути увагу:

• схема елементів масиву описується через поле items
• обовʼязкові поля треба вказувати всередені обʼєкту, котрому вони належать. Якщо вказати їх у корні — перевірка не пройде.

Як використовувати це в тестах?

Сніпет дає уяву про те, як правильно писати тести для валідації схеми. Лише одна проблема є у прикладі, це логування помилок, так як все що ви отримаєте у цьому випадку — це false expect to be true. А що, на кшталт отримання данних про природу помилки? Для цього нам треба звернутися до обʼєкту errors у результаті валідації. Він має наступну структуру:

{
    "valid": false,
    "errors": [{}],
    "missing": [...]
}

Тобто, щоб все це отримувати у тесті, можно просто записати це у наступному вигляді:

pm.test(`${request.name} - schema is valid`, () => {
  const result = tv4.validateMultiple(jsonData, schema);
  
  if(!result.valid) result.errors.forEach(error => 
  console.log(`Validation error: ${error.message}. Path: ${error.schemaPath}`));
  
  pm.expect(result.valid).to.be.true;
});

В цьому прикладі варто звернути увагу на функцію validateMultiple. Її відмінність від validate у тому, що tv4 зупинить перевірку із негативним результатов як тільки знайде перше неспівпадіння. У випадку ж із validateMultiple, перевірка буде проведена у повному обсязі і, відповідно, ви зможете вивести усі помилки за одну перевірку.

І це ще не все, що можливо робити за допомогою цієї бібліотеки, але все ж таки достатньо, щоб додати її до ваших перевірок, якщо ви вже використовуєте Postman. Всі додаткові можливості ви можете подивитись у офіційній документації на сайті npm. А на цьому все, дякую за увагу і до наступних зустрічей.🇺🇦