Data Sink Test Step

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

About Data Sink test step

Use the Data Sink test step to store data collected in your tests to an external storage, such as Excel, text files, databases, and so on. In a usual case, you assign values to the test case properties and then store them to a data sink you need.

You can use the following data sinks:

Data Sink Description
Data Connection Writes property values to a database via a Prepared SQL statement, uses a DB Connection defined at the Project Level.
Excel Writes property values to an XLS file.
File Writes property values to a CSV file.
Groovy Invokes a script for handling property values.
JDBC Writes property values to a database via a Prepared SQL statement, uses JDBC.
Property Writes and aggregates property values to a new result property.
SubReport Writes property values to a subreport that can be used for custom reporting.
Using Data Sink and Data Source test steps together

When you run a test case that contains a Data Sink test step, the resource, to which you store data, is opened when the test case starts and is closed after the test case ends. To use a resource in both Data Sink and Data Source test steps, you need to place these test steps in separate test cases that are run in a sequence.

Using Data Sink in Distributed load tests

Due to the specifics of LoadUI agent, you must create a file, to which the data sink will store data, before starting your test. If you do not create the file on the remote computer, ReadyAPI Performance Agent will create it in a subdirectory of the <home>/.readyapi/loadui/agent-projects directory.

Requirements

To use this test step, you need a ReadyAPI Test license. If you do not have it, you can request it on our web site or start a trial.

Editing Data Sink test step

You can modify settings of a test step in its editor:

Data Sink test step editor

Click the image to enlarge it.

Here is a brief description of available panels in the test step editor:

Properties panel

Shows the list of step properties. The Data Sink test step writes data from these properties.

To manage the list, use the toolbar items:

  • – Adds a new property to the end of the list.

  • and – Move the selected property up and down in the property list.

  • – Sorts properties alphabetically.

  • – Clears the list of properties.

  • – Loads the list of properties from a file.

  • – Saves the list of properties to a file.

  • – Removes the selected property.

Also, you can import a list of properties from a file.

Note: You can use a Get Data dialog to specify the property expansion for the property value. To do this, double-click the Value cell to start editing, then right-click it and select Get Data from the context menu.

Configuration panel

In this panel, you can select the Data Sink type and configure it according to your needs.

Data log

In the Data Log, you can preview retrieved values.

Data Sink types

The Data Connection data sink stores data to the database by using a predefined JDBC database connection. It allows you to specify one connection and use it in several ReadyAPI test steps, as well as in the virtual service data sources within the project.

If you need to use this connection only once, you can use the JDBC data sink.

Note: To use the data connection data sink, you need to install a database driver. To learn how to do this, see Installing Database Drivers.
Data Connection data sink

Click the image to enlarge it.

Option Description
Connection Specifies the name of a database connection.
Configure Opens the Database configuration dialog to modify the selected database connection.
Test Connection Tests the selected database connection.
SQL Update Specifies the query to the database. You can specify the desired query manually or by using the Build SQL Query or Create Query dialog.
To insert test step property values into the query, use a question mark (?). The values will be used in the order they are specified on the property list on the left.
Property expansion does not work in the query. Use a question mark (?) to insert values instead.
You can read more about working with SQL queries below.
Stored Procedure Specifies if the defined SQL Query uses a stored procedure of the database.
Use a wizard Opens a dialog to specify an SQL Query. If the Stored Procedure option is enabled, it opens the Create Query dialog, otherwise the Build SQL Query dialog.
The Data Sink options are initialized at the start of the test case execution. You cannot use dynamic values with them. Property expansions referring to test case-level properties will not work as expected. Instead, use test suite- and project-level properties.

The Excel data sink stores data to a Microsoft Excel file. It assigns data from the test step properties to the columns in the order they are listed in the editor. That is, the value of the first property will be stored to the first column, the second property – to the second column, and so on.

Excel data sink

Click the image to enlarge it.

Option Description
Output File The target Excel file to write.
Worksheet The name of the worksheet tab to store data.
Append to end of file If checked, the data sink appends new data at the end of the source file and writes all data to the output file. Otherwise, it overwrites data starting from the cell specified in the Start at Cell field.
Start at Cell A cell to start from.

Advanced Options

The Data Sink options are initialized at the start of the test case execution. You cannot use dynamic values with them. Property expansions referring to test case-level properties will not work as expected. Instead, use test suite- and project-level properties.

See an example of using the Excel data sink below.

The File data sink saves data to a text file. It writes data to the specified file line by line separating property values by the specified symbol in the order they are listed in the editor.

File data sink

Click the image to enlarge it.

Option Description
File File to write to.
Separator Specifies the character to be used to separate values in a file. The default value is a comma (,). If no value is specified, the default one is used.
Escape character The character that will be used to escape double-quote characters in values and to escape the Escape character if some value contains it.
If you don’t need to escape, leave this field empty.
The default value is " (a double quotation mark).
Quote Specifies whether ReadyAPI adds double quotes around values. This will help you make the file readable in case some value includes the Separator character.
Trim Specifies whether ReadyAPI removes trailing or leading spaces from the stored value.
Append Specifies if ReadyAPI appends data to an existing file.
Encoding Specifies the encoding used to read the file.
The Data Sink options are initialized at the start of the test case execution. You cannot use dynamic values with them. Property expansions referring to test case-level properties will not work as expected. Instead, use test suite- and project-level properties.

Use the Groovy data sink to store values by executing a groovy script.

Groovy data sink

Click the image to enlarge it.

Specifies the groovy code that will store the desired data. You can use the following objects in the script:

  • context – Provides a scripting interface to properties specific to the current test run context.

  • properties – An associative array, keys of which match the data sink properties.

  • testRunner – Provides scripting interface to the test runner object that is executing the current test case and test step.

  • log – Provides a scripting interface to the ReadyAPI test log.

See an example of using the Groovy data sink below.

The JDBC data sink stores data to the database by using the connection specified in the test step.

The data sink can either use a project database connection, or a connection specified only for the test step.

Note: To use the JDBC data sink, you need to install a database driver. To learn how to do this, see Installing Database Drivers.

The data source assigns values to the properties by matching the names of the database columns or aliases.

JDBC data sink

Click the image to enlarge it.

Option Description
Connection Specifies the name of a database connection. Specify None to use a connection defined in the test step.
Configure Opens the Database configuration dialog to modify the selected database connection.
Driver Specifies the used database driver if the Connection option is set to None.
Connection String Specifies the used connection string if the Connection option is set to None.
Password Specifies the password to access the database if the Connection option is set to None.
Configure Opens the Database configuration dialog to modify the connection.
Test Connection Tries to connect to the database by using the specified connection settings.
SQL Update Specifies the query to the database. You can specify the desired query manually or by using the Build SQL Query or Create Query dialog.
To insert test step property values into the query, use a question mark (?). The values will be used in the order they are specified on the property list on the left.
Property expansion does not work in the query. Use a question mark (?) to insert values instead.
You can read more about working with SQL queries below.
Stored Procedure Enable this option, if your query is a call to a stored procedure. In this case, you can specify only the name and parameters of the desired procedure.
Build Query Opens a dialog to specify an SQL Query. If the Stored Procedure option is enabled, it opens the Create Query dialog, otherwise, the Build SQL Query dialog.
The Data Sink options are initialized at the start of the test case execution. You cannot use dynamic values with them. Property expansions referring to test case-level properties will not work as expected. Instead, use test suite- and project-level properties.

For more information on how to use a JDBC data sink, see the Storing Data Tutorial.

The Property data sink combines three values into one. For each row, it adds the content of the Content field between the contents of the Prefix and Suffix fields.

Property data sink

Click the image to enlarge it.

Option Description
Result Property The target property to write to.
Prefix The prefix for the property value.
Content Content of the property that ReadyAPI adds to the resulting property on each row.
Suffix The suffix for the property value.

For example, you specify the following settings:

Prefix <users>
Content <user name="${DataSource#name}"/>
Suffix </users>

When you run the test case, for the each row, you will get the following values:

Row 1 <users><user name="John Smith"/></users>
Row 2 <users><user name="John Smith"/><user name="Sarah Jane Smith"/></users>
Row 3 <users><user name="John Smith"/><user name="Sarah Jane Smith"/><user name="Mickey Smith"/></users>
The Data Sink options are initialized at the start of the test case execution. You cannot use dynamic values with them. Property expansions referring to test case-level properties will not work as expected. Instead, use test suite- and project-level properties.

The SubReport data sink collects data and exposes it to generated reports. No configuration is needed in the Data Sink. To use this data sink, generate a report with the Data Sink subreport.

Subreport data sink

Click the image to enlarge it.

The Data Sink options are initialized at the start of the test case execution. You cannot use dynamic values with them. Property expansions referring to test case-level properties will not work as expected. Instead, use test suite- and project-level properties.

Property list

Besides the test step editor, you can adjust the test step’s behavior by using its properties in the Data Sink Properties and Custom Data Sink Test Step Properties panels in the Navigator.

Name Description
Name

The test step’s name.
Description

Text describing the test step.

This page contains properties that you created in the test step editor. You can use the tab’s toolbar items to create and delete properties, save them to and load them from a file. To learn more, see About Properties.

Test step toolbar

The Test Step toolbar contains commands that allow you to modify a test step or appearance of the test step editor.

DataSink test step toolbar

Click the image to enlarge it.

Test step options

To open the Options dialog, click on the test step toolbar.

The options apply to the selected Data Sink test step regardless of the data source type.

The dialog contains the following options:

Option Description
Shared Controls whether this Data Sink should be shared between threads in a load test.

Logging

While the test step editor is open, you can see retrieved values in the Data Log panel. If the test step is run as part of a test case, you can see brief information on the test step run in the Transaction Log panel.

Working with

Below, you can find information on common tasks that you can perform with the Data Sink test step.

You can export the data acquired during the test run to a database through a Data Connection or JDBC data sink. To do this, you need to specify the properties you want to export in the property list on the left, and then refer to those properties in an SQL query in the SQL Update field:

Data Connection DataSink: SQL query example

Click the image to enlarge it.

You can specify the desired query manually or by using the Build SQL Query or Create Query dialog.

The question marks (?) in the query indicate the property values that will be exported to the database. The values will be used in the order they are specified in the property list. In the example above, the first question mark indicates the value of the placeid property, the second question mark indicates the value of the name property.

Property expansion does not work in queries. Use question marks (?) to insert values.

For information on how to set up a database connection, see the Storing Data Tutorial.

Use the Excel Data Sink test step to get data from your tests and store them in Excel files.

In this sample, we will add Excel Data Sink to the existing sample data-driven test case. To find out how to create data-driven tests, see the tutorials in the data-driven testing section.

  1. Open the REST Sample Project:

    Excel DataSink Example: Opening sample project

    Click the image to enlarge it.

  2. Open and run the DataDriven REST Test test case. This is required to get a response from the virtual service which we will use later.

    Excel DataSink Example: Run test case

    Click the image to enlarge it.

  3. Add a Data Sink test step. Then, place Data Sink after the Logout request test step. This ensures that Data Sink is part of the Data Source Loop.

    Excel DataSink Example: Test step order

    Click the image to enlarge it.

  4. Switch to Data Sink and select the Excel Data Sink type.

    Excel DataSink Example: Excel data sink type

    Click the image to enlarge it.

  5. Configure the Excel file properties:
    • Output File – Click Browse and select the Excel file to write data to.
    • Worksheet – Enter the name of the worksheet to write to. If it does not exist, ReadyAPI will delete all other worksheets and create the required one.

    • Start at Cell – Enter A1 to write data to the start of the Excel file.

      Excel DataSink Example: Excel file properties

      Click the image to enlarge it.

  6. Add a Property to the property list. Name it sessionid.

    Excel DataSink Example: Adding data sink property

  7. Right-click in the Value field and select Get Data.

    Excel DataSink Example: Property context menu

  8. In the ensuing Get Data dialog, select Sample REST Test Suite > DataDriven REST Test > Login > Response. Click Add.

    Excel DataSink Example: Get data dialog

    Click the image to enlarge it.

  9. Select the sessionid item in the response. This is the data that will be written to the data sink.

    Excel Data Sink Example: Specify JSONPath

    Click the image to enlarge it.

Done! You can now run the test, and Data Sink will write the response data to the Excel file you specified. Here is what this file looks like:

Excel DataSink Example: Resulting file

You can export data through a groovy script:

Groovy

Groovy

// Write a response from the "Test Request – login" test step to a file.
def response = context.expand('${Test Request – login#Response}')
new File("C:\\Work\\_response.txt").write(response)

// To use a different charset, use the following command.
// new File("C:\\Work\\_response.txt").write(response, "UTF-8")

See Also

Storing Data Tutorial
Data Source Test Step
Data Source Loop Test Step
Test Steps

Watch the video
 
Highlight search results