TCP Virtual Services

TCP stands for the Transmission Control Protocol — a transport-level protocol on which Internet protocols of higher levels rely (HTTP, SOAP, HTTPS, and others). TCP and IP are foundation protocols of the Internet protocol suite (see the TCP and TCP/IP descriptions on the Web).

Developers may create TCP services if they find higher-level protocols excessive for their needs. These TCP services typically work faster than services based on higher-level protocols, as they don’t use data formats and data processing that higher-level protocols require. In ReadyAPI, you can create virtual services that emulate the behavior of such real TCP services.

TCP virtual services are able to listen to incoming TCP data streams and split them into separate requests. Using these virtual services, you can work with IP and TCP packets, as well as emulate sending raw data in the needed format.

In ReadyAPI, you create empty TCP virtual services, and then add virtual operations to them manually.

To create a service:

1. Create a project if no project is open. To do this, select File > New Empty Project from the main menu:

   

2. Select the APIs (Virtual) node and select Project > New Virtual Service from the main menu.

   — or —

   Select the APIs (Virtual) node and click Service on the toolbar.

3. In the subsequent dialog, select Empty TCP and click OK:

   

   Click the image to enlarge it.

A new virtual service will appear in the Navigator and in the virtual service editor. You can see the virtual service properties on the right:

Click the image to enlarge it.

Option 1

To add new operations to a TCP virtual service, simply right-click the virtual service and select Add TCP Operation::

Click the image to enlarge it.

A request will appear in the virtual service editor. You can edit the request body on the right:

Click the image to enlarge it.

Option 2

You can also quickly create an operation by cloning an existing operation: click Duplicate VirtAction for an existing operation and then modify its properties in the editor on the right:

Click the image to enlarge it.

Option 3

When you send a request to a TCP virtual service, you send the request to certain TCP socket on that server. A typical request URL looks like this:

http://virt-address:port

ReadyAPI does not include any means for sending TCP data like it does, for instance, for SOAP services (SOAP Request test steps). You will have to use third-party software, for example, the open source Packet Sender solution.

ReadyAPI uses Groovy scripts to match TCP requests. You can write scripts for the entire TCP virtual service or individual requests.

1. To match the script, add a Routing Script to the TCP Virtual API.

   

   Click the image to enlarge it.

   This script has access to various objects, including the log, context, mockRunner, and requestBody. The requestBody represents the incoming request as a byte array. The routing script executes after the request delimiter script.

2. In the TCP request panel, select Exact in the Matching Strategy Selector.

   By default, the selector is set to Exact matching. This selector enables ReadyAPI to match incoming requests exactly to the request body visible on the TCP request panel.

   Note:

   Exact matching currently works for local TCP Virtual Services only. Support for TCP services deployed to VirtServer will follow in our next releases.

   

   Click the image to enlarge it.

3. To match the script, select Script in the Matching Strategy Selector. It allows you to apply custom scripting logic while matching incoming requests to Virtual Actions.

   

   Click the image to enlarge it.

   When you select the script matching strategy, the Apply global routing script checkbox becomes visible (unchecked by default), and the Routing Script window becomes accessible.

   Apply a global routing script – 

   • When this checkbox is checked, the script defined at the Virtual Service level is applied to the corresponding Virtual Action.

   • If the checkbox is not checked, the script defined at the level of the Virtual Action is used. Routing scripts have access to all global routing script objects, including the new bodyTemplate object. The bodyTemplate is a byte array containing the request body defined at the level of the Virtual Action.

Both global and action level routing scripts should return a boolean value. If nothing or a non-boolean value is returned or if the script throws an exception, it is treated as if the script returned false. When multiple Virtual Actions match an incoming request, the first Virtual Action from the list will be matched. This prioritization can be significant in scenarios where overlapping requests exist. Scripts are executed in the order of Virtual Actions from top to bottom.

A TCP virtual service listens to the data stream that it receives from a client. The TCP standard does not define any data format of the incoming data, so the service and clients use some arbitrary format to which they agreed.

To detect a request, the service monitors the incoming stream for the request delimiter character (you set it in virtual service properties). Once the delimiter is found, the service treats all bytes before the delimiter as request data, and starts listening for another request.

To find a response for the reply, the service searches for the virtual operation that matches the received request data. To do this, it compares the received data with the request data in virtual operations in your service. It compares them byte by byte.

When the virtual operation is found, the service selects a response according to the operation’s Dispatch style property, and then sends that response to the client. The service automatically appends the response delimiter character to the response data, so the client can identify response bounds properly. (You specify this delimiter in virtual service properties.)

If the service fails to find a virtual request matching the incoming data, it ignores that incoming data.

If the service has two virtual operations that match the same request data, it will use the first found operation.

You can run TCP 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.

In the TCP message editor, you can view and edit the contents of TCP request and response messages.

It is available in multiple locations in the virtual TCP service editor, see reference for details. The editor is also available from the Transaction Log in the view-only mode.

Tip:	You can open the editor in a separate dialog. To do that, click .

You can configure the editor, using the following options:

Note

Save messages to and load them from files

Properties

TCP Virtual Service Properties

TCP Request Properties

TCP Response Properties

Transaction Log Pages

TCP Request Log

TCP Response Log