About

In ReadyAPI, you can create virtual services that emulate the behavior of real relational databases. You do this by recording real database responses and using their data later as virtual responses.

We call these services JDBC virtual services. They help you create and run tests when the use of a real database is inconvenient or impossible, for example:

They help you design API operations that work with a database that is not ready yet, or that is “closed” for maintenance.
They help you bypass primary key constraints of a real database, or, in general, receive database responses that match your current tasks.

Imagine, for example, that your API has an operation for creating a user account and storing it to some database table. When developing or testing such an API, you may need to run this operation several times. This will result in adding duplicated data to the database, which is often prohibited in real life. JDBC virtual services help you work around this limitation by simulating the database behavior, in which the user data is always “new”.
You can alter the data of virtual responses in any way you like to mask the information stored in a real database. This makes the virtual services useful for creating and testing APIs that function in the medical industry and in other areas, where privacy is highly important.

Create JDBC Virtual services

You create JDBC virtual services from scratch. This means that you create an empty service and then add virtual operations to it by recording requests to an existing database. To create a JDBC service:

Point to the APIs (Virtual) node in the Navigator panel and click :
In the subsequent dialog, select Empty JDBC and click OK.

Click the image to enlarge it.

Then, add operations as described below. You can copy, modify and delete the recorded database responses, but you cannot create new responses manually.

Add Operations

To add an operation to the virtual service, you must record a request that is routed to a real database:

Open the virtual service editor. Set Route Options to Route and Record Non-Virted Request.
Specify a database connection:
- In the Route to field, specify a connection string for your database, for example jdbc:mysql://127.0.0.1:3306/MyDatabase. You can find the connection string syntax in the database documentation.
  
  Make sure to place the database driver to the <ReadyAPI>\bin\ext folder.
- In the Username and Password fields specify credentials of the database user.
  
  Note: You can specify the username and password in a connection string. In this case, you can leave these fields empty.
Click the image to enlarge it.
Send a request to the virtual service (see below for detailed information). ReadyAPI will analyze the request and response and add the operation to the service. You can do this from any JDBC client or ReadyAPI.

An alternative way to create an operation is to clone an existing operation and modify the clone according to your needs. You do this with the Duplicate VirtAction command:

Click the image to enlarge it.

For information information on editing operations, see JDBC Request Properties.

Send Requests

Sending requests to JDBC virtual services is similar to sending requests to a real database with the following distinctions:

To connect to a virtual service, you use the ServiceV JDBC driver in your JDBC client. ReadyAPI includes it by default, so you do not need to import the driver when working with the service from ReadyAPI by using the JDBC Request test step.
You can download the driver from the SmartBear website.

The name of the driver package:

com.smartbear.servicev.jdbc.driver.JdbcVirtDriver

If you send requests from a different client, add the SmartBear JDBC Driver to the <product installation>/lib/ directory and make sure it is included in your classpath.
Use the following template for the connection string:

jdbc:servicev://<host address>:<virt-service-port>

For example, jdbc:servicev://localhost:10080.
You do not need to specify your user name or password to work with the virtual service.

Tip: When routing is enabled, the virtual service handles all the interactions with the real database. You specify connection parameters in the virtual service, not in the request.
The query in the request must match one of the queries that the virtual service uses to dispatch the response.

How JDBC Virtual Services Store Data

ReadyAPI does not create a copy of a database when you configure a virtual service. Instead, it handles each request individually, depending on what query you sent. So, two queries that use Select statements to get data from the same table will be two different requests. This way you can modify one of them to return a faulty response, while the other request will complete correctly. It also means that ReadyAPI supports the same query statements your database does.

Request and Response Dispatching

When a JDBC virtual service receives a request it searches for a matching recorded request. If it finds a request with the same query, Catalog and Schema parameters, the service sends one of the specified responses. If the service has two virtual operations that match the same query, it will use the first operation found.

If the virtual service does not find a matching query it routes the request to a real database. If routing is disabled, the service returns Statement not virtualized.

If the request uses the Catalog or Schema parameters to narrow down the results, this information is also extracted from the request and must match the data recorded in the virtual service.

Run JDBC Virtual Services

You can run JDBC virtual services both on local and on remote machines:

On local computers, you can run them from within ReadyAPI and from the command-line runner.
To run virtual services on remote machines, you need VirtServer there.

For complete information, see Running Virtual Services.