Working with JSONs in ACCELQ

Availability: Release 6.1

JSON (JavaScript Object Notation) is a widely used data format for data exchange between web applications and servers. ACCELQ provides a set of built-in, no-code commands to handle JSON data and perform various operations on it.

This article helps you understand various JSON fetch, verification, and manipulation commands available in ACCELQ along with some examples.

Listing of available commands

Under the Help Center, type JSON, and in the "Commands" tab, click the "JSON Automation" header. You will find a listing of all available commands along with detailed descriptions.

Sourcing JSON Content

While constructing your Action logic, you might need to work with JSON content from diverse sources. All JSON commands in ACCELQ consistently offer a list of data sources as an enumerator, allowing you to use any of these data sources with all the supported JSON commands.

Here are the supported sources for JSON:

1. Direct JSON text
2. JSON file path on the Agent machine where the test is executing
3. As a resource URL
4. Response of a recently executed REST API call in ACCELQ
5. Response of the most recently executed REST API call

1. Direct JSON Text

Choose this option when you need to directly input the JSON content either as text or as a parameter.

JSON Content Source Selection - Text Format

When using this JSON source, you can also invoke JSON editor to allow inputting large-size content conveniently. When typing the value for the argument, click the icon displayed in the image below.

Here is more about JSON Viewer capability.

2. File Path

Choose this option when you need a command to read the JSON content from an existing file on the local storage on the agent machine. You could provide either the absolute path or the relative path (from Agent's user_data folder) of the file.

JSON Content Source Selection - File Path

Relative paths can be specified in relation to the following folder on the Agent machine:

<Agent Folder>\user_data\

Note: Your file does not necessarily have a .json extension.

3. JSON Resource URL

With this option, you can input a URL for your JSON content. This is handy for accessing existing JSON data from web APIs accessible over your network or other online resources.

JSON Content Source Selection - JSON Resource URL

4. Response from a recently executed REST call

This option allows you to directly feed the response of a recent REST API call as a JSON source in a JSON command in Action logic. Provide the reference name of the REST API call whose response is to be used as input.

JSON Content Source Selection - Given REST Response

Example usage of REST Reference Name

5. Response from the most recent REST call

This option is very similar to the previous option except that it uses the response of the most recent REST API call directly. There is no need to supply the Reference name of the REST API call.

JSON Content Source Selection - Latest REST Response

Example usage of Latest REST Response

JSON Example and JSON Path

JSON Example

We will use the following reference content (paymentAPI.json) in the examples for various commands.

{
    "status": "success",
    "paymentId": "123456789",
    "timestamp": "2023-04-10T11:45:00Z",
    "message": "Payment successful. Transaction completed.",
    "errorCode": null,
    "user": {
        "username": "john_doe",
        "email": "john.doe@example.com",
        "age": 32,
        "address": {
            "street": "123 Main St",
            "city": "Anytown",
            "state": "CA",
            "zip": "12345"
        }
    },
    "items": [
        {
            "name": "Bottle",
            "price": 24.99,
            "quantity": 3
        },
        {
            "name": "Belt",
            "price": 9.99,
            "quantity": 1
        }
    ],
    "isRefundable": true
}

Sample - Payment API Response

Specifying JSON Path

In some JSON commands, you may need to refer to a particular node in the JSON using its JSON path. ACCELQ commands support both the Object Node Path (Dot Notation) as well as the Bracket Notation for the JSON path. For example, if you have a JSON object like this:

{
    "person": {
        "name": "John",
        "age": 30,
        "address": [
                "city": "New York",
                "country": "USA"
        ]
    }
}

Sample JSON Content to understand JSON Node Path

Then the name property can be accessed by person.name or $.person.name, “[’person’][’name’] or $[’person’][’name’]

Likewise, the property/array-element city can be accessed by person.address[0] or $.person.address[0] or [’person’][’address’][0] or $[’person’][’address’][0].

Dot Notation is relatively simple and less prone to syntactical errors; all the examples in this article use this format.

Note: You can use the native JSON Viewer in ACCELQ to find the JSON path for a particular node.

JSON Commands in ACCELQ

ACCELQ supports an extensive set of commands to retrieve and manipulate JSON data. You can broadly categorize these commands into:

1. Fetching JSON Data
2. Modifying JSON Data
3. Verifying JSON Data
4. Enquiring about JSON data
5. Other commands

Fetching JSON Data

ACCELQ provides a number of commands to read/fetch JSON data.

Get JSON Node value

Retrieves the value of a given JSON node from the content. Specify the required node using JSON path.

Example usage of Get JSON Node value command

Get JSON Array size

This command fetches the number of elements in a JSON List or Array Node.

Example usage of Get JSON Array size command

Modifying JSON Data

ACCELQ provides an extensive list of commands to modify JSON data.

Set Value for JSON node

This command sets or updates the value of a provided node.

Example usage of Set Value for JSON node command

Here is the JSON after executing the above statement:

You can also specify the Value Type for the value to be set for the node from a list of enums.

Corresponding Log JSON Value Report

Returns: The complete updated JSON Content.

Add new JSON Property

This command allows you to add a key-value pair at a given node of the JSON. The following example adds a property at the root of the given JSON.

Example usage of Add new JSON Property Command

Here is the JSON after executing this statement:

We can further specify the data type of the value for the property to be added from a list of enums.

Returns: The complete updated JSON Content.

Add Item to JSON Array

This command allows you to add an item to an existing JSON Array.

Here we are adding a JSON Object to the JSON Array

Here is the updated JSON after executing the above statement.

We can also specify the data type of the value to be added to the array node.

Returns: The complete updated JSON Content.

Verifying JSON Data

ACCELQ provides various verification & validation commands for JSON data.

Verify JSON Node exists

With this command, you can verify if a node exists in the JSON Array. Node path must be specified in the standard JSON path notation.

Verify JSON Node value matches

This command helps you verify if a JSON node value matches the expected value.

In addition to the standard string-based comparison criteria like contains, starts-with etc., one unique criterion supported here is (equals, as json), used for object comparison. As an object is an unordered collection of items, this option is preferred for such nodes.

Verify JSON Array size Is

This command is useful to verify the size of a JSON node whose value is of the type - Array or List.

Compare two JSON Contents

This command allows you to compare two given JSON contents, each of which may be sourced independently from one of the supported JSON sources. The result report displays the comparison in a nicely readable side-by-side fashion.

This command supports comprehensive controls to selectively ignore/select the nodes to be compared.

“all nodes” in comparison

Comparison is performed against all nodes in the two JSONs. This is used for exact equals verification.

Here is the sample comparison display in the test report.

JSON Diff Viewer with Rich Report showing the Expected vs. Actual JSON Content

“given nodes” in comparison

This command allows you to specify a selective list of node paths to be compared between the two JSON contents. This list must be passed as a (collections) List. Refer to this article to learn more about using Lists in ACCELQ.

“all nodes except the given” in comparison

You can specify an exception list when comparing two JSONs. This is extremely helpful in situations where there may be some dynamic data in the JSON such as a timestamp etc. that you may want to ignore while comparing two JSONs.

This list must be passed as a (collections) List. Refer to this article to learn more about using Lists in ACCELQ.

Conditionals for JSON Data

ACCELQ supports the following JSON commands to be used in conditional statements:

Is JSON Node value NULL

This command checks if a given node value is null, or not. This is a command to enquire about JSON nodes, and hence does not cause failure in report even if the node does not exist.

Example usage of Is JSON node null command used inside an if-block

Returns: A boolean value indicating if the node value is ‘null’.

Is JSON Node exists

This command checks if a given JSON node exists in the content. Specify the JSON path for the node to check.

Example usage of Is JSON node exists command used inside an if-block

Other JSON Commands

Logging JSON Content in the report

You can print JSON content in the test report by employing the "Log JSON Value" command. This command not only formats the JSON data neatly but also offers the convenience of copying JSON paths directly from the report.