A tester uses a web browser to access the console. The console manages the virtual service. The system under test (application under test) connects directly to the virtual service on different ports.
For more details see the documentation for the protocol you are interested in:
There are several ways of stopping Traffic Parrot. You can use any of them.
By pressing Ctrl+C:Each time Traffic Parrot is started or stopped, it writes to the tp.out file detailing the startup or shutdown process. This file can be useful to help diagnose issues when starting and stopping.
The main log file is written to logs/trafficparrot.log and contains information about what Traffic Parrot is doing while it is running.
Some changes to Traffic Parrot configuration require a restart. Please find further information in the lists below.
You configure Traffic Parrot web console and virtual service by editing property values in trafficparrot.properties file or by passing parameters to the start script.
All configuration properties are documented in the Configuration Reference page.
The trafficparrot.properties is located in the main Traffic Parrot directory. Open trafficparrot.properties file in your favourite text editor and update the property values. The names of properties should be self-explanatory. If you have any issues just request help by emailing us.
You can also configure Traffic Parrot by passing arguments to the start script. This will override properties defined in the trafficparrot.properties file.
./start.sh trafficparrot.gui.http.port=20000 trafficparrot.virtualservice.http.port=20001
start.cmd trafficparrot.gui.http.port=20000 trafficparrot.virtualservice.http.port=20001
The list of all available properties that can be configured is available in the trafficparrot.properties file which is located in the main Traffic Parrot directory.
Some properties may only be changed by passing values to the start script. For example, outbound HTTPS certificate configuration and outbound HTTP proxy configuration may only be specified as start script values.
| Property name | Description | Example usage |
|---|---|---|
| trafficparrot.gui.http.port | Port number of the HTTP Web UI | trafficparrot.gui.http.port=18080 |
| trafficparrot.gui.https.port | Port number of the HTTPS Web UI | trafficparrot.gui.https.port=18079 |
| trafficparrot.gui.security.mode |
Web UI security configuration:
|
trafficparrot.gui.security.mode=LOGIN_PROPERTIES Contents of trafficparrot.gui.login.properties in Jetty HashLoginService format: admin=password,traffic-parrot-gui-role |
| trafficparrot.virtualservice.trafficFilesRootUrl | Points to the location of traffic recording and replay files. While recording, new files will be written to that location. While replaying, mappings will be read from that location. Allows for checking-in traffic files to source control like Subversion or GIT (or any other). Currently only "file:" URLs are supported. |
Example on Linux (in one line, no spaces): trafficparrot.virtualservice.trafficFilesRootUrl =file:/home/dev/git/paymentsapi/trafficparrot_files Example on Windows (in one line, no spaces): trafficparrot.virtualservice.trafficFilesRootUrl =file://C:\Users\tom\workspace\sales\api_rec |
| trafficparrot.virtualservice.http.port | HTTP virtual service port number | trafficparrot.virtualservice.http.port=18081 |
| trafficparrot.virtualservice.https.port | HTTPS virtual service port number | trafficparrot.virtualservice.https.port=18082 |
If your system requires the use of a HTTP proxy to make outbound connections (e.g. in a corporate environment) you can tell Traffic Parrot to use the proxy using the settings below. The values must be passed to the start script.
| Property name | Description | Example usage |
|---|---|---|
| http.proxyHost | The hostname or IP address of the HTTP proxy server | http.proxyHost=localhost |
| http.proxyPort | The port number of the HTTP proxy server | http.proxyPort=9043 |
| https.proxyHost | The hostname or IP address of the HTTPS proxy server | https.proxyHost=192.168.2.6 |
| https.proxyPort | The port number of the HTTPS proxy server | https.proxyPort=9044 |
| java.net.useSystemProxies | If you have a system level proxy configured you may instead be able to set this flag to true | java.net.useSystemProxies=true |
If you need to record a system with a certificate that is not trusted by default, you will need to specify the trust store properties. The values must be passed to the start script. This is used for one-way SSL scenarios.
| Property name | Description | Example usage |
|---|---|---|
| javax.net.ssl.trustStore | The path to the trust store file containing the trusted certificates | javax.net.ssl.trustStore=C:\path\to\trust.jks |
| javax.net.ssl.trustStorePassword | The password of the trust store | javax.net.ssl.trustStorePassword=password |
| javax.net.ssl.trustStoreType | The type of trust store (e.g. jks or pkcs12) | javax.net.ssl.trustStoreType=jks |
If you need to record a system that requires a client certificate for authentication, you will need to specify the key store properties. The values must be passed to the start script. This is used for two-way SSL scenarios requiring mutual authentication.
| Property name | Description | Example usage |
|---|---|---|
| javax.net.ssl.keyStore | The path to the key store file containing the client certificate to use | javax.net.ssl.keyStore=C:\path\to\key.jks |
| javax.net.ssl.keyStorePassword | The password of the key store | javax.net.ssl.keyStorePassword=password |
| javax.net.ssl.keyStoreType | The type of key store (e.g. jks or pkcs12) | javax.net.ssl.keyStoreType=jks |
cd trafficparrot-x-y-z-instance_1 ./start.sh trafficparrot.gui.http.port=18080 trafficparrot.gui.jmxConnectorServerPort=18085 trafficparrot.virtualservice.http.port=8081 trafficparrot.virtualservice.https.port=18082 trafficparrot.virtualservice.proxy.http.port=18095 trafficparrot.virtualservice.http.management.port=18083 trafficparrot.virtualservice.jms.management.port=19093 trafficparrot.virtualservice.jmxConnectorServerPort=18084 trafficparrot.virtualservice.grpc.tls.port=10051 trafficparrot.virtualservice.grpc.non.tls.port=10052 cd ../trafficparrot-x-y-z-instance_2 ./start.sh trafficparrot.gui.http.port=28080 trafficparrot.gui.jmxConnectorServerPort=28085 trafficparrot.virtualservice.http.port=28081 trafficparrot.virtualservice.https.port=28082 trafficparrot.virtualservice.proxy.http.port=28095 trafficparrot.virtualservice.http.management.port=28083 trafficparrot.virtualservice.jms.management.port=29093 trafficparrot.virtualservice.jmxConnectorServerPort=28084 trafficparrot.virtualservice.grpc.tls.port=20051 trafficparrot.virtualservice.grpc.non.tls.port=20052
If you connect to Traffic Parrot via HTTPS it will return a self-signed certificate.
If you would like Traffic Parrot to use a different certificate for its HTTPS virtual service you can override the PrivateKeyEntry called trafficparrot in trafficparrot-x.y.z/certificates/trafficparrot-keystore.jks. The password to the JKS keystore is trafficparrot.
For example:
cd trafficparrot-x.y.z/certificates # (optional) generate a new certificate openssl genrsa -out server.key 2048 openssl req -new -out server.csr -key server.key openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt openssl pkcs12 -export -in server.crt -inkey server.key -out server.p12 -name trafficparrot -CAfile ca.crt -caname root # import the certificate to traffic parrot keytool -importkeystore -deststorepass trafficparrot -destkeypass trafficparrot -destkeystore trafficparrot-keystore.jks -srckeystore server.p12 -srcstoretype PKCS12 -srcstorepass trafficparrot -alias trafficparrot # restart traffic parrot cd .. ./stop.sh ./start.sh # display the new certificate openssl s_client -showcerts -connect localhost:8082 </dev/null
There is a special file jvm.args that you can use to specify custom JVM arguments. One parameter per line. For example you can change the heap size with the -Xmx parameter.
System properties are also supported e.g. -Dproperty.name=value. This will override properties with the same name that are present in trafficparrot.properties but will not override key=value properties that are set by passing arguments to the start script.
test@test-pcs:~/Downloads/trafficparrot-no-jre-5.x.y$ export TP_STARTUP_WAIT_MILLIS=180000 test@test-pcs:~/Downloads/trafficparrot-no-jre-5.x.y$ ./start.sh /optf/programs/jdk1.8.0_181/bin/java Picked up environment startup timeout in milliseconds 180000
As an alternative to using the Traffic Parrot user interface, you can instead use the HTTP management APIs.
We have a Postman workspace file that you can import to demonstrate some of the common Traffic Parrot management APIs.
There is also some OpenAPI documentation of those APIs. Or you may download the raw OpenAPI specification.
Please note that these APIs are not fully documented yet - if you see something missing that you would like then please let us know and we will add it for you.
Traffic Parrot supports a method for grouping together virtual service mappings to form a scenario. For example you may wish to group together mappings used for different types of testing e.g. integration, manual and performance tests.
The default scenario stores mappings on the filesystem under the directory specified in trafficparrot.properties by the trafficparrot.virtualservice.trafficFilesRootUrl property. For example the mappings and __files directories which are used for HTTP mappings in the default scenario.
All other scenarios are placed in the scenarios directory, which is also found under the configured root folder. For example the scenarios/Example/mappings and scenarios/Example/__files which are used for HTTP mappings in the scenario named Example.
Once you have placed some files under a scenario directory you will see the scenario in the navigation bar dropdown:
Clicking on a scenario name will activate that scenario. The scenario directory on the file system will be used as the source of mappings until Traffic Parrot is shut down. The default scenario is activated when Traffic Parrot starts up.
You can also use the /api/scenarios REST API to switch between scenarios.
Here is the required workflow for using scenarios as part of your testing.
To create a new scenario create a new folder on disk in trafficparrot-5.0.0/scenarios directory, for example, trafficparrot-5.0.0/scenarios/hello-world-scenario.
You can then select that new scenario in the Traffic Parrot user interface dropdown and add mappings to it by recording or manually creating from request-response pairs.
Traffic Parrot supports role based access control (RBAC) with the following roles available:
| Role | Description |
|---|---|
| traffic-parrot-gui-role | Allows a user to access the UI |
| traffic-parrot-gui-edit-role | Allows a user to use the UI to add, edit and delete mappings |
trafficparrot.gui.security.mode=LOGIN_PROPERTIES
admin=password,traffic-parrot-gui-role,traffic-parrot-gui-edit-role readonly=password,traffic-parrot-gui-role
First, download the examples project which will help you get started. Please follow the instructions below for more information.
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-failsafe-plugin</artifactId>
<version>2.19.1</version>
<executions>
<execution>
<id>integration-tests</id>
<goals>
<goal>integration-test</goal>
<goal>verify</goal>
</goals>
</execution>
</executions>
<configuration>
<includes>
<include>**/*IntegrationTest*</include>
</includes>
<trimStackTrace>false</trimStackTrace>
</configuration>
</plugin>
You should ensure that your Maven Surefire Plugin tests do not overlap:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.19.1</version>
<configuration>
<excludes>
<exclude>**/*IntegrationTest*</exclude>
</excludes>
</configuration>
</plugin>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<version>2.19.1</version>
<configuration>
<excludes>
<exclude>**/*IntegrationTest*</exclude>
</excludes>
<failIfNoTests>false</failIfNoTests>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-failsafe-plugin</artifactId>
<version>2.19.1</version>
<executions>
<execution>
<id>integration-tests</id>
<goals>
<goal>integration-test</goal>
<goal>verify</goal>
</goals>
</execution>
</executions>
<configuration>
<includes>
<include>**/*IntegrationTest*</include>
</includes>
<trimStackTrace>false</trimStackTrace>
</configuration>
</plugin>
<plugin>
<groupId>com.trafficparrot</groupId>
<artifactId>trafficparrot-maven-plugin</artifactId>
<version>4.7.7</version>
<executions>
<execution>
<id>check-environment</id>
<phase>pre-clean</phase>
<goals>
<goal>check-environment</goal>
</goals>
</execution>
<execution>
<id>start-traffic-parrot</id>
<phase>pre-integration-test</phase>
<goals>
<goal>start</goal>
</goals>
</execution>
<execution>
<id>stop-traffic-parrot</id>
<phase>post-integration-test</phase>
<goals>
<goal>stop</goal>
</goals>
</execution>
</executions>
<configuration>
<acceptLicense>true</acceptLicense>
<downloadFrom>file:///${trafficparrot.zip.file}</downloadFrom>
<licenseFile>file:///${trafficparrot.license.file}</licenseFile>
<cacheDownload>true</cacheDownload>
<printLogs>true</printLogs>
<deleteAfterStop>true</deleteAfterStop>
<httpImportMappings>true</httpImportMappings>
<httpVirtualServicePort>18081</httpVirtualServicePort>
<httpsVirtualServicePort>18082</httpsVirtualServicePort>
<jmsConnectionsFile>file:///${project.build.testOutputDirectory}/trafficparrot/jms-connections.json</jmsConnectionsFile>
<jmsBrokerType>INTERNAL</jmsBrokerType>
<jmsInternalBrokerPort>19091</jmsInternalBrokerPort>
<jmsInternalBrokerProvider>ACTIVE_MQ</jmsInternalBrokerProvider>
<jmsReplayQueue>true</jmsReplayQueue>
<jmsQueueConsumeRequestsFromConnectionId>USE-TRAFFIC-PARROT-INTERNAL-BROKER</jmsQueueConsumeRequestsFromConnectionId>
<jmsQueueReplayResponsesToConnectionId>example-connection-id</jmsQueueReplayResponsesToConnectionId>
<jmsReplayTopic>true</jmsReplayTopic>
<jmsTopicReplayToConnectionId>example-connection-id</jmsTopicReplayToConnectionId>
<ibmMqConnectionsFile>file:///${project.build.testOutputDirectory}/trafficparrot/ibm-mq-connections.json</ibmMqConnectionsFile>
<ibmMqReplayQueue>true</ibmMqReplayQueue>
<ibmMqQueueConsumeRequestsFromConnectionId>ibm-mq-connection</ibmMqQueueConsumeRequestsFromConnectionId>
<ibmMqQueueReplayResponsesToConnectionId>ibm-mq-connection</ibmMqQueueReplayResponsesToConnectionId>
<ibmMqReplayTopic>true</ibmMqReplayTopic>
<ibmMqTopicReplayToConnectionId>ibm-mq-connection</ibmMqTopicReplayToConnectionId>
<additionalJarFiles>
<additionalJarFile>file:///${examples.jar.file}</additionalJarFile>
<additionalJarFile>file:///${ibm.mq.client.jar.file}</additionalJarFile>
</additionalJarFiles>
</configuration>
</plugin>
</plugins>
</build>
<repositories>
<repository>
<id>trafficparrot.com</id>
<url>https://trafficparrot.com/repository</url>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>trafficparrot.com</id>
<url>https://trafficparrot.com/repository</url>
</pluginRepository>
</pluginRepositories>
You will need to:
You can also provide your existing Swagger/OpenAPI/RAML definitions and Traffic Parrot will generate mocks based on the APIs and examples in the specification.
To import HTTP definitions:First, download the examples project which will help you get started. Please follow the instructions below for more information.
pluginManagement {
repositories {
maven {
url 'https://trafficparrot.com/repository'
}
}
}
You will also need to make changes similar to the following in your build.gradle.kts file:
plugins {
id("com.trafficparrot").version("4.5.4")
}
repositories {
maven("https://trafficparrot.com/repository")
}
startTrafficParrot {
// This can either be a file:/// or a http:// location of the Traffic Parrot release ZIP file
downloadFrom = uri("http://location/to/artifact/repository/trafficparrot-4.5.4-bin.zip").toURL()
// Set this to true to indicate that you accept the Traffic Parrot LICENSE terms
acceptLicense = false
// Set this to true if you would like to cache the download in the java.io.tmpdir
cacheDownload = true
// Set this to the location of your Traffic Parrot enterprise license file
licenseFile = file(project.projectDir.absolutePath + "/trafficparrot.license").toURL()
trafficFilesRoot = file(project.projectDir.absolutePath + "/src/test/resources/trafficparrot")
// This will import Swagger/OpenAPI/RAML specifications
httpImportMappings = true
httpVirtualServicePort = 18081
httpsVirtualServicePort = 18082
jmsConnectionsFile = file(project.projectDir.absolutePath + "/src/test/resources/trafficparrot/jms-connections.json").toURL()
jmsBrokerType = "INTERNAL"
jmsInternalBrokerPort = 19091
jmsInternalBrokerProvider = "ACTIVE_MQ"
jmsReplayQueue = true
jmsQueueConsumeRequestsFromConnectionId = "USE-TRAFFIC-PARROT-INTERNAL-BROKER"
jmsQueueReplayResponsesToConnectionId = "example-connection-id"
jmsReplayTopic = true
jmsTopicReplayToConnectionId = "example-connection-id"
}
stopTrafficParrot {
deleteAfterStop = true
}
You will need to:
You can also provide your existing Swagger/OpenAPI/RAML definitions and Traffic Parrot will generate mocks based on the APIs and examples in the specification.
To import HTTP definitions:By default Traffic Parrot reads its license from a trafficparrot.license file on the classpath (typically placed in the installation directory). This works well for a local installation, but baking the license file into a Docker image means you have to rebuild the image whenever the license changes, and the license is then embedded in an image layer.
You can instead supply the license through the TRAFFICPARROT_LICENSE environment variable, so it can be injected at runtime from a Kubernetes Secret, a Docker secret, or a secrets manager such as HashiCorp Vault — this follows the 12-factor approach of keeping configuration out of the image. If the environment variable is not set, Traffic Parrot reads the trafficparrot.license file from the classpath exactly as before, so existing installations are unaffected.
The license content is multi-line and encrypted, so it must be base64-encoded before it can be carried safely in an environment variable. Encode your trafficparrot.license file once and use the resulting single line as the value of the variable:
base64 -w0 trafficparrot.license
The -w0 flag disables line wrapping so the whole value is produced on a single line. (On macOS, GNU coreutils provides gbase64 -w0; the BSD base64 does not wrap by default.) A stray trailing newline in the value is tolerated — Traffic Parrot trims the value before decoding it.
Traffic Parrot resolves the license from the first source that is set, in this order:
| Priority | Source | Value |
|---|---|---|
| 1 (highest) | System property -Dtrafficparrot.license.content | base64-encoded license content |
| 2 | Environment variable TRAFFICPARROT_LICENSE | base64-encoded license content |
| 3 (lowest) | Classpath file trafficparrot.license | the raw license file (default behaviour) |
If the environment variable or system property is set but not valid (the value is not valid base64, or the decoded content is not a parseable license), Traffic Parrot fails to start with a clear error that names the variable — it does not silently fall back to the classpath file. This is intentional: a set-but-broken value is a misconfiguration you need to see rather than have masked. An unset (or empty) variable falls back to the classpath file as normal.
Pass the encoded license to docker run with --env:
docker run --name trafficparrot -d \
--env TRAFFICPARROT_LICENSE=BASE64_LICENSE_CONTENT \
-p 127.0.0.1:8080:8080 -p 127.0.0.1:8081:8081 trafficparrot
To avoid the value appearing in your shell history or process list, keep it in an env file that is not committed to source control and reference it with --env-file:
# trafficparrot.env (do not commit this file) TRAFFICPARROT_LICENSE=BASE64_LICENSE_CONTENT
docker run --name trafficparrot -d \
--env-file trafficparrot.env \
-p 127.0.0.1:8080:8080 -p 127.0.0.1:8081:8081 trafficparrot
With Docker Compose, inject the value at runtime rather than hard-coding it in a committed docker-compose.yml. The example below reads the variable from the environment of the host that runs docker compose up (for example exported from your secrets manager):
services:
trafficparrot:
image: trafficparrot
environment:
# value supplied from the host environment, not stored in this file
TRAFFICPARROT_LICENSE: ${TRAFFICPARROT_LICENSE}
ports:
- "127.0.0.1:8080:8080"
- "127.0.0.1:8081:8081"
In Kubernetes, store the encoded license in a Secret and reference it from the pod with valueFrom.secretKeyRef.
Create the Secret:
kubectl create secret generic trafficparrot-license \
--from-literal=license=BASE64_LICENSE_CONTENT
Reference it from the container:
env:
- name: TRAFFICPARROT_LICENSE
valueFrom:
secretKeyRef:
name: trafficparrot-license
key: license
The same approach works with the sample Helm chart — supply the encoded license as a chart value backed by a Secret rather than baking it into the image.
The license is sensitive. Inject it at runtime via a Kubernetes Secret, a Docker secret, or a secrets manager such as Vault. Do not commit the license (encoded or raw) to a source repository, and do not bake it into a Docker image layer. Traffic Parrot never logs the license content or the value of the environment variable.
The Traffic Parrot License Server supports supplying its own license through an environment variable in the same way — see Supplying the license in the License Server documentation.
To run Traffic Parrot in Docker you will need to use start-foreground.sh instead of start.sh.
Here is an example that should get you started:
FROM eclipse-temurin:21-jre RUN apt-get update && apt-get install unzip -y WORKDIR /opt COPY trafficparrot-*.zip trafficparrot.zip RUN unzip trafficparrot.zip && rm trafficparrot.zip && mv trafficparrot-* trafficparrot RUN chgrp -R 0 /opt/trafficparrot && chmod -R g=u /opt/trafficparrot WORKDIR /opt/trafficparrot CMD ["./start-foreground.sh"]
FROM alpine:3 RUN apk add --no-cache openjdk21-jre bash libc6-compat gcompat libgcc WORKDIR /opt COPY trafficparrot-*.zip trafficparrot.zip RUN unzip trafficparrot.zip && rm trafficparrot.zip && mv trafficparrot-* trafficparrot RUN chgrp -R 0 /opt/trafficparrot && chmod -R g=u /opt/trafficparrot ENV LD_LIBRARY_PATH=/usr/lib:/opt/trafficparrot/jre/lib/amd64/server:/opt/trafficparrot/jre/lib/amd64 WORKDIR /opt/trafficparrot CMD ["./start-foreground.sh"]
docker build -t trafficparrot .
docker run --name trafficparrot -d -p 127.0.0.1:8080:8080 -p 127.0.0.1:8081:8081 -p 127.0.0.1:8083:8083 -p 127.0.0.1:9093:9093 trafficparrot
until docker logs trafficparrot | grep "Started Traffic Parrot"; do sleep 1; done
docker stop trafficparrot
docker logs trafficparrot
docker rm -v trafficparrot
Please be aware of these important points when running Traffic Parrot in Docker:
ENV GUI_HTTP_PORT=8080
ENV VS_HTTP_PORT=8081
CMD exec ./start-foreground.sh \
trafficparrot.gui.http.port=$GUI_HTTP_PORT \
trafficparrot.virtualservice.http.port=$VS_HTTP_PORT
ENV LOG_LEVEL=ERRORThis can be then be configured for use:
log4j.rootLogger=${LOG_LEVEL},file,stdout
And the Dockerfile with: CMD exec ./start-foreground.sh -DLOG_LEVEL=$LOG_LEVEL
<Root level="${env:LOG_LEVEL}">
<root level="${LOG_LEVEL}">
Traffic Parrot can be run in OpenShift or any other Kubernetes based environment.
We have a sample Helm chart that can be used to help you get started, you can download it here and follow the included instructions.
For the latest examples, check out our Traffic Parrot Helm Examples GitHub repository.
./upgrade.sh /path/to/previous-trafficparrot
upgrade.exe "C:\path\to\previous-trafficparrot"
You can use JMX to monitor Traffic Parrot, for example by using JConsole.
Large enterprises with complex test environments often start with a proof of concept project. If you feel like you do not have very complex test environments in your organisation, or would like to just try the software go ahead and jump straight into the Quick start. Otherwise, here is an example of a plan divided into stages on how you can implement a proof of concept project today.
After completing this first step, you will have a Traffic Parrot installation ready to virtualize assets. This step is usually combined with Stage 1.
If you you are a large enterprise with complex environments you will be required to run prerequisite confirmation tests (bash commands, SSH connections, ...) to confirm environment set up readiness before proceeding to installation. This will help avoiding common pitfalls to speed up the proof of concept project.
After completing this step you will have a solid proof of the value of service virtualization and Traffic Parrot to your organization. Traffic Parrot will be up and running and deliver value; the whole team will not yet know how to use it.
After completing this step, proceed to Stage 2 to enable the whole team.
Introducing other team members to Traffic Parrot. After this step, the team should have been able to virtualize one more service on their own for the given system or across a given team.
Introducing Traffic Parrot to other teams. Showcasing the successful implementation in the first team. Repeat steps 0-2 for other teams.