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.
Create TCP virtual services
In ReadyAPI, you create empty TCP virtual services, and then add virtual operations to them manually.
To create a service:
Create a project if no project is open. To do this, select File > New Empty Project from the main menu:
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.
In the subsequent dialog, select Empty TCP and click OK:
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:
To add new operations to a TCP virtual service, simply right-click the virtual service and select Add TCP Operation::
A request will appear in the virtual service editor. You can edit the request body on the right:
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:
One more possible way to add operations to a virtual service is to record traffic to some existing web service: you switch the service to a special recording mode and send requests to an existing web service. ReadyAPI will trace the requests and responses and create virtual operations from them. See Add Recorded Operations to Virtual Service.
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:
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.
Match TCP requests
ReadyAPI uses Groovy scripts to match TCP requests. You can write scripts for the entire TCP virtual service or individual requests.
To match the script, add a Routing Script to the TCP Virtual API.
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.
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.
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.
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.
Request and response dispatching
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.
Run TCP virtual services
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.
TCP message editor
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.
|You can open the editor in a separate dialog. To do that, click .
You can configure the editor, using the following options:
Specifies the view mode of the editor. Possible options:
|The encoding you want to use for your request and response messages.
How ReadyAPI should represent the message in the Code view.
|If selected, ReadyAPI shows the unprintable segments of the message in the editor.
Don’t include the request delimiter character into the request data, and don’t include the response delimiter to the response data in the editor. Including the request delimiter will cause incorrect request recognition, and as for response delimiters, the virtual service adds them automatically when sending responses. For more information on delimiters and their role in TCP communications, see above.
Save messages to and load them from files
Use the buttons at the bottom of the editor to save messages to and load them from files:
Save as — Saves the message content to the specified file.
Load from — Retrieves the content of the specified file and adds it to the message.
Note: Not available in the Transaction Log.