Maeris logo
Get started for free

Advanced API Assertions

Learn advanced assertion techniques to create comprehensive and robust API validations in Maeris.

Overview

Advanced assertions allow you to create complex validations using scripts, custom logic, JSON path expressions, and sophisticated comparison operators. These techniques enable you to validate complex scenarios that basic assertions cannot handle.

JSON Path Assertions

JSON Path allows you to extract and validate specific values from complex nested JSON structures.

Common JSON Path Expressions

Examples:
$.data.users[0].id - First user's ID
$.data.users[*].email - All user emails
$.data.users[?(@.status == 'active')] - Active users
$.data.items.length() - Number of items
$.data.total - Total value

Assertion Examples

Assert $.data.users[0].status equals "active"
Assert $.data.items.length() is greater than 10
Assert $.data.total is a number
Assert $.data.users[*].email contains "@example.com"

Script-Based Assertions

For complex validation logic, you can write custom scripts using JavaScript to perform sophisticated checks.

Script Assertion Examples

Validate Array Order:
const items = pm.response.json().data.items;
const sorted = [...items].sort((a, b) = a.id - b.id);
pm.expect(items).to.eql(sorted);
Validate Date Format:
const date = pm.response.json().data.createdAt;
const dateRegex = /^\d4-\d2-\d2T\d2:\d2:\d2/;
pm.expect(date).to.match(dateRegex);
Validate Unique Values:
const emails = pm.response.json().data.users.map(u = u.email);
const uniqueEmails = [...new Set(emails)];
pm.expect(emails.length).to.equal(uniqueEmails.length);

Schema Validation

Validate that responses match a JSON schema, ensuring data structure and types are correct.

Schema Validation Example

Schema:
{
"type": "object",
"required": ["id", "name", "email"],
"properties": {
"id": { "type": "number" },
"name": { "type": "string" },
"email": { "type": "string", "format": "email" }
}
}

Assert that the response matches this schema to ensure data integrity.

Conditional Assertions

Create assertions that only run under certain conditions, allowing for flexible validation logic.

Conditional Examples

If status is 200, validate data:
if (pm.response.code === 200) {
pm.expect(pm.response.json().data).to.exist;
pm.expect(pm.response.json().data.id).to.be.a('number');
}
Validate based on user role:
const role = pm.response.json().user.role;
if (role === 'admin') {
pm.expect(pm.response.json().permissions).to.exist;
}

Array and Collection Assertions

Validate arrays and collections with advanced checks like sorting, uniqueness, and element validation.

Assert array length is greater than 0
Assert all array elements have required fields
Assert array is sorted by ID
Assert all emails in array are unique
Assert array contains specific element
Assert array elements match pattern

Performance Assertions

Validate API performance characteristics beyond simple response time checks.

  • Assert response time is within acceptable range
  • Assert response size is reasonable
  • Assert number of redirects is minimal
  • Assert connection time is fast
  • Compare response times across requests

Best Practices

  • Start Simple: Use basic assertions when possible, only use advanced techniques when needed
  • Document Complex Logic: Add comments to explain complex assertion logic
  • Reuse Assertions: Create reusable assertion scripts for common patterns
  • Test Assertions: Verify that your assertions work correctly before relying on them
  • Handle Edge Cases: Consider null values, empty arrays, and missing fields
  • Performance: Keep assertion scripts efficient to avoid slowing down tests
  • Error Messages: Use descriptive error messages in custom assertions

Next Steps