Настройка тестирования API 1С-Битрикс (Postman/Newman)

Настройка тестирования API 1С-Битрикс (Postman/Newman)

REST API Битрикс выходит из строя в неожиданных местах: обновление ядра меняет формат ответа, кастомный контроллер начинает возвращать 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 Битрикс

Несколько конкретных вещей, на которые стоит написать тесты превентивно:

Числа как строки. Битрикс часто возвращает "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(/[а-яА-Я]/) для продуктов с кириллическими названиями.

Поддержка коллекции

Коллекция — живой артефакт. При добавлении нового эндпоинта в Битрикс сразу добавляйте тест в Postman. Проверка структуры ответа занимает 10 минут, а ловит регрессию до попадания в прод.