Setting up 1C-Bitrix API testing (Postman/Newman)

Setting Up API Testing for 1C-Bitrix (Postman/Newman)

The 1C-Bitrix REST API breaks in unexpected places: a core update changes the response format, a custom controller starts returning null instead of an empty array, an external system integration breaks due to a shift in the data structure. Without automated tests, this is discovered in production.

Postman Collection Structure

Organize the collection by domain area, not by HTTP method. For a Bitrix store, a typical structure is:

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)

Environment Variables

Separating environments is critical — do not run tests against production:

{
  "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": "" }
  ]
}

The auth token is obtained in the Pre-request Script of the authentication request and stored in a variable for the entire collection:

// Pre-request Script for the auth request
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);
});

Tests for the Bitrix Catalog API

Example tests for the product list endpoint:

// Tests tab for 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);
});

// Save the first product's slug for subsequent requests
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);
}

Order Creation Test

// Tests for 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');
});

Running via Newman in CI/CD

Newman is the CLI version of Postman; it runs in any CI pipeline without a GUI. Export the collection and environment from Postman and commit them to the repository.

# Install
npm install -g newman newman-reporter-htmlextra

# Run with HTML report
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

Common 1C-Bitrix API Issues

Several specific issues worth writing preventive tests for:

Numbers as strings. Bitrix often returns "price": "1500.00" instead of "price": 1500. The type can change after an update or refactor. Test: pm.expect(typeof product.price).to.equal('number').

Empty array vs null. Standard Bitrix methods may return false, null, or [] for an empty result set — depending on the wrapper. An external system expects an array. Test: pm.expect(body.data.items).to.be.an('array').

Encoding. After migrating to a different server, Cyrillic characters in fields sometimes break. Test: pm.expect(product.name).to.match(/[а-яА-Я]/) for products with Cyrillic names.

Maintaining the Collection

The collection is a living artifact. When a new endpoint is added to 1C-Bitrix, add a test to Postman immediately. Verifying the response structure takes 10 minutes and catches regressions before they reach production.