API Simulation Wrappers (Beta)

Beta. API simulation wrappers are a beta feature and may change.

An API simulation wrapper calls an HTTP endpoint before each simulation in a test set. Values from the JSON response become available as template variables in the test case’s Simulation Input. Use an API simulation wrapper when a scenario needs fresh data at runtime, such as a test customer, account identifier, quote, reservation, or session. The wrapper is configured once for the test set. Saving the test set applies the same configuration to every test case in it, while the endpoint is called separately before each simulation.

Configure an API call

Open a test set

Open Test Sets, then select the test set you want to configure.

Select the API wrapper

In Simulation setup, select API and click Add Pre-Simulation API Call.

Configure the request

Enter the endpoint URL, HTTP method, timeout, and any optional JSON request body or headers.

Reference the response

Add {{sim_wrapper.api.*}} variables to your test case inputs using the response examples below.

Save the test set

Save to apply the configuration to every test case in the test set.

Request settings

Setting	Required	Description
API URL	Yes	The full URL Coval calls before the simulation.
Method	Yes	`GET`, `POST`, `PUT`, or `DELETE`. Defaults to `GET`.
Timeout	Yes	How long to wait for the endpoint, in seconds. Defaults to `30`.
Request Body	No	A JSON request body for `POST` or `PUT` requests.
Headers	No	A JSON object containing request headers, such as an authorization header.

Use test data and scoped credentials. Do not place production secrets or real sensitive customer data in test set configuration or endpoint responses.

Use an object response

For a JSON object response, fields are available directly under sim_wrapper.api. For example, if the endpoint returns:

{
  "customer": {
    "firstName": "John",
    "phoneNumber": "3034186858"
  }
}

Use these values in a scenario:

You are {{sim_wrapper.api.customer.firstName}}, a customer calling for help.
Your phone number is {{sim_wrapper.api.customer.phoneNumber}}.

Use an array response

For a JSON array response, the complete array is available under sim_wrapper.api.response. Use bracket notation to select an item. For example, if the endpoint returns:

[
  [
    { "phoneNumber": "3034186858" },
    { "firstName": "John" }
  ]
]

Use the nested values in a scenario:

You are a customer. Your phone number is {{sim_wrapper.api.response[0][0].phoneNumber}}.
Your first name is {{sim_wrapper.api.response[0][1].firstName}}.

Property names are case-sensitive and must match the JSON response exactly. For example, phoneNumber and phone_number are different properties.

Troubleshooting

Confirm the endpoint is publicly reachable from Coval and returns a successful HTTP status.
Confirm the response body is valid JSON.
Check that every property name and array index in the template matches the response.
Increase the timeout if the endpoint regularly needs more than 30 seconds.
Test the endpoint with non-sensitive sample data before running the full test set.

If a referenced value is unavailable, the template cannot be resolved in the simulation input.

Simulated Conversations

Evaluate

Analyze

Review

Cookbooks

Sofia

Reference

Configure an API call

Request settings

Use an object response

Use an array response

Troubleshooting

​Configure an API call

​Request settings

​Use an object response

​Use an array response

​Troubleshooting

Configure an API call

Request settings

Use an object response

Use an array response

Troubleshooting