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.
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: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:8u352-b08-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.17.2 RUN apk add --no-cache openjdk8-jre bash libc6-compat gcompat 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:
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.
./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.
This documentation is for an old version of Traffic Parrot. There is a more recent Traffic Parrot version available for download at trafficparrot.com