How to Use Conditional Match

Overview

Using Conditional Match in ReadyAPI involves creating signatures, defining matches, and configuring requests and responses.

Comparison operators

The Conditional Match uses the following comparison operators:

Table 9. Comparison Operators

Operator	Description
Equals	Checks whether the actual node value equals the expected value.
Does not Equal	Checks whether the actual node value does not equal the expected value.
Equals (One of)	Checks whether the actual node value equals one of the expected values specified in the comma-separated format inside square brackets (for example, `[value1, value2, value3]`).
Equals (None of)	Checks whether the actual node value does not equal any of the expected values specified in the comma-separated format.
Contains	Checks whether a node contains the expected value.
>	Checks whether the actual node value is greater than the expected value. For non-numeric values it always fails.
>=	Checks whether the actual node value is not less than the expected value. For non-numeric values it always fails.
<	Checks whether the actual node value is less than the expected value. For non-numeric values it always fails.
<=	Checks whether the actual node value is not greater than the expected value. For non-numeric values it always fails.
Is Empty	Checks whether a node exists and is empty in the received message.
Is not Empty	Checks whether a node exists and is not empty in the received message.
Does not Contain	Checks whether a node does not contain the expected value.
Exists	Checks whether a node exists in the received message.
Matches (regex)	Checks whether the actual value matches the specified regular expression.
*	Accepts any value.
_	Accepts empty value.

1. Create a Signature

A signature defines the expected structure of incoming requests. To create one:

Navigate to Virtual Service Configuration:
Go to Virtual Service > Dispatch Method > Conditional Match > Configure.
Add a New Signature:
Click the icon next to Signatures.
Define Signature Details:
In the Signature Editor, add parameters to define your request structure.
To add child parameters or remove a parameter, click the icon.
Optional: Use the Signature Editor to define match conditions directly. When finished, click Save to set up the conditional match.
Configure your signatures and assign requests to signatures to enable validation and match/no-match response expectations.
Deploy and run the virtual service.

2. Create a Match

Creating a match involves defining the conditions that will link requests to responses. You have several options to create a match:

Important

Matches are automatically paired with signatures. When a matching signature is found, its name appears in the Signature field in the Conditional Match Editor. If no matching signature exists, use the Save as signature button to create a new signature based on the match.

Import Settings

Before using the Import from a File or Record from Traffic options, you can customize the import mechanism to match the signature matching settings:

Table 10. Import Settings

Setting	Description
Ignore Headers	If set to `true`, any headers present in the source request will be ignored and not included in signature created based on the request.
Ignore Null Parameters	Parameters with `null` value found in the source request will be ignored and not included in signature created based on the request.
Ignore Empty Objects	Parameters with value of empty object (`{}`) found in the source request will be ignored and not included in signature created based on the request.
Ignore Empty Arrays	Parameters with value of empty array (`[]`) found in the source request will be ignored and not included in signature created based on the request.
Ignore Empty Strings	Parameters with value of empty string (`""`) found in the source request will be ignored and not included in signature created based on the request.

Create a Match Manually (Empty Editor)

This option allows you to build requests from scratch using the Empty Request option, enabling you to add parameters individually.

Navigate to Virtual Service Configuration:
Go to Virtual Service > Dispatch Method > Conditional Match > Configure.
Add a New Request:
Click the icon next to Requests.
Select Empty Request:
Choose Empty Request.
Define Match Conditions:
Use the Conditional Match Editor to add parameters, set conditions, and valid values.
To add child parameters or remove a parameter, click the icon.

Import from an API Definition

This option allows you to import an existing API definition in ReadyAPI.

Navigate to Virtual Service Configuration:
Go to Virtual Service > Dispatch Method > Conditional Match > Configure.
Load from APIs:
Click the icon next to Requests.
Select Load from APIs to open the API explorer window.
Select an API:
Choose an API to import as a match. The new match will then appear in the list.
Important
The request body of the API must be in valid JSON format to be imported as a match.

Import from a File

This option allows you to import an API definition from a file, enabling you to select both requests and responses for conditional matching.

Import and Pair

To import multiple files, click the Load from files button. Request and response files will be automatically paired based on their respective file names.

Confirmation Popup for Successful Import

When request/response pairs are imported from files, a confirmation message is displayed to indicate success.

Examples

Explore examples of request and response file configurations, including complex scenarios, to understand their implementation in different contexts:

Example 1. Basic Example of Request File

POST /myAPI/v2/endpoint HTTP/1.1
{   
    "parameter1": {
        "child_parameter": "value"   
    },
    "parameter2": "value"
}

Basic Example of Response File

{   
"status": 200,   
"message": "Ok"
}

Example 2. Advanced Scenario of Request File

POST /myAPI/v2/endpoint HTTP/1.1
{   
    "info": {     
        "_postman_id": "12345678-abcd-efgh-ijkl-0123456789ab",     
        "name": "ReadyApi",     
        "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",     
        "_exporter_id": "9876543"   
    },   
    "item": [     
        {       
            "name": "http://localhost:8084/test",       
            "protocolProfileBehavior": {         
                "disabledSystemHeaders": {           
                    "user-agent": true,           
                    "accept-encoding": true,           
                    "connection": true         
            }       
        },
        "request": {         
            "method": "POST",         
            "header": [],         
            "body": {           
                "mode": "raw",           
                "raw": "{\n\t\"field\": \"1\",\n \"array\": [1,2,3],\n \"obj\": {\n \"foo\": \"bar\"\n },\n \"objArr\": [\n {\n \"a\": \"a\"\n },\n {\n \"a\": \"b\"\n }\n ]\n}",           
                "options": {             
                    "raw": {               
                        "language": "json"             
                    }           
                }         
            },         
            "url": {           
                "raw": "http://localhost:8084/test",           
                "protocol": "http",           
                "host": [             
                    "localhost"           
                ],           
                "port": "8084",           
                "path": [             
                    "test"           
                ]         
            }       
        },       
        "response": []     
    }   
  ]
}

Advanced Scenario of Response File

{   
    "status": 200,   
    "message": "Ok"
}

File Naming Convention

The file names in a request/response pair consist of a prefix, a suffix, and a file extension.

<prefix><suffix>.<extension>

Example 3. Single Request, Single Response

The following example has one request and one response:

depositMoney-req.txt
depositMoney-req.txt

Example 4. Single Request, Multiple Responses

The following example has one request and three responses:

depositMoney-req.txt
depositMoney-rsp1.txt
depositMoney-rsp2.txt
depositMoney-rsp3.txt

Note

Request files must begin with the method and path on the first line, formatted as follows: POST/rateCal/v4/rates/quotes HTTP/1.1

Note

The request body must be in JSON format.

Table 11. File Naming Convention

Name	Description
Prefix	A unique identifier prepended to a file name to denote its association with a specific context or category. Note Maintain consistency by using this prefix across all files associated with a transaction. Example: `depositMoney`
Suffix	A distinctive identifier appended to file names to denote specific purposes or contexts within a transaction. Example: Request file suffix: `-req` Example: Response file suffix: `-rsp` (with an optional numerical suffix to distinguish multiple responses).
Extension	A file type identifier appended to the end of a file name, always preceded by a dot. It defines the format or type of data contained within the file. Example: `.txt`

Name

Description

Prefix

A unique identifier prepended to a file name to denote its association with a specific context or category.

Note

Maintain consistency by using this prefix across all files associated with a transaction.

Example: depositMoney

Suffix

A distinctive identifier appended to file names to denote specific purposes or contexts within a transaction.

Example: Request file suffix: -req

Example: Response file suffix: -rsp (with an optional numerical suffix to distinguish multiple responses).

Extension

A file type identifier appended to the end of a file name, always preceded by a dot. It defines the format or type of data contained within the file.

Example: .txt

Import from a Signature

This option allows you to import an API signature to select and load requests for conditional matching.

Navigate to Virtual Service Configuration:
Go to Virtual Service > Dispatch Method > Conditional Match > Configure.
Load from Signature:
Click the icon next to Requests.
Select Load from signature to open the signature selector dialog.
Select a Signature:
Choose a signature as the basis for your match. A new match will display with all fields from the selected signature. Define your match conditions by selecting the match and clicking the icon.

Record from Traffic

This option enables loading the request from traffic data.

Navigate to Virtual Service Configuration:
Go to Virtual Service > Dispatch Method > Conditional Match > Configure.
Record Traffic:
Click the icon next to Requests.
Select a Proxy as the recording method.
Set up the proxy in your client as per the on-screen instructions.
Begin sending requests. View requests and responses in the Transactions tab. Select those you wish to import and click Generate matches.
The imported request/response pairs will be visible in the Conditional Match configuration dialog.
Note
ReadyAPI will consolidate identical responses, creating only one instance.

3. Create a Response

Important

Access and manage all responses by clicking the button.

You can create a new response manually by clicking the icon next to Responses section in Conditional Match configuration view.

Property Expansion

To include request values in a response, utilize property expansion within the response body using the following syntax:

${#MockRequest#$['requestParameterPath'];?:['defaultValue']}

defaultValue: Serves as a fallback value for property expansion when it cannot access the specified request parameter (for example, if the parameter is missing from the incoming request).

requestParameterPath: To access the value of a specific parameter, construct a path that includes each JSON parameter level within separate square brackets. For example:

{

  "parameter1":

      "child1": "value1",

      "child2": "value2",

  "parameter2": "value3"

}

To retrieve the value of child2, utilize ${#MockRequest#$['parameter1']['child2'];?:['defaultValue']}.

Example 5. Response Example

{
  "id" : ${#MockRequest#$['id'];?:9841}, //this will populate the 'id' fields value from received request. If request does not have id field, default value of 9841 will be used instead
  "petId" : 0,
  "quantity" : 0,
  "shipDate" : "MASKED",
  "status" : "placed",
  "complete" : false
}

How to Use Conditional Match

Overview

Comparison operators

1. Create a Signature

2. Create a Match

Important

Import Settings

Create a Match Manually (Empty Editor)

Import from an API Definition

Important

Import from a File

File Naming Convention

Note

Note

Note

Import from a Signature

Record from Traffic

Note

3. Create a Response

Important

Property Expansion

See Also

Search results