Assertions & Validation

Assertions validate that the API response meets expected criteria. The API Node provides a powerful and flexible assertion engine that runs automatically after each API call.

Overview

API Node assertions validate:

Response data - Body content and structure
Status codes - HTTP response status
Headers - Response headers
Response time - Performance checks

For detailed information on assertion types, operators, and syntax, see the Assertions Reference.

How Assertions Work

API request executes
Response is received
Assertions run against response.data, response.status, response.headers
If all assertions pass → Continue to next node
If any assertion fails → Test stops (unless configured otherwise)

Assertion Types

Standard Assertions

Use built-in operators to validate response data:

Left: response.data.user.id
Operator: equals
Right: "12345"

Custom Assertions

Reference reusable assertion functions from Script Library:

Assertion Type: Custom
Function: isValidUser (from Script Library)
Parameters:
  - user: response.data.user

Iterator Assertions

Validate all items in an array:

Path: response.data.items
Assertions:
  - Left: status
    Operator: equals
    Right: "active"

Assertion Groups

Apply predefined sets of related assertions:

Assertion Groups:
  - Standard API Response Validation
  - Security Headers Check

For complete details on these assertion types, see the Assertions Reference.

Configuration Options

Assertion Condition

Control when assertions run using a JSONata expression:

Condition: response.status = 200

Assertions are skipped if the condition evaluates to false.

Continue on Failure

When enabled, assertion failures are logged but test execution continues. Useful for:

Collecting all validation failures in one run
Non-critical assertions that shouldn’t block the test

Examples

Response Data Validation

Assertion 1: User ID is a number
  Left: response.data.user.id
  Operator: isNumber

Assertion 2: User email is valid
  Left: response.data.user.email
  Operator: isEmail

Assertion 3: User is active
  Left: response.data.user.status
  Operator: equals
  Right: "active"

Status Code Validation

Left: response.status
Operator: equals
Right: 200

Response Header Validation

Left: response.headers["content-type"]
Operator: contains
Right: "application/json"

Array Response Validation

Path: response.data.items
Assertions:
  - Left: id
    Operator: exists
  - Left: price
    Operator: greaterThan
    Right: 0

This validates that all items have an id and a positive price.

Best Practices

Start with status code: Always validate response.status first
Validate structure: Check that required fields exist before validating their values
Use specific paths: Target specific fields rather than broad checks
Group related assertions: Use Assertion Groups for commonly-used validation sets
Create custom assertions for complex logic: Move complex validation logic to Script Library for reusability

Common Patterns

Basic API Contract Validation

Assertions:
  1. Status is 200
  2. Response has "data" property
  3. Data has "id" property
  4. Data has "name" property

Pagination Response

Assertions:
  1. response.data.items is an array
  2. response.data.total is a number
  3. response.data.page equals the requested page

Error Response Handling

Condition: response.status >= 400

Assertions:
  1. response.data.error exists
  2. response.data.message exists

Viewing Results

After execution, the API Node’s details panel displays:

Statistics: Total assertions, passed count, failed count
Detailed Results Table: Each assertion’s result with actual vs. expected values
Error Messages: Specific reasons for failures