Налаштування тестування API 1С-Бітрікс (Postman/Newman)

Налаштування тестування API 1С-Бітрікс (Postman/Newman)

REST API 1С-Бітрікс виходить з ладу в неочікуваних місцях: оновлення ядра змінює формат відповіді, кастомний контролер починає повертати null замість порожнього масиву, інтеграція із зовнішньою системою ламається через зміщення в структурі даних. Без автоматизованих тестів це виявляється в продакшені.

Структура колекції Postman

Колекція організовується за доменними областями, а не за HTTP-методами. Для магазину на Бітрікс типова структура:

Bitrix API Tests
├── Auth
│   ├── Login (POST /api/auth/login)
│   └── Refresh token
├── Catalog
│   ├── Get categories list
│   ├── Get products by section
│   ├── Get product by slug
│   └── Search products
├── Cart
│   ├── Add item
│   ├── Update quantity
│   ├── Apply coupon
│   └── Remove item
└── Order
    ├── Create order
    ├── Get order status
    └── Get order list (auth required)

Змінні оточення

Критично важливо розділити оточення — не запускати тести на продакшені:

{
  "id": "local-env",
  "name": "Local",
  "values": [
    { "key": "base_url",      "value": "https://dev.shop.example.com" },
    { "key": "api_prefix",    "value": "/local/ajax/api/v1" },
    { "key": "user_email",    "value": "[email protected]" },
    { "key": "user_password", "value": "testpass123" },
    { "key": "auth_token",    "value": "" }
  ]
}

Токен авторизації отримується в Pre-request Script запиту авторизації і зберігається в змінну для всієї колекції:

// Pre-request Script запиту авторизації
pm.sendRequest({
    url: pm.environment.get('base_url') + pm.environment.get('api_prefix') + '/auth/login',
    method: 'POST',
    header: { 'Content-Type': 'application/json' },
    body: {
        mode: 'raw',
        raw: JSON.stringify({
            login:    pm.environment.get('user_email'),
            password: pm.environment.get('user_password')
        })
    }
}, function(err, res) {
    const token = res.json().data.token;
    pm.environment.set('auth_token', token);
});

Тести для API каталогу Бітрікс

Приклад тестів для ендпоінту списку товарів:

// Вкладка Tests запиту GET /catalog/products
pm.test('Status 200', () => {
    pm.response.to.have.status(200);
});

pm.test('Response structure', () => {
    const body = pm.response.json();
    pm.expect(body).to.have.property('status', 'ok');
    pm.expect(body).to.have.property('data');
    pm.expect(body.data).to.have.property('items').that.is.an('array');
    pm.expect(body.data).to.have.property('total').that.is.a('number');
    pm.expect(body.data).to.have.property('pages').that.is.a('number');
});

pm.test('Product has required fields', () => {
    const items = pm.response.json().data.items;
    if (items.length > 0) {
        const product = items[0];
        pm.expect(product).to.have.keys(['id', 'name', 'slug', 'price', 'currency', 'in_stock']);
        pm.expect(product.price).to.be.a('number').and.to.be.above(0);
        pm.expect(product.currency).to.equal('RUB');
    }
});

pm.test('Response time < 500ms', () => {
    pm.expect(pm.response.responseTime).to.be.below(500);
});

// Зберігаємо slug першого товару для наступних запитів
const items = pm.response.json().data.items;
if (items.length > 0) {
    pm.environment.set('test_product_slug', items[0].slug);
    pm.environment.set('test_product_id', items[0].id);
}

Тест створення замовлення

// Tests для POST /order/create
pm.test('Order created', () => {
    const body = pm.response.json();
    pm.response.to.have.status(200);
    pm.expect(body.status).to.equal('ok');
    pm.expect(body.data).to.have.property('order_id').that.is.a('number');
    pm.expect(body.data.order_id).to.be.above(0);
});

pm.test('Order ID saved', () => {
    const orderId = pm.response.json().data.order_id;
    pm.environment.set('last_order_id', orderId);
    pm.expect(orderId).to.be.a('number');
});

Запуск через Newman у CI/CD

Newman — CLI-версія Postman, запускається в будь-якому CI-контурі без GUI. Експортуємо колекцію та оточення з Postman, кладемо до репозиторію.

# Встановлення
npm install -g newman newman-reporter-htmlextra

# Запуск із HTML-звітом
newman run tests/postman/bitrix-api.collection.json \
  --environment tests/postman/staging.environment.json \
  --reporters cli,htmlextra \
  --reporter-htmlextra-export reports/api-test-report.html \
  --bail

# GitLab CI
api-tests:
  stage: test
  image: node:20-alpine
  script:
    - npm install -g newman newman-reporter-htmlextra
    - newman run tests/postman/bitrix-api.collection.json
        --environment tests/postman/staging.environment.json
        --reporters cli,htmlextra
        --reporter-htmlextra-export reports/api-test-report.html
        --bail
  artifacts:
    when: always
    paths:
      - reports/api-test-report.html
    expire_in: 7 days

Типові проблеми API 1С-Бітрікс

Кілька конкретних речей, на які варто написати тести превентивно:

Числа як рядки. Бітрікс часто повертає "price": "1500.00" замість "price": 1500. Після оновлення або рефакторингу тип може змінитися. Тест: pm.expect(typeof product.price).to.equal('number').

Порожній масив vs null. Стандартні методи Бітрікс при порожній вибірці можуть повернути false, null або [] — залежно від обгортки. Зовнішня система очікує масив. Тест: pm.expect(body.data.items).to.be.an('array').

Кодування. При міграції на інший сервер кирилиця в полях іноді ламається. Тест: pm.expect(product.name).to.match(/[а-яА-Я]/) для продуктів із кириличними назвами.

Підтримка колекції

Колекція — живий артефакт. При додаванні нового ендпоінту в 1С-Бітрікс одразу додавайте тест у Postman. Перевірка структури відповіді займає 10 хвилин, але виявляє регресію до потрапляння в продакшен.