Node ReferenceAssertions Reference

Assertions Reference

Assertions validate API responses and ensure your tests catch regressions. ReAPI provides built-in operators, Chai integration, and support for custom assertion functions.

Built-in Operators

Type Validation

  • isString: Validates string type
  • isNumber: Validates numeric type
  • isBoolean: Validates boolean type
  • isArray: Validates array type
  • isObject: Validates object type
  • isNull: Validates null value
  • isUndefined: Validates undefined value

Format Validation

  • isEmail: Validates email format
  • isUrl: Validates URL format
  • isUuid: Validates UUID format
  • isIso8601: Validates ISO 8601 date format
  • isJson: Validates JSON string format

Value Comparison

  • equals: Exact equality comparison
  • contains: String/array contains check
  • startsWith: String starts with check
  • endsWith: String ends with check
  • matches: Regular expression matching

Chai Integration

ReAPI supports most Chai assertions with 1-2 parameters:

Equality

// response.data.id equals 123
response.data.id.equals(123)
 
// response.data.name equals "John"
response.data.name.equals("John")

Comparison

// response.data.count is above 10
response.data.count.above(10)
 
// response.data.score is below 100
response.data.score.below(100)
 
// response.data.items has length 5
response.data.items.length(5)

Inclusion

// response.data.tags includes "important"
response.data.tags.include("important")
 
// response.data has property "user"
response.data.property("user")

JSONata Targeting

Use JSONata to target specific parts of the response:

Simple Paths

// Target: response.data.user.email
data.user.email
 
// Target: response.data.items[0].id  
data.items[0].id

Array Operations

// All user emails
data.users.email
 
// Active users only
data.users[status="active"]
 
// Count of items
$count(data.items)

Complex Queries

// Average of all prices
$average(data.products.price)
 
// Users with specific role
data.users[role="admin"].name
 
// Conditional selection
data.orders[amount > 100].id

Custom Assertions

Developers can register custom assertion functions that appear in the UI:

Registration Example

// Developer registers this function
function isValidUser(user) {
  $addAssertionResult(
    user.id && user.email && user.status,
    `Expected valid user object`,
    `Got: ${JSON.stringify(user)}`
  );
}

Usage in Tests

Once registered, isValidUser appears as a first-class assertion option in the visual interface for QA teams to use.

Assertion Context

Assertions have access to:

  • response: Full API response (status, headers, body)
  • request: Original request data
  • context: All context variables
  • environment: Environment configuration

Best Practices

Specific Targeting

// Good: Specific path
response.data.user.id.equals(123)
 
// Avoid: Too broad
response.contains("123")

Meaningful Messages

// Custom assertions should provide clear error messages
function isValidOrder(order) {
  const isValid = order.id && order.amount && order.status;
  $addAssertionResult(
    isValid,
    "Order should have id, amount, and status",
    `Missing fields in: ${JSON.stringify(order)}`
  );
}

Multiple Assertions

Use multiple targeted assertions rather than one complex assertion:

// Good: Separate concerns
response.data.user.id.isNumber()
response.data.user.email.isEmail()
response.data.user.status.equals("active")
 
// Avoid: Complex single assertion

More assertion patterns and advanced examples coming soon…

Context & VariablesOverview