10 Chai Assertions

title: "Chai Assertions in Postman" description: "Use Chai assertion patterns in Postman including expect, should, and assert interfaces, deep equality, property chains, nested assertions, and custom plugins for comprehensive API testing." weight: 10 date: 2026-06-28 lastmod: 2026-06-28 tags: [api-development, postman] }

Chai is the assertion library underlying Postman's pm.expect. It provides three interfaces: expect (BDD style), should (chainable), and assert (TDD style). Understanding Chai patterns enables more expressive and readable Postman tests.

What You'll Learn

• Chai expect, should, and assert interfaces
• Property chains and language chains
• Deep property inclusion
• Nested property access
• Custom error messages

Why It Matters

Chai's expressive syntax makes tests read like natural language. Deep property assertions simplify nested JSON validation. Custom error messages help debug failures faster.

Real-World Use

Chai is used by thousands of Node.js projects. Postman bundles Chai for all test scripts. Many API test frameworks build on Chai's assertion patterns.

flowchart LR
    Chai[Chai Assertions] --> Expect[expect() BDD]
    Chai --> Should[should BDD]
    Chai --> Assert[assert TDD]
    Expect --> Language[Language Chains: to, be, been, is, that, have, and]
    Expect --> Properties[Property Assertions]
    Expect --> Comparison[Comparison Assertions]

Teacher Mindset

Use the expect interface for consistency with Postman documentation. Chain language words (to, have, property) for readability. Use deep property checks for nested objects.

Code Examples

// Example 1: Language chains
pm.test('Language chain examples', () => {
    const body = pm.response.json();

    pm.expect(body).to.be.an('object');
    pm.expect(body).to.have.property('name');
    pm.expect(body).to.have.property('tags').that.is.an('array');
    pm.expect(body).to.have.property('address').that.is.an('object')
        .that.has.property('city');
});

pm.test('Chained assertions for lists', () => {
    const items = pm.response.json().items;
    pm.expect(items).to.be.an('array')
        .that.has.lengthOf.at.least(1)
        .and.to.have.property('0')
        .that.has.property('id');
});

// Example 2: Deep property assertions
const body = pm.response.json();

pm.test('Deep property checks', () => {
    // Check nested property existence
    pm.expect(body).to.have.nested.property('user.name');
    pm.expect(body).to.have.nested.property('user.address.city');

    // Check nested property value
    pm.expect(body).to.have.nested.property('user.role', 'admin');

    // Deep inclusion
    pm.expect(body).to.have.deep.property('settings', {
        theme: 'dark',
        notifications: true
    });
});

pm.test('Nested array properties', () => {
    pm.expect(body)
        .to.have.nested.property('orders[0].id')
        .that.is.a('string');

    pm.expect(body)
        .to.have.nested.property('orders[0].items')
        .that.is.an('array')
        .with.lengthOf.at.least(1);
});

// Example 3: Custom assertions and comparison
pm.test('Custom comparison assertions', () => {
    const body = pm.response.json();

    // Number comparisons
    pm.expect(body.page).to.be.at.least(1);
    pm.expect(body.total).to.be.at.most(10000);

    // String length
    pm.expect(body.name).to.have.lengthOf.at.least(2);
    pm.expect(body.name).to.have.lengthOf.at.most(100);

    // Inclusion
    pm.expect(body.status).to.be.oneOf(['active', 'inactive', 'pending']);
    pm.expect(body.tags).to.include.members(['new', 'featured']);

    // Custom error message
    pm.expect(body.email, 'Email is required').to.not.be.empty;
    pm.expect(body.id, `Expected ID to be a string, got ${typeof body.id}`)
        .to.be.a('string');
});

Common Mistakes

• Mixing expect and assert interfaces inconsistently
• Not using deep property (nested) for nested objects
• Forgetting that chai comparisons are strict (===) by default
• Not using custom error messages for complex assertions
• Over-chaining with too many language words

Practice

1. Write assertions using language chains (to.have.property.that.is.an).
2. Use deep.nested.property for checking nested object values.
3. Write assertions with custom error messages.
4. Use oneOf, include.members, and lengthOf assertions.
5. Challenge: Write a complex assertion chain that validates a deeply nested order response with items, pricing, and shipping address.

FAQ

Mini Project

Write Chai assertions for a complex API response (order with nested items): check top-level properties (id, status, total), deep nested properties (customer.name, items[0].productId), array properties (items length > 0, all items have price), string patterns (date format, email), and use custom error messages for each assertion.

What's Next

Next, you will learn about workflows and request chaining with setNextRequest.