JDBC Request Test Step

Applies to ReadyAPI 3.53, last modified on June 07, 2024

About JDBC Request test step

The JDBC Request test step sends a database query and returns the result.

You need to have a JDBC connector in the ext/bin directory for each database type you want to use.

Configuring JDBC Request test step

You can modify settings of a test step in the Configure panel of the request editor:

JDBC Request test step editor

Click the image to enlarge it.

Configure tab

The Configure tab contains the following edit fields:

Name Description
Parameter editor The list of properties used in the query. To modify them, use buttons on its toolbar:
  • – adds a new parameter.

  • and – move the selected parameter up or down.

  • – clears all parameter values.

  • – loads the list of parameters from a file. See below.

  • – exports the list of parameters to a file. See below.

  • – deletes the selected parameter.

  • To Rename a parameter, double-click its name or press F2 when the cell is selected.
  • To change a parameter value, double-click the value cell or press F2 when the cell is selected.
    You can use the project, test suite or other properties to specify parameter values.
Connection Specifies the desired database connection and allows you to create a new one. Also, you may set this option to None and use connection settings specified 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 specify connection used in test step.
Test Connection Tries to connect to the database by using the specified connection settings.
SQL Query

Specifies the query to the database. To use a test step parameter in the query, specify the name of the desired parameter with the leading colon character (:parameter). You can specify the desired query manually or by using the Build SQL Query or Create Query dialog.

Currently, you cannot use SQL queries with the double-colon (::) syntax.
Stored Procedure Enable this option, if your query is a call to a stored procedure. In this case, you specify only the name and parameters of the desired procedure. See below.
Convert Column Names to Uppercase If you enable this option, response elements will contain only uppercase characters.
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.

Raw tab

The Raw tab is filled after you send a request to a database. The tab displays the contents of the sent SQL query. If you use parameter names or property expansion expressions in your query, then the Raw tab will display the actual request data with all the expressions “expanded”.

Viewing response

You can examine a response from the database in the following panels:

  • XML - Shows the response data as XML data. In the XML panel, you can edit the content to create the needed response. See Request Editor Interface.

  • Outline - Shows the data in a tree-like structure. Allows you to quickly add assertions or set up a property transfer for later test steps. See Request Editor Interface.

  • Table - Shows the data in a tabular view.


    To limit the number of visible rows, use the drop-down list at the top of the panel.

    Note: This setting limits only the number of rows visible in the table. If you need to control the number of rows in the actual response, use the Max Rows property of the test step.

Property list

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

Name Description

The test step’s name.


Text describing the test step.

Max Rows

Specifies the maximum rows to obtain from a database.

Query Timeout

Specifies the number of seconds to wait for a database response. If there is no response during this period, the test step fails. The 0 or absent value means the infinite wait time.

Fetch Size

Specifies the number of rows obtained in one database roundtrip.

Due to the specifics of the MySQL Connector/J drivers, when you work with MySQL databases, you can specify only the -2147483648 value to obtain one row in a roundtrip. Other values are ignored.
Discard Response

When this option is set to true, ReadyAPI deletes the response data from memory after the assertion runs. Works only if the test step editor is closed.

Pretty print

When this option is set to true, the XML panel of the response displays data with line breaks and indents.

Processing a large XML document increases test step runtime. Set this option to false to decrease it.

Values on the Custom JDBC Request Test Step Properties tab are available to other test steps in your project. For instance, you can verify these property values with the Assertion test step, or check them and change the execution flow with the Conditional GoTo test step.

You can modify, add, remove and change custom properties load values of custom properties from a file, or save them to a file. To do this, use the toolbar items. See examples below, for more information.

This tab contains the following properties:

  • Properties that correspond to the request parameters.

  • A property that provides access to the request and response data.

Name Description

Provides access to the response data. The database’s response to JDBC requests is shown in the XML format. The property returns a hierarchy of XML nodes returned by the server. You can use this property to verify the response data.

Test step toolbar

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

JDBC Request test step toolbar

Click the image to enlarge it.

Verifying response

To add, change or modify them, use the Assertion panel. You can use the following assertions:

Name Description
Property Content:
Contains Verifies that the response contains the specified string.
Equals Verifies that the value of a property is equal to the specified value.
Equals (Binary) Checks whether the binary response is equal to a file.
Message Content Assertion Verifies that the message contains expected contents.
Smart Assertion Verifies the message content and metadata such as headers.
Not Contains Verifies that the response does not contain the specified value
XPath Match Checks whether the result of the specified XPath expression is equal to the specified value.
XQuery Match Verifies that the result of the specified XQuery expression is equal to the specified value.
Compliance, Status and Standards
HTTP Header Equals Checks whether the response contains the expected value of an HTTP header.
HTTP Header Exists Verifies that the response contains the specified HTTP header.
Swagger Compliance Assertion Verifies that a request and response are compliant with an OpenAPI or Swagger specification.
Script Assertion Executes a script to perform a custom assertion.
Response SLA Checks whether the response was returned within the specified timeout.
JDBC Status Verifies that the JDBC database returns a response.
JDBC Timeout Checks whether a JDBC database response returns within a specific time period.


While the test step editor is open, brief information on sent requests is listed in the Log tab. If the test step is run as part of a test case, you can see a more detailed log in the Transaction Log panel.

Working with

Below, you can find information on common tasks that you can perform with JDBC Request test step.

To connect to a database, you need to specify a connection. You can do it in one of the following ways:

  • Select an existing connection from the Connection drop-down list.

  • Specify a new connection and share it across all your projects, select the Create New option from the Connection drop-down list.

  • Specify a connection specific to the test step by selecting None from the Connection drop-down list and specifying a driver, connection string and password in the fields below. To use the Database Configuration dialog, click Configure.

    This connection will not be available from other test steps, test cases, test suites or projects.

To obtain values from a database, you send an SQL query. In ReadyAPI, you can visually create the desired query:

  • Click the Build Query button.

  • Use the ensuing Build SQL Query dialog to visually create the desired query. To learn how to do it, see Build SQL Query Wizard.

Alternatively, you can specify the desired query manually by typing it in the SQL Query field.

To specify a call to a stored procedure in a query, do the following:

  1. Enable the Stored Procedure option.

  2. Enter the name of the stored procedure in the SQL Query field.

  3. Specify the needed parameters in the same order as they are declared in a database.


To modify test step parameters, use the toolbar buttons that allow you to add, remove parameters, clear its values and change its order. Also, you can import and export a list of parameters from/to a file (see below).

To export parameters to a file, click and specify the file to which you want to save the request parameters.

ReadyAPI exports the list of the request parameters and the ResponseAsXML custom property.

To import parameters from a file:

  • Click and specify the file to import in the ensuing Load Properties dialog.

  • If the file contains properties that are not specified in the request, ReadyAPI can create them. For this, enable the Create Missing option.

  • If the request contains properties that are not specified in the file, ReadyAPI can remove them. For this, enable the Delete Remaining option.

Loading from a file does not affect the ResponseAsXML custom property, even if it is specified in the file.

To use a parameter value in a database query, specify its name after the colon. For example, the following query uses the continent parameter to pass a value to the WHERE clause:

SQL Query

FROM country
WHERE country.continent = :continent

You can use the project, test suite, and other property types as parameter values. To refer to a property, use the following syntax:

  • ${#Project#MyPropertyName} – Project properties.

  • ${#TestSuite#MyPropertyName} – Test suite properties.

  • ${#Env#MyPropertyName} – Environment properties.

For more information, see Property Expansion.

To verify that the server returns the expected response, use assertions:

  1. In the Assertions panel in the test step editor and click .

  2. In the Add Assertion dialog, specify the desired assertion.

  3. Set up a new assertion according to your needs and click OK.

To remove the Content-Length: 0 header from your request, add the -Dsoapui.send.zero.content.length=false parameter to the vmoptions file located in the <ReadyAPI>/bin directory and restart ReadyAPI.

See Also

Data Source Test Step
Data Sources and Data-Driven Tests
Test Steps

Watch the video
Highlight search results