API Assertions

Assertions are crucial for validating that your API responses match expected outcomes. They help ensure your API behaves correctly under various conditions by checking specific parts of the response data, status codes, headers, and more.

How Assertions Work

Defining an assertion involves specifying four key components:

1. Assert Type: The part of the API response you want to validate (e.g., response body, status code, header).
2. Property Path: The specific location within the selected Assert Type to target (e.g., body.user.id, statusCode, headers['Content-Type']). This identifies the actual value.
3. Operator: The comparison logic to apply between the actual value and the expected value (e.g., equals, contains, greaterThan).
4. Expected Value: The value you anticipate the API response should contain at the specified property path.

Supported Assert Types

Robonito currently supports assertions on the following parts of an API response:

• Response Body: Validate data within the JSON or text body returned by the API.
• Status Code: Validate the HTTP status code (e.g., 200, 404, 500).
• Headers: Validate specific response headers and their values. (Self-correction: Added Headers as a likely common assert type)

Property Path

The property path precisely identifies the data point within the Assert Type you wish to validate.

• For Response Body (JSON): Use dot notation (.) to navigate nested objects and bracket notation ([index]) for array elements.
  // Example JSON Body:
  {
    "user": { "id": 123, "name": "Alice" },
    "orders": [ { "orderId": "A1", "total": 50 }, { "orderId": "B2", "total": 75 } ],
    "status": "active"
  }
  

  • body.status -> accesses "active"
  • body.user.id -> accesses 123
  • body.orders[0].orderId -> accesses "A1"
  • body -> accesses the entire response body object
• For Status Code: Use statusCode.
• For Headers: Use headers['Header-Name'] (e.g., headers['Content-Type']).

Example Assertions

Let's use the following example API response:

Status Code: 200

Headers:

Content-Type: application/json
X-Request-ID: abc-123

Response Body:

{
  "user": {
    "id": 101,
    "username": "jdoe",
    "roles": ["editor", "viewer"]
  },
  "data": {
    "items": [
      { "itemId": "X1", "price": 25.50 },
      { "itemId": "Y2", "price": 10.00 }
    ],
    "count": 2
  },
  "timestamp": "2025-04-16T10:00:00Z"
}

Here are some example assertions you could define:

1. Check Status Code:

   {
     "assertType": "StatusCode",
     "propertyPath": "statusCode",
     "operator": "equals",
     "expectedValue": 200
   }
   

2. Check Content-Type Header:

   {
     "assertType": "Headers",
     "propertyPath": "headers['Content-Type']",
     "operator": "contains",
     "expectedValue": "application/json"
   }
   

3. Check Username in Body:

   {
     "assertType": "ResponseBody",
     "propertyPath": "body.user.username",
     "operator": "equals",
     "expectedValue": "jdoe"
   }
   

4. Check Number of Items:

   {
     "assertType": "ResponseBody",
     "propertyPath": "body.data.count",
     "operator": "greaterThanOrEqual",
     "expectedValue": 1
   }
   

5. Check if User has 'editor' Role:

   {
     "assertType": "ResponseBody",
     "propertyPath": "body.user.roles",
     "operator": "contains",
     "expectedValue": "editor"
   }
   

6. Check Price of the First Item:

   {
     "assertType": "ResponseBody",
     "propertyPath": "body.data.items[0].price",
     "operator": "equals",
     "expectedValue": 25.50
   }
   

7. Check Type of count field:

   {
     "assertType": "ResponseBody",
     "propertyPath": "body.data.count",
     "operator": "typeOf",
     "expectedValue": "number" // Expected type as a string
   }
   

Assertion Result Format

Each assertion execution returns a result object indicating success or failure, along with details:

Best Practices

1. Be Specific: Target specific fields rather than asserting against large, complex objects when possible. This makes failures easier to diagnose.
2. Use Appropriate Operators: Choose operators that match the data type and the logic you need (e.g., use numeric operators for numbers, contains for arrays/strings, typeOf for type checking).
3. Validate Status Codes: Always include an assertion for the expected HTTP status code.
4. Check Critical Data: Focus assertions on the most important parts of the response that indicate success or failure of the API call's purpose.
5. Consider Edge Cases: Add assertions to check how the API handles errors, empty responses, or unexpected data formats.
6. Use typeOf: Validate the data type of key fields, especially in dynamically typed responses, to prevent errors in subsequent processing.