Applies to ReadyAPI 2.5, last modified on October 22, 2018

About

A common task for a virtual API is to provide responses that have the same structure, but different data. For instance, your virtual service may return different temperature values for different places specified by parameters of incoming requests.

To solve this task, you may want to decouple the response structure from data and store the content outside of your service, for example, in some file or database. In ReadyAPI, virtual services support loading data from external data sources like Excel sheets, CSV files or database tables and inserting this data into the responses. This feature also allows you to create services that share the same set of data for their responses of different types. This topic describes how you can configure and use data sources in your virtual services.

DataSources Page

You specify a data source for your virtual services on the DataSources page of the virtual service editor:

Service virtualization and API testing: Using data sources in virtual services

Click the image to enlarge it.

Each data source has properties. They correspond to data source columns and provide access to the data source’s data.

Configure Data Sources

  1. Switch to the DataSources page of the virtual service editor. Click on the page toolbar and specify the data source name in the subsequent dialog box. You will use this name to refer to a data source:

    Service virtualization and API testing: Creating data sources

    Click the image to enlarge it.

  2. Select the data source type and specify connection settings:

    Service virtualization and API testing: Configuing data source connection settings

    Click the image to enlarge it.

    The connection settings are common across ReadyAPI tools. For detailed information, see DataSource Reference.

  3. Create properties for the data source. The properties provide access to the data source’s data. If your data source is based on an Excel sheet, on a database or a comma-separated value (CSV) file, the property names you enter must coincide with column names of the data source.

    ReadyAPI automatically suggests importing property names from the data source after you finish configuring the connection settings. We recommend accepting this suggestion. If you decline it, you can import properties any time later by clicking the button or create properties manually by clicking on the property list toolbar:

    Service virtualization and API testing: The Add Property command

    Click the image to enlarge it.

    We would like to remind that property names must coincide with the data source’s column names.

    Tip: For REST service users: If the response body you defined contains a JSON object, you can create data source properties from this object – simply click in the DataSource section of the response editor. This will create data source properties whose names coincide with the property names of the object. You can add the properties to a new data source, or to an existing one:
    Service virtualization and API testing: Create data source properties from JSON response

    Click the image to enlarge it.

After you set up data source settings and created properties, you can use the properties in responses (see below).

Configure Data Source Options

  1. Select the data source you want to configure. Click to open the configuration dialog.

    Service virtualization and API testing: Setting up data source options

    Click the image to enlarge it.

  2. Set up the options:

    • Trim – Commands the data source to remove leading and trailing spaces from the retrieved text values.

    • Entitize – Commands the data source to replace special HTML symbols (like & or >) with the appropriate entities (like & or >).

Refer to Data in Responses

  1. Switch to the Setup page of the virtual service editor.

  2. Select the desired response.

  3. In the property editor on the right, select your data source from the DataSource drop-down list:

    Service virtualization and API testing: Selecting data source

    Click the image to enlarge it.

  4. Use the property expansion syntax to refer to a property:

    ${property-name}

    – or –

    ${#MockResponse#property-name}

    You can insert these expressions into the response body or in a header. The property names are case-insensitive:

    Service virtualization and API testing: Referring to data source properties

    Click the image to enlarge it.

    If needed, you can use multiple property expansions, for instance:

    Service virtualization and API testing: Using multiple properties

    Click the image to enlarge it.

    For REST service users: The described functionality is available only when the Response Property Expansion property is true. By default, the property value is true. You may need to check it if the property expansion stopped working for some reason.

    Referring in Scripts

    To refer to a data source property in script code, you use the mockResponse.getPropertyValue(...) function. The property names are case-insensitive:

    Groovy

    def propertyValue = mockResponse.getPropertyValue('my-property-name')
    mockResponse.responseContent = "<data>" + propertyValue + "</data>"

    The getPropertyValue(...) function returns the property value in the “property expansion” format. For example, mockResponse.getPropertyValue('City') will return ${City}, not the actual value of the property like a string or a number. ReadyAPI will handle this expression and insert the actual value before sending the response. This means that you cannot check or compare actual property values in scripts.

How It Works

  1. When you start a virtual service that uses a data source, the service connects to the data source and positions the data cursor to the first record.

  2. When the virtual service receives a request, it selects a response according to the dispatch settings and runs script event handlers. At that, the service can retrieve data from the current data record and insert this data into the response. During all these actions, the data cursor points to the same record of the data source.

    After sending the response, the virtual service forwards the cursor to the next record. Note that the service forwards the cursor even if the selected response does not retrieve data from the data source.

  3. When the virtual service reaches the last record of a data source, it jumps to the first record.

You can see some statistics on using the data source in the property editor of your virtual service:

  1. Select your virtual service in the Navigator and look at the properties on the right.

  2. The DataSources section displays the list of data sources defined in your service. The Loops column indicates how many times that virtual service goes through all the data source records:

    Service virtualization and API testing: DataSources section in properties

    Click the image to enlarge it.

Supported Data Sources

Virtual services use the following data source types. Find information on data source settings by the links below:

Data Source Type Description
Excel A worksheet in an Excel workbook.
File A file with comma-separated values.
Grid An arbitrary table which you create on the DataSources page and to which you enter data manually. The data source properties you create on the DataSources page are columns of this table.
JDBC A table, view, query or stored procedure of some database, to which you connect through JDBC.
Data Connection A table, view, query or stored procedure of some database, with which you work through a predefined JDBC connection created in the Databases wizard.
Data Generator This data source generates test data for the properties you created on the DataSources page.

Data Generator

You use the Data Generator data source to generate test data for properties directly from the ReadyAPI UI. The entire procedure is quick and easy:

  1. Select the Data Generator type for your data source.

  2. Create properties.

  3. For each property, configure the data generator parameters to get the values that suite your needs best:

    Service virtualization and API testing: Create Data Generator data source

    Click the image to enlarge it.

ReadyAPI offers over a dozen of generators that create data of various types: human names, numbers, dates, emails, street addresses, and so on. For complete information on the generators and their parameters, see topics of the Data Generator section.

ReadyAPI stores the generated data as part of your virtual API data. When you deploy your virtual service to a remote server, the generated data will be copied along with the service settings to the server automatically.

Grid Data Source

You use the Grid data source to create test data manually. Select the Grid data source type, create properties and then enter data into the grid cells:

Service virtualization and API testing: Create Grid data source

Click the image to enlarge it.

To clone values quickly, enter some value into a cell (press Enter to confirm the input), then click this cell and select Fill Down or Fill Right at the bottom to clone values across other rows or columns correspondingly.

The Grid data source settings and data are stored in your ReadyAPI project as part of your service data.

See Also

Configuring Virtual Services

Highlight search results