JSONata Expression Language

For a complete guide to all functions and features, please refer to the Official JSONata Documentation.

JSONata is the foundational expression language for extracting and transforming data in ReAPI. While the Template Engine generates values for API requests, JSONata processes data from API responses and context variables.

Why Learn JSONata?

JSONata is essential for ReAPI testing because it enables:

• Response Data Extraction: Pull specific values from API responses.
• Smart Assertions: Validate complex API responses with simple expressions.
• Dynamic Test Logic: Create conditional flows based on extracted data.
• Data Transformation: Reshape API response data for use in other test steps.

A Note on String Literals

A common point of confusion is the difference between a string value (a literal) and a JSONata expression that references a variable.

• Unquoted text is a JSONata expression. It’s treated as a path to a variable. For example, if you type active into a value field, ReAPI will look for a variable named active in the context. If it doesn’t exist, the expression will return undefined.
• Quoted text is a string literal. To use the actual string value “active”, you must enclose it in quotes: "active".

Example of a common mistake in an assertion:

• Incorrect: response.data.status equal active
  • ReAPI interprets active as a variable, which is likely undefined, causing the assertion to fail unexpectedly.
• Correct: response.data.status equal "active"
  • This correctly compares the status field with the literal string “active”.

Always use quotes for static string values.

Where You’ll Use JSONata in ReAPI

As a QA engineer, you’ll encounter JSONata in these key areas:

🎯 Assertions

In assertions, JSONata expressions are used to target and extract the data you want to validate. This extracted value is then compared against an expected value using a mandatory assertion operator.

Example 1: Checking a Status Code

• Target (JSONata): response.status
• Operator: equal
• Value: 200

Example 2: Checking for Existence

• Target (JSONata): $exists(response.data.user)
• Operator: isTrue

Here are a few more examples of JSONata expressions used as assertion targets:

// Get the number of users in the response array (e.g., to use with the 'greaterThan' operator)
response.data.users.$count()

// Get a specific user's email (e.g., to use with the 'equal' operator)
response.data.users[0].email

⚖️ Conditional Logic (IF Nodes)

Create dynamic test flows based on data from previous steps:

user.role = "admin" and user.permissions.write = true
$count(response.data.errors) = 0

📝 Context Operations

Set and manipulate test variables by transforming API responses:

{
  "userId": response.data.user.id,
  "userEmail": response.data.user.email,
  "isActive": response.data.user.status = "active"
}

Basic Usage and Common Patterns

Here are a few examples of the most common JSONata operations you’ll use in ReAPI.

Accessing Data

Use dot notation to access object properties and square brackets for array elements.

// Access an object property
response.data.user.id

// Access an array element by its index
response.data.users[0].name

// Get an array of all user names
response.data.users.name

Filtering Arrays

Use square brackets with a conditional expression to filter arrays.

// Find all users who are older than 18
users[age > 18]

// Find all products that are available and cost more than 100
products[available = true and price > 100]

Common Built-in Functions

JSONata has a rich library of functions. Here are a few essentials:

// Check if a property exists
$exists(user.email)

// Count the number of items in an array
$count(users)

// Sum the 'total' property of all objects in an 'orders' array
$sum(orders.total)

// Check if a string contains a substring
$contains(user.email, "@company.com")

When to Use JSONata vs Template Engine

💡 Complementary Tools: JSONata and Template Engine work together. Use the Template Engine for dynamic API configurations and JSONata for data logic.

Mastering a few basic JSONata patterns will allow you to create sophisticated, maintainable test automation that adapts to your data and business requirements. For more advanced use cases, remember to consult the official documentation.