How to Use Conditional Match

Applies to ReadyAPI 3.56, last modified on November 21, 2024

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:

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:

  1. Navigate to Virtual Service Configuration:

    Go to Virtual Service > Dispatch Method > Conditional Match > Configure.

    Configuring Conditional Match

    Click the image to enlarge it.

  2. Add a New Signature:

    Click the icon next to Signatures.

    Adding Signature in Conditional Match

    Click the image to enlarge it.

  3. Define Signature Details:

    In the Signature Editor, add parameters to define your request structure.

    Adding Signature Parameters in Conditional Match

    Click the image to enlarge it.

    To add child parameters or remove a parameter, click the icon.

    Adding Child Signature Parameters in Conditional Match

    Click the image to enlarge it.

    Optional: Use the Signature Editor to define match conditions directly. When finished, click Save to set up the conditional match.

  4. Configure your signatures and assign requests to signatures to enable validation and match/no-match response espectations.

  5. 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:

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:

Import Settings Configuration

Click the image to enlarge it.

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.

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

  1. Navigate to Virtual Service Configuration:

    Go to Virtual Service > Dispatch Method > Conditional Match > Configure.

    Configuring Conditional Match

    Click the image to enlarge it.

  2. Add a New Request:

    Click the icon next to Requests.

    Adding Request in Conditional Match

    Click the image to enlarge it.

  3. Select Empty Request:

    Choose Empty Request.

    Selecting Empty Request in Conditional Match

    Click the image to enlarge it.

  4. Define Match Conditions:

    Use the Conditional Match Editor to add parameters, set conditions, and valid values.

    Adding Parameters in Conditional Match

    Click the image to enlarge it.

    To add child parameters or remove a parameter, click the icon.

    Adding Child Parameters in Conditional Match

    Click the image to enlarge it.

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

  1. Navigate to Virtual Service Configuration:

    Go to Virtual Service > Dispatch Method > Conditional Match > Configure.

    Configuring Conditional Match

    Click the image to enlarge it.

  2. Load from APIs:

    Click the icon next to Requests.

    Adding Request in Conditional Match

    Click the image to enlarge it.

    Select Load from APIs to open the API explorer window.

    Load from APIs in Conditional Match

    Click the image to enlarge it.

  3. Select an API:

    Choose an API to import as a match. The new match will then appear in the list.

    The request body of the API must be in valid JSON format to be imported as a match.

    Selecting an API in Conditional Match

    Click the image to enlarge it.

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

Importing from a file in Conditional Match

Click the image to enlarge it.

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.

Importing multiple files in Conditional Match

Click the image to enlarge it.

Confirmation Popup for Successful Import

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

Successful Import Confirmation

Click the image to enlarge it.

Examples

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

Example

Example

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

<prefix><suffix>.<extension>

Example

Example

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.
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: Request file suffix: -req (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

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

  1. Navigate to Virtual Service Configuration:

    Go to Virtual Service > Dispatch Method > Conditional Match > Configure.

    Configuring Conditional Match

    Click the image to enlarge it.

  2. Load from Signature:

    Click the icon next to Requests.

    Adding Request in Conditional Match

    Click the image to enlarge it.

    Select Load from signature to open the signature selector dialog.

    Importing from Signature in Conditional Match

    Click the image to enlarge it.

  3. 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.

    Selecting Signature in Conditional Match

    Click the image to enlarge it.

This option enables loading the request from traffic data.

  1. Navigate to Virtual Service Configuration:

    Go to Virtual Service > Dispatch Method > Conditional Match > Configure.

    Configuring Conditional Match

    Click the image to enlarge it.

  2. Record Traffic:

    Click the icon next to Requests.

    Clicking Record in Conditional Match

    Click the image to enlarge it.

  3. Select a Proxy as the recording method.

    Selecting Recording Method in Conditional Match

    Click the image to enlarge it.

  4. Set up the proxy in your client as per the on-screen instructions.

    Setting Up Proxy in Conditional Match

    Click the image to enlarge it.

  5. Begin sending requests. View requests and responses in the Transactions tab. Select those you wish to import and click Generate matches.

    Managing Transactions in Conditional Match

    Click the image to enlarge it.

  6. The imported request/response pairs will be visible in the Conditional Match configuration dialog.

    Note: ReadyAPI will consolidate identical responses, creating only one instance.
    Imported Response-Request Pairs in Conditional Match

    Click the image to enlarge it.

3. Create a Response

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.

Creating a response in Conditional Match

Click the image to enlarge it.

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']}

    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

    }

See Also

Conditional Match (Dispatch Strategy)
Conditional Match Overview

Highlight search results