About

The Conditional Match dispatch strategy of a virtual service provides greater control over the configuration of how virtual services respond to various requests, enabling more realistic and dynamic testing scenarios.

This feature allows you to pair specific requests with corresponding responses, configure multiple request/response pairs, and set a default response for unmatched requests.

Additionally, requests can be grouped and matched by signature, validating and matching requests based on data structure, with default responses provided for failed validations. You can configure requests with specific data configurations or arguments using operators like =, +, -, *, <, >, and regex.

This advanced functionality enables intricate request/response configurations, ensuring precise and accurate virtual service behavior.

The Conditional Match dispatch type is available for REST virtual services only.

Conditional Match is currently designed to work with body parameters only. It does not support matching based on query parameters.

Key Components

This section explains two essential components of Conditional Match:

Match: A set of conditions that must be satisfied for the chosen response to be sent to an incoming request.
Signature: A template that defines the body structure an incoming request needs to match to be paired with a specified response.

Getting Started

Start using Conditional Match by exploring its versatile applications to control how your system handles request-response interactions. This section guides you through scenarios and settings, demonstrating how to simulate user interactions, manage complex logic, and effectively test API behaviors. To get started, complete the following steps:

Configure your virtual service.
Set up your requests and responses by importing or recording.
Configure the request - response pairing logic.
Configure your signatures and assign requests to signatures to enable validation and match/no-match response expectations.
Deploy and run the virtual service.

Set a Default Dispatch Style for Virtual Services

You can now set a default dispatch style for Virtual Services in the Preferences window. Navigate to the Virtual Service Preference tab to configure this setting, which defaults to Sequence. The available dispatch styles in the dropdown are:

Sequence
Random
Query Match
XPath
Script
Parameter
Conditional Match

Matching Algorithm

This process outlines how the Matching Algorithm handles incoming requests by directing them to the appropriate Virtual Action, verifying signatures when required, and providing responses based on predefined matches or defaults.

Receive the incoming request.
Identify the endpoint and route it to the corresponding Virtual Action.
Find a matching signature if signature verification is enabled.
If a matching signature is found, proceed to find a corresponding match.
Send the appropriate response based on the match.
If no matching signature or match is found, send the Default response configured for the Virtual Action.

Reordering Signatures

You can now reorder signatures in the Conditional Match configuration window. This feature may be necessary in certain scenarios, such as when a user specifies a Size of value for a field in a signature. For more details, please refer to the Matching Algorithm section.

Note:

Signatures have been updated to support arrays, meaning a request with arrays can now match more than one signature.
If a request matches two signatures, it will match the first signature found in the list. Changing the order of signatures allows you to control the matching outcome.

Click the image to enlarge it.

Settings for Conditional Match

Access additional configuration settings for Conditional Match by selecting the Conditional Match Configuration button. The following options can be adjusted via dropdowns:

Verify Signature
Verify Signature Headers
Ignore Null Values
Ignore Empty Arrays
Ignore Empty Objects
Ignore Empty Strings

Signature Validation Options

The following settings allow you to configure how signatures are validated in Conditional Match, ensuring the appropriate handling of requests.

Validate Signatures: Validating signatures ensures that the requests and responses adhere to a predefined structure, enhancing reliability and consistency.
Don’t Validate Signatures: In some cases, it might be necessary to disable signature validation, allowing more flexibility in handling requests. In this case, the matching algorithm will use the first match from the top of the match list that works for the incoming request.
Validate Signature Headers: Validating headers ensures that the requests include the necessary metadata before they are processed.
Validate Signature Values: Validating the values of request parameters ensures that the data conforms to expected formats and ranges.

You can choose to enable or disable the signature validation options using checkboxes:

Checkbox	Checked	Unchecked
Verify Signature	The system verifies if the incoming request’s parameter structure matches the parameter structure defined by the assigned signature (all parameters specified in the signature must be present in the incoming request and the incoming request must not contain any parameters that are not present in the signature).	Matching occurs without validating parameter structure from the assigned signature.
Verify Signature Headers	The system checks if the incoming request includes all headers specified in the assigned signature.	Headers specified in the signature are not considered during the matching process.
Verify Header Values	All conditions defined in the headers tab in the conditional match are evaluated during the matching process.	Conditions defined in the headers tab in the conditional match are disregarded.

JVM Settings

Configure signature validation and header validation behaviors in Conditional Match with the JVM settings.

Signature Validation: Controls whether signature validation is enabled (true) or disabled (false).

Note: Enabling this setting hides the UI option to toggle this functionality.

readyapi.verify.signatures=true
Signature Header Validation: Controls whether signature header validation is enabled (true) or disabled (false).
readyapi.verify.signatures.headers=true

Enabling Conditional Match Property Expansion

This feature lets you dynamically insert request values into responses, enhancing testing flexibility and accuracy.

Enabling Property Expansion in Conditional Match

Click the image to enlarge it.

When enabled, during the import of request/response pairs using Import from a file or Record from traffic the following behavior applies:

If both the request and response share a parameter with the same value, the response's value will be replaced with the Property Expansion syntax, using the default value recorded at the time. For further information on Property Expansion in Conditional Match, refer to the Property Expansion section.

Setting Dates Delta Using Property Expansion

The Dates Delta feature allows you to use property expansion for date values in Conditional Match. You can specify the date format as dd-MM-yyyy in Preferences → Virtual Service. This ensures that responses can have date values relative to request dates.

When Enable conditional match dates property expansion is set to true, the new syntax is automatically applied during record from traffic and record from traffic:

If a date exists in both the request and the response, the response date will be replaced with dates delta property expansion.

You can utilize two options for parsing dates in the response body:

Current Date Delta: Returns a date based on the current date, provided delta, and specified format.

{

"currentDate": #MockRequest#currentDateDelta("date-format", "date-delta"),

}
Request Date Delta: Returns a date based on the first date found in the request, along with the delta and format.

{

"requestDate": #MockRequest#requestDateDelta("date-format", "date-delta"),

}

This functionality enhances your ability to manage date values dynamically in API responses, ensuring more accurate and context-aware interactions.

Set a Default Response per Signature

You can set a default response for each signature. This response is sent when an incoming request matches the signature but lacks a corresponding specific response. If the request doesn’t match any signature, the global default response is used.

To enable this feature, go to Preferences → Virtual Service and select the Enable default response per signature option. Once enabled, you can choose a default response for each signature, which will be used if the request matches the signature but doesn’t have an associated response.

Setting a default response for signatures in Conditional Match

Click the image to enlarge it.

Verify Array Size in Signatures

You can now verify the array size within signatures.

Open the Signature Editor.
For the parameter you expect to be an array, select Size of from the available options.
Enter the desired array size.

Note:

By default, all parameters are set to Exists. If a parameter is configured as Exists and is identified as an array, the size of that array will not be verified during signature matching.

Verifying Array Size in Signatures in Conditional Match

Click the image to enlarge it.

Ignore Null/Empty Parameters

The Ignore Null/Empty Parameters feature allows you to disregard parameters with null or empty values during signature matching.

When this feature is enabled, any parameters in an incoming request with null or empty values will be ignored.

Example

Signature

{

"login": "myLogin",

"password": "myPassword"

}
Incoming request

{

"login": "myLogin",

"password": "myPassword",

"additionalParam": null

}

In this case, the request will be matched to the signature from the example.

You can enable ignoring null/empty values separately for the following cases:

Ignore Null Values: If enabled, an incoming request will be treated as if the parameter with a value of null doesn't exist.
{ "foo": null }
Ignore Empty Arrays: If enabled, an incoming request will be treated as if the parameter with a value of empty array doesn’t exist.
{ "foo": [] }
Ignore Empty Objects: If enabled, an incoming request will be treated as if the parameter with a value of empty object doesn’t exist.
{ "foo": {} }
Ignore Empty Strings: If enabled, an incoming request will be treated as if the parameter with a value of empty string doesn’t exist.
{ "foo": "" }

By enabling any of these options, you can fine-tune how the system handles incoming requests, making your signature matching more flexible.

Checkbox to ignore null or empty parameters in signature matching in Conditional Match

Click the image to enlarge it.

Selected Items Previewer

A Selected Items Previewer is available in the Configure dialog for Conditional Match. This tool helps you visualize the relationships between signatures, requests, and responses:

Select Signature: Displays the corresponding request matches.
Select Request: Shows the related signatures and response matches.
Select Response: Reveals the associated requests and signatures.

Click the image to enlarge it.

Scenarios for Conditional Match

Conditional Match can be used in various scenarios where precise control over request-response interactions is required. For instance:

Simulating Different User Interactions: Adjust responses based on user-specific data sent in the request body.
Handling Complex Logic: Implement logic within mock services to respond differently based on intricate conditions.
Validate Signature Headers: Validating headers ensures that the requests include the necessary metadata before they are processed.
Testing Different API Behaviors: Test how your system reacts to a wide range of request conditions without changing the underlying code.

Exporting matches as JSON

A new option has been added to preview and export matches as JSON.

Select one or more requests to export, then click the Export to JSON button.

Click the image to enlarge it.
If a single request is selected, a preview will open in a new window.

Click the image to enlarge it.
You will then be prompted to choose a location and name for the file to save.

Click the image to enlarge it.
If multiple requests are selected, you will be prompted to select a directory to save the zipped exported requests.

Click the image to enlarge it.