TCP Virtual Services

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


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:

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

    The New Empty Project option
  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:

    Create a new TCP virtual service

    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:

A new virtual service and its properties

Click the image to enlarge it.

Add operations

Option 1

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

The Add TCP Operation button

Click the image to enlarge it.

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

The TCP request and its editor

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:

Service virtualization and API testing: The Duplicate VirtAction command

Click the image to enlarge it.

Option 3

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.

Send requests

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.

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

    Add TCP Script

    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.
    Add TCP Script

    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.

    Add TCP Script

    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.

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.

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

You can configure the editor, using the following options:

Option Description
View mode Specifies the view mode of the editor. Possible options:
  • Code — Raw representation of the message.
  • Text — ASCII representation of the message.
  • Dual — Includes both views, with the Code view on the left and the Text view on the right.
Encoding The encoding you want to use for your request and response messages.
Code Type How ReadyAPI should represent the message in the Code view.
  • Hexadecimal
  • Decimal
  • Octal
  • Binary
Show unprintable 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.


See Also

Virtual Service Specifics

Highlight search results