Skip to main content

Assertions

Assertions are how you validate that API responses meet your expectations. They're essential for automated testing and ensuring API reliability.

What is an Assertion?​

An assertion is a validation rule that checks if a condition is true. In Nidra, assertions let you verify:

  • Status codes are correct
  • Response contains expected data
  • Response fields have correct values
  • Performance meets requirements
  • Headers are present and correct

Adding Assertions​

In Requests​

  1. Send a request to see the response
  2. Click the "Assertions" tab
  3. Click "Add Assertion"
  4. Configure your assertion
  5. Save

In Conduits​

  1. Add or edit a request step
  2. Click "Add Assertion"
  3. Configure the assertion
  4. Save the step

When the conduit runs, assertions are checked automatically.

Status Code Assertions​

The most common assertion type.

Equals​

Status Code equals 200

Use when you expect an exact status code.

In Range​

Status Code between 200 and 299

Use for any successful response.

Not Equals​

Status Code not equals 500

Use to ensure no server errors.

Common Patterns​

  • GET success: equals 200
  • POST created: equals 201
  • PUT success: equals 200 or 204
  • DELETE success: equals 204 or 200
  • Not found: equals 404
  • Any success: between 200 and 299

Response Field Assertions​

Validate specific fields in the response body.

Equals​

Response:
{
  "status": "success",
  "id": 12345
}

Assertions:

Field "status" equals "success"
Field "id" equals 12345

Contains​

Field "email" contains "@example.com"

Use for partial string matching.

Exists​

Field "userId" exists

Verifies the field is present (any value).

Does Not Exist​

Field "error" does not exist

Ensures field is absent.

Type Checking​

Field "id" is type "number"
Field "email" is type "string"
Field "active" is type "boolean"
Field "tags" is type "array"

Comparison Operators​

Equality​

  • equals: Exact match
  • not equals: Must be different

Comparison​

  • greater than: value > expected
  • greater than or equal: value >= expected
  • less than: value < expected
  • less than or equal: value <= expected

Example:

{
  "price": 99.99,
  "quantity": 5
}
Field "price" less than 100
Field "quantity" greater than 0

String Operators​

  • contains: Substring match
  • does not contain: Substring not present
  • starts with: Prefix match
  • ends with: Suffix match
  • matches regex: Regular expression

Examples:

Field "email" contains "@"
Field "url" starts with "https://"
Field "filename" ends with ".pdf"
Field "phone" matches regex "^\d{3}-\d{3}-\d{4}$"

Collection Operators​

  • is empty: Array/object has no elements
  • is not empty: Has at least one element
  • length equals: Exact number of elements
  • length greater than: More than N elements

Examples:

{
  "items": [1, 2, 3],
  "tags": []
}
Field "items" length equals 3
Field "items" is not empty
Field "tags" is empty

Nested Field Assertions​

Access nested fields using dot notation.

{
  "user": {
    "profile": {
      "email": "user@example.com",
      "verified": true
    },
    "settings": {
      "notifications": true
    }
  }
}

Assertions:

Field "user.profile.email" contains "@example.com"
Field "user.profile.verified" equals true
Field "user.settings.notifications" equals true

Array Assertions​

Validate array contents and structure.

Array Length​

{
  "results": [1, 2, 3, 4, 5]
}
Field "results" length equals 5
Field "results" length greater than 0

Array Element​

{
  "users": [
    {"id": 1, "name": "Alice"},
    {"id": 2, "name": "Bob"}
  ]
}
Field "users[0].name" equals "Alice"
Field "users[1].id" equals 2

Array Contains​

Field "users[*].name" contains "Alice"

Checks if any element matches.

Header Assertions​

Validate response headers.

Header "Content-Type" equals "application/json"
Header "X-Rate-Limit-Remaining" greater than 0
Header "Cache-Control" contains "no-cache"
Header "Set-Cookie" exists

Performance Assertions​

Validate response times and performance.

Response time less than 500
Response time less than 1000

Values in milliseconds.

Use for:

  • SLA compliance
  • Performance regression detection
  • Load testing validation

Response Body Assertions​

Validate entire response body.

Body Contains​

Response body contains "success"
Response body contains "error" (should fail for success)

Body Matches Schema​

Response body matches schema {
  "type": "object",
  "required": ["id", "name"]
}

JSON Schema validation.

Body Equals​

Response body equals {"status": "ok"}

Exact match (use carefully).

Combining Assertions​

Use multiple assertions for comprehensive validation.

Complete Validation Example​

Status Code equals 200
Response time less than 500
Header "Content-Type" contains "application/json"
Field "status" equals "success"
Field "data" exists
Field "data.id" is type "number"
Field "data.email" contains "@"
Field "data.createdAt" exists

All assertions must pass for the test to succeed.

Assertion Logic​

AND Logic (Default)​

All assertions must pass:

Field "status" equals "success" AND
Field "code" equals 200 AND
Field "data" exists

OR Logic (Advanced)​

At least one assertion must pass:

Status Code equals 200 OR
Status Code equals 201

(If supported - check Nidra documentation)

Variable-Based Assertions​

Use variables in assertions for dynamic validation.

Compare with Variables​

Field "userId" equals {{expectedUserId}}
Field "total" greater than {{minimumTotal}}
Field "email" equals {{userEmail}}

Extract and Assert​

  1. Extract value: data.id → {{createdId}}
  2. In next step: 
    Field "id" equals {{createdId}}

Validates consistency across requests.

Common Assertion Patterns​

CRUD Operations​

Create (POST):

Status Code equals 201
Field "id" exists
Field "id" is type "number"
Field "createdAt" exists

Read (GET):

Status Code equals 200
Response time less than 500
Field "id" equals {{resourceId}}

Update (PUT):

Status Code equals 200
Field "updatedAt" exists
Field "name" equals {{newName}}

Delete:

Status Code equals 204
Response body is empty

Error Validation​

Status Code equals 400
Field "error" exists
Field "error.message" contains "required"
Field "error.code" equals "VALIDATION_ERROR"

Pagination​

Status Code equals 200
Field "results" is type "array"
Field "pagination.page" equals 1
Field "pagination.totalPages" greater than 0
Field "pagination.hasNext" is type "boolean"

Authentication​

Status Code equals 200
Field "token" exists
Field "token" is type "string"
Field "expiresIn" greater than 0
Field "tokenType" equals "Bearer"

Best Practices​

What to Assert​

  • Always: Status code
  • Usually: Key response fields
  • Performance-critical APIs: Response time
  • Contracts: Required fields exist
  • Data validation: Types and formats

Granularity​

  • Too few assertions: Tests may miss issues
  • Too many assertions: Tests become brittle
  • Sweet spot: Assert critical properties and contracts

Meaningful Failures​

Structure assertions so failures are informative:

Bad:

Response body contains "success"

Good:

Field "status" equals "success"
Field "code" equals 200
Field "errors" does not exist

When it fails, you know exactly what's wrong.

Troubleshooting​

Assertion Fails Unexpectedly​

  1. Review the actual response
  2. Check the field path (typos?)
  3. Verify data type (string vs number)
  4. Check variable resolution
  5. Review API changes

Flaky Assertions​

If assertions sometimes pass, sometimes fail:

  • Response time: Use higher threshold or percentiles
  • Timestamps: Use relative checks, not exact values
  • Generated data: Use patterns (contains) not exact matches
  • Ordering: Don't rely on array order unless guaranteed

False Positives​

Assertion passes but shouldn't:

  • Check assertion logic
  • Verify field path is correct
  • Ensure you're testing the right thing
  • Add more specific assertions

Advanced Techniques​

Custom Assertions​

If standard assertions aren't enough:

  • Use script steps for complex logic
  • Chain multiple simple assertions
  • Use JSONPath for complex queries

Conditional Assertions​

Assert based on conditions:

If Field "type" equals "premium":
  Then Field "features" length greater than 10

(If supported by Nidra)

Assertion Templates​

Create reusable assertion sets:

Standard Success Response:

- Status Code equals 200
- Response time less than 500
- Header "Content-Type" contains "application/json"
- Field "status" equals "success"

Apply this template to multiple requests.

Real-World Example​

E-Commerce Order Validation​

# Order creation request
POST {{baseUrl}}/orders

# Assertions:
Status Code equals 201
Response time less than 1000
Header "Content-Type" equals "application/json"

# Order structure
Field "orderId" exists
Field "orderId" is type "string"
Field "orderId" starts with "ORD-"

# Monetary values
Field "total" is type "number"
Field "total" greater than 0
Field "currency" equals "USD"

# Items
Field "items" is type "array"
Field "items" is not empty
Field "items" length equals {{expectedItemCount}}
Field "items[0].productId" exists
Field "items[0].quantity" greater than 0

# Status
Field "status" equals "pending"
Field "paymentStatus" equals "unpaid"

# Timestamps
Field "createdAt" exists
Field "estimatedDelivery" exists

# Customer
Field "customer.id" equals {{customerId}}
Field "customer.email" contains "@"

Next Steps​