` Traffic Parrot documentation
  1. Home
  2. Documentation
  3. Virtual Services

Virtual Services

« Back to documentation home

Virtual Services

Traffic Parrot provides two powerful features for managing test environments:

  • Virtual Services (Scenarios) - Create isolated test environments with separate mappings and configurations. Each virtual service can optionally run on its own dedicated HTTP/HTTPS ports, allowing multiple services to run simultaneously.
  • Composite Scenarios - Combine mappings from multiple virtual services into a single active scenario. This enables teams to share and merge their test data while maintaining separate scenario management.

Virtual services help organize your test data by project, team, or environment, while composite scenarios provide flexibility in combining these isolated test sets when needed.

Supported protocols

Currently the following protocols fully support the virtual services feature:
  • HTTP
  • HTTPS
  • Native IBM® MQ
  • JMS
Limited support is provided for the following protocols, as per the existing scenarios feature documentation:
  • gRPC
  • Files

Architecture

  • Each Traffic Parrot server can host one or more virtual services
  • Each virtual service has a separate configuration directory on the filesystem, including:
  • HTTP virtual services can be run on multiple ports
  • MQ virtual services can connect to multiple queue managers
  • JMS virtual services can connect to multiple brokers
Traffic Parrot Virtual Services Directories Architecture Diagram
Traffic Parrot Virtual Services Multiple HTTP Ports Architecture Diagram
Traffic Parrot Virtual Services Multiple Queue Managers Ports Architecture Diagram
Traffic Parrot Virtual Services Home

Managing Virtual Services

The virtual services can be managed using the Virtual Services UI page:

Traffic Parrot Virtual Services List
Add Virtual Service
To add a virtual service, click the new virtual service button:
Traffic Parrot New Virtual Service Button
Which will show a create dialog:
Traffic Parrot New Virtual Service Dialog

Click the submit button to create the virtual service. If a valid free HTTP/HTTPS port is specified, then the virtual service will be accessible on the ports specified.

Edit Virtual Service
To edit a virtual service, click the edit virtual service button for an existing virtual service in the list:
Traffic Parrot Edit Virtual Service Button
Traffic Parrot Edit Virtual Service Dialog

Click the submit button to edit the virtual service. If a valid free HTTP/HTTPS port is specified, then the virtual service will be accessible on those ports. The service will no longer be accessible on the old ports.

Delete Virtual Service
To delete a virtual service, click the delete virtual service button for an existing virtual service in the list:
Traffic Parrot Delete Virtual Service Button
Traffic Parrot Delete Virtual Service Dialog

Click the delete button to delete the virtual service. The service will no longer be accessible on the old port. The deleted virtual service mappings will be backed up in the deleted-scenarios directory.

Select Virtual Service
To select a virtual service, click on the name of the virtual service in the dropdown at the top of the page. This can be accessed from any page.
Traffic Parrot Select Virtual Service

Once selected, the following will happen:

  • The default HTTP virtual service port of 8080 will serve the selected virtual service over HTTP
  • The default HTTPS virtual service port of 8081 will serve the selected virtual service over HTTPS
  • The custom HTTP/HTTPS ports assigned to each virtual service remain active regardless of the currently selected virtual service
  • The Add/Edit/Record/Replay pages for all protocols now impact the currently selected virtual service
Virtual Service Properties
Each virtual service has a service.properties file that is used to specify configuration such as custom HTTPS certificates and MQ startup settings:
Property name Description Example usage
http.port The HTTP port for the virtual service http.port=9017
https.port The HTTPS port for the virtual service https.port=9018
https.key.store.path Path to the HTTPS key store to use, relative to the virtual service directory https.key.store.path=certs/server.jks
https.key.store.password The password for the HTTPS key store https.key.store.password=password
https.key.manager.password The password for the HTTPS key store manager https.key.manager.password=password
https.key.store.type The type of key store used, for example JKS or PKCS12 https.key.store.type=JKS
https.need.client.auth Whether client authentication is required. Set to true or false. https.need.client.auth=true
https.trust.store.path Path to the HTTPS trust store to use, relative to the virtual service directory https.trust.store.path=certs/servertrust.jks
https.trust.store.password The password for the HTTPS trust store https.trust.store.password=password
https.trust.store.type The type of trust store used, for example JKS or PKCS12 https.trust.store.type=JKS
ibm.mq.queue.replay.on.startup When set to true, replay mode will be enabled for this virtual service ibm-mq-mappings on startup ibm.mq.queue.replay.on.startup=true
ibm.mq.queue.replay.request.queue.manager The name of the queue manager to connect to consume request messages, as specified in ibm-mq-connections.json ibm.mq.queue.replay.request.queue.manager=REQ.QM
ibm.mq.queue.replay.response.queue.manager The name of the queue manager to connect to produce response messages, as specified in ibm-mq-connections.json ibm.mq.queue.replay.response.queue.manager=RSP.QM
jms.queue.replay.on.startup When set to true, replay mode will be enabled for this virtual service jms-mappings on startup jms.queue.replay.on.startup=true
jms.queue.replay.request.connection.id The id of the connection to use to consume request messages, as specified in jms-connections.json jms.queue.replay.request.connection.id=1
jms.queue.replay.response.connection.id The id of the connection to use to produce response messages, as specified in jms-connections.json jms.queue.replay.response.connection.id=2

Virtual Service Configuration

HTTP

To configure a HTTP virtual service you should:

  1. (optional) Follow the instructions to add a new virtual service and specify a HTTP port
  2. Follow the instructions to select a virtual service
  3. Use the HTTP UI to Add/Edit mappings

HTTPS

To configure a HTTPS virtual service you should:

  1. Follow the instructions to configure a HTTP virtual service and specify a HTTPS port
  2. (optional) Configure HTTPS configuration in the scenarios/ServiceName/service.properties file:
    • https.key.store.path=certs/server.jks
    • https.key.store.password=password
    • https.key.manager.password=password
    • https.key.store.type=JKS
    • https.need.client.auth=true
    • https.trust.store.path=certs/servertrust.jks
    • https.trust.store.password=password
    • https.trust.store.type=JKS

Native IBM® MQ

To configure a Native IBM® MQ virtual service you should:

  1. Configure the required IBM® MQ JARs (only needs to be done once per Traffic Parrot instance)
  2. (optional) Follow the instructions to add a new virtual service
  3. Follow the instructions to select a virtual service
  4. Configure the scenarios/ServiceName/ibm-mq-connections.json file
  5. Use the Native IBM® MQ UI to Add/Edit mappings and turn on replay mode
  6. (optional) Configure Native IBM® MQ startup configuration in the scenarios/ServiceName/service.properties file:
    • ibm.mq.queue.replay.on.startup=true
    • ibm.mq.queue.replay.request.queue.manager=REQ.QM
    • ibm.mq.queue.replay.response.queue.manager=RSP.QM

JMS

To configure a JMS virtual service you should:

  1. (optional) Configure the required IBM® MQ JARs (only needs to be done once per Traffic Parrot instance and if using IBM® MQ as your JMS connection type)
  2. (optional) Follow the instructions to add a new virtual service
  3. Follow the instructions to select a virtual service
  4. Configure the scenarios/ServiceName/jms-connections.json file
  5. Use the JMS UI to Add/Edit mappings and turn on replay mode
  6. (optional) Configure JMS startup configuration in the scenarios/ServiceName/service.properties file:
    • jms.queue.replay.on.startup=true
    • jms.queue.replay.request.connection.id=1
    • jms.queue.replay.response.connection.id=2

Composite Scenarios

The Composite scenario feature allows you to combine mappings from multiple scenarios into a single active scenario. This is useful for testing complex environments where different teams maintain separate scenario sets that need to work together.

Accessing Composite Scenarios

To access the Composite scenario management interface:

  1. Navigate to the Virtual Services page from the main navigation bar
  2. Click the "Manage Composite Scenario" button (with grid icon) at the top of the page
  3. Alternatively, if the Composite scenario is listed in the virtual services table, click the "Configure" button next to it

The Composite scenario also appears in the scenario dropdown selector with a link emoji (🔗) indicator. Selecting it from the dropdown activates the Composite scenario rather than opening the management interface.

Managing Composite Scenarios

Composite scenario management interface

Adding Scenarios to Composite

To add a scenario to the composite:

  1. Navigate to the Composite Scenario page
  2. Select a scenario from the dropdown list
  3. Click "Add to Composite"

Removing Scenarios from Composite

To remove a scenario from the composite:

  1. Navigate to the Composite Scenario page
  2. Click the "Remove" button next to the scenario you want to remove

Clearing All Scenarios

Click "Clear All" to remove all scenarios from the composite at once.

How Composite Scenarios Work

When the Composite scenario is active:

  • Mappings from all included scenarios are combined and available
  • If multiple scenarios contain conflicting mappings, the last added scenario takes precedence
  • The composite scenario uses the default HTTP/HTTPS ports
  • Changes made while the Composite scenario is active are saved to the Composite scenario directory

Note

The Composite scenario is HTTP-only and does not support combining non-HTTP protocol mappings.

API Endpoints

The following REST API endpoints are available for managing composite scenarios:

Method Endpoint Description
GET /api/scenarios/http/composite Get composite scenario status and active scenarios
POST /api/scenarios/http/composite/add?scenario={name} Add a scenario to the composite
POST /api/scenarios/http/composite/remove?scenario={name} Remove a scenario from the composite
POST /api/scenarios/http/composite/clear Clear all scenarios from the composite

Limitations

  • The UI can only be used to make changes to one virtual service at a time
  • The UI does not support editing the following configuration, which must be configured directly using the file system and a text editor:
    • scenarios/ServiceName/service.properties
    • scenarios/ServiceName/data
    • scenarios/ServiceName/ibm-mq-connections.json
    • scenarios/ServiceName/jms-connections.json
    • scenarios/ServiceName/database-connections.json
  • Live changes to virtual services names and ports are only picked up if the changes are made via the UI (changes directly to the filesystem of a running instance are not picked up dynamically)
  • Only one Files/gRPC virtual service can be set to record or replay mode at a time
  • Switching virtual service while replay mode is active for Files is not supported and replay must be stopped before switching