The JDBC Request test step sends a database query and returns the result.
Important
You need to have a JDBC connector in the ext/bin directory for each database type you want to use.
You can modify settings of a test step in the Configure panel of the request editor:
 |
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:
|
Connection | Specifies the desired database connection and allows you to create a new one. Also, you may set this option to |
Configure | Opens the Database configuration dialog to modify the selected database connection. |
Driver | Specifies the used database driver if the |
Connection string | Specifies the used connection string if the |
Password | Specifies the password to access the database if the |
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 ( ImportantCurrently, you cannot use SQL queries with the double-colon ( |
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 |
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”.
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 property of the test step.
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.
JDBC Request Properties
Name | Description |
|---|---|
Name | The test step’s name. |
Description | 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. ImportantDue to the specifics of the MySQL Connector/J drivers, when you work with MySQL databases, you can specify only the |
Discard Response | When this option is set to |
Pretty print | When this option is set to ImportantProcessing a large XML document increases test step runtime. Set this option to |
Custom JDBC Request Test Step Properties
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 |
|---|---|
ResponseAsXml | 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. |
The test step toolbar contains commands that allow you to modify a test step or appearance of the test step editor.
 |
To add, change or modify them, use the Assertion panel. You can use the following assertions:
Name | Description |
|---|---|
Property Content: | |
Verifies that the response contains the specified string. | |
Verifies that the value of a property is equal to the specified value. | |
Checks whether the binary response is equal to a file. | |
Verifies that the message contains expected contents. | |
Verifies the message content and metadata such as headers. | |
Verifies that the response does not contain the specified value | |
Checks whether the result of the specified XPath expression is equal to the specified value. | |
Verifies that the result of the specified XQuery expression is equal to the specified value. | |
Compliance, Status and Standards | |
Checks whether the response contains the expected value of an HTTP header. | |
Verifies that the response contains the specified HTTP header. | |
Verifies that a request and response are compliant with an OpenAPI or Swagger specification. | |
Script | |
Executes a script to perform a custom assertion. | |
SLA | |
Checks whether the response was returned within the specified timeout. | |
JDBC | |
Verifies that the JDBC database returns a response. | |
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.
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 Newoption from the Connection drop-down list.Specify a connection specific to the test step by selecting
Nonefrom 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.Important
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:
Enable the Stored Procedure option.
Enter the name of the stored procedure in the SQL Query field.
Specify the needed parameters in the same order as they are declared in a database.
 |
Imagine there is the getOrdersByStatus stored procedure in your database. To use the stored procedure:
Specify the name of the procedure in the SQL Query field.
Specify the needed parameters in the order declared in the database. In this example, the stored procedure requires two parameters: the first parameter is the desired status, and the second one - the quantity of entries to return.
If a stored procedure uses output parameters, use the question mark (
?) to specify them. For example:getOrdersByStatus('pending', 5, ?)
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.
Important
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.
Important
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:
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:
In the Assertions panel in the test step editor and click
.In the Add Assertion dialog, specify the desired assertion.
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.