1. Home
  2. Documentation
  3. User guide

User guide

« Back to documentation home

Architecture

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:

Supported protocols

gRPC

For details on HTTP service virtualization have a look at the HTTP documentation

HTTP

For details on gRPC service virtualization have a look at the gRPC documentation

JMS

For details on JMS service virtualization have a look at the JMS documentation

Native IBM® MQ

For details on IBM® MQ service virtualization have a look at the Native IBM® MQ documentation

Files

For details on file based messaging service virtualization have a look at the Files documentation

Testing with scenarios

Overview

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:

Scenarios 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.

Workflow

Here is the required workflow for using scenarios as part of your testing.

Protocol used is HTTP/gRPC
  1. Switch to scenario in the Traffic Parrot web user interface by selecting it from the dropdown
  2. Run tests that rely on scenario
Protocol used is JMS/MQ/Files
  1. Stop replay for protocol
  2. Switch to scenario in the Traffic Parrot web user interface by selecting it from the dropdown
  3. Start replay for protocol
  4. Run tests that rely on scenario

How to create a new scenario

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.

Starting and stopping

Linux, Unix and Mac

Start
  1. Open a terminal window
  2. Go to the installation directory cd trafficparrot-x.y.z
  3. Run start script ./start.sh
  4. (Optional) Inspect the startup log file and make sure there are no “ERROR”s less +F tp.out
  5. Open the web console in any modern web browser (Chrome, Firefox or MS Edge) http://localhost:8080
Stop
  1. Open a terminal window
  2. Go to the installation directory cd trafficparrot-x.y.z
  3. Run stop script ./stop.sh

Windows

Start
  1. Go to the installation directory trafficparrot-x.y.z
  2. Double click start.cmd or start.exe to run it
  3. (Optional) Inspect the console output and make sure there are no “ERROR”s
  4. Open the web console in any modern web browser (Chrome, Firefox or MS Edge) http://localhost:8080
Stop

There are several ways of stopping Traffic Parrot. You can use any of them.

By pressing Ctrl+C:
  1. Press Ctrl+C in the Command Prompt running Traffic Parrot
By running the stop script:
  1. Open a new Command Prompt.
  2. Go to the installation directory cd trafficparrot-x.y.z
  3. Run stop script stop.cmd or stop.exe
By clicking on the system tray:
  1. Click on the system tray icon
  2. Click quit

Logs

Start and stop logs

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.

Traffic Parrot logs

The main log file is written to logs/trafficparrot.log and contains information about what Traffic Parrot is doing while it is running.

Configuration changes requiring restart

Some changes to Traffic Parrot configuration require a restart. Please find further information in the lists below.

Changes requiring restart
  • Dockerfile changes
  • Kubernetes deployment configuration changes
  • JAR file changes including plugins
  • trafficparrot.properties file changes
  • jvm.args file changes
  • Changes to mappings when mappings cache is enabled
  • MQ start queue replay on startup script
  • HTTPS certificate changes
  • HTTP/HTTPS port changes
  • Add new virtual service folder
  • Remove existing virtual service folder
Changes not requiring restart
  • Changes to mappings for existing HTTP/HTTPS virtual service folder with mappings cache disabled
  • Changes to MQ/JMS/Files for existing virtual service folder with no changes to request/response queues and mappings cache disabled
Changes not requiring restart but requiring MQ/JMS/Files stop and start replay mode
  • Changes to MQ/JMS/Files with changes to request/response queues
  • Changes to MQ/JMS/Files connections JSON file

Configuration

Properties

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.

Changing properties in the file

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.

Passing values to the start script

You can also configure Traffic Parrot by passing arguments to the start script. This will override properties defined in the trafficparrot.properties file.

For example, on Linux: 
./start.sh trafficparrot.gui.http.port=20000 trafficparrot.virtualservice.http.port=20001
For example, on Windows: 
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.

Frequently changed properties
For the full list of available configuration options please see trafficparrot.properties file located in the Traffic Parrot directory.
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:
  • ALLOW_ALL will allow UI access to any user
  • LOGIN_PROPERTIES will only allow UI access for specified users

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

Outbound HTTP proxy settings

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

Outbound HTTPS certificates

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

Running more than one instance simultaneously

To run two Traffic Parrot instances in parallel, you need to configure it to run on different port numbers.
For example: 
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
Depending on your particular use case, you might have to change a number of additional properties values. For a list of all the available properties, please see trafficparrot.properties file located in the Traffic Parrot directory.

HTTPS certificates for the virtual service

Change the HTTPS server certificate

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

Change the HTTPS trusted entries
These certificates are used for the virtual service server during for example recording. The default pre-generated certificates are located in the certificates directory. You can change the virtual service HTTPS certificate by modifying the following properties in trafficparrot.properties file:
  1. trafficparrot.virtualservice.keystoreAndTruststore.jks.resource=certificates/trafficparrot-keystore-and-truststore.jks
  2. trafficparrot.virtualservice.keystoreAndTruststore.jks.password=trafficparrot

JVM arguments

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.

Logging

In order to change the logging level, see configuration files trafficparrotserver.log4j.properties.

Startup config

To configure how long the startup scripts will wait for TP to start up set an environment variable TP_STARTUP_WAIT_MILLIS, for example: 
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

Management APIs

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.

Running from Maven

First, download the examples project which will help you get started. Please follow the instructions below for more information.

The build lifecycle

We recommend using the following lifecycle phases:
  1. pre-clean to check that there is not an existing Traffic Parrot instance running using the trafficparrot:check-environment goal
  2. pre-integration-test to start Traffic Parrot using trafficparrot:start goal
  3. integration-test to run tests that rely on Traffic Parrot using the failsafe:integration-test goal
  4. post-integration-test to stop Traffic Parrot using the trafficparrot:stop goal
We recommend using the following Maven Failsafe Plugin goals to execute your tests: 
<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>

Changes to your pom.xml

To use the plugin, you will need to make changes similar to the following in your pom.xml file: 
<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:
  1. Update the version of the trafficparrot-maven-plugin to match the version you wish to use. Usually this should match the Traffic Parrot release version number.
  2. Set the value of the acceptLicense property in the pom.xml to true to indicate that you accept the Traffic Parrot license terms. You can find a copy in the examples project.
  3. Set the value of the downloadFrom property in the pom.xml to the URL of the Traffic Parrot release you would like to use. We are able to host a stable https:// link for our clients if you do not want to host the artifact internally.
  4. Set the value of the licenseFile property in the pom.xml to the file:/// that points to your license file.
  5. Add entries in the additionalJarFiles field in the pom.xml for any additional JAR files that you would usually place in the lib/external directory of Traffic Parrot.
  6. Ensure you have connectivity to https://trafficparrot.com/repository

HTTP replay

To replay HTTP traffic:
  1. Place the HTTP mappings in the src/test/resources/trafficparrot/mappings directory of your project
  2. Set the value of the httpVirtualServicePort property in the pom.xml to the port number your tests will use to connect to the virtual service over HTTP
  3. Set the value of the httpsVirtualServicePort property in the pom.xml to the port number your tests will use to connect to the virtual service over HTTPS
  4. The mappings will be replayed by Traffic Parrot during the integration-test phase

HTTP import

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:
  1. Place the Swagger/OpenAPI/RAML files in the src/test/resources/trafficparrot/http-import directory of your project
  2. Set the value of the httpVirtualServicePort property in the pom.xml to the port number your tests will use to connect to the virtual service over HTTP
  3. Set the value of the httpsVirtualServicePort property in the pom.xml to the port number your tests will use to connect to the virtual service over HTTPS
  4. Set the value of the httpImportMappings property in the pom.xml to true
  5. Mappings will generated based on the specification and replayed by Traffic Parrot during the integration-test phase

JMS queue replay

To replay JMS queue traffic using an internal broker:
  1. Place the JMS queue mappings in the src/test/resources/trafficparrot/jms-mappings directory
  2. Set the value of the jmsReplayQueue property in the pom.xml to be true
  3. Set the value of the jmsBrokerType property in the pom.xml to be INTERNAL
  4. Set the value of the jmsInternalBrokerPort property in the pom.xml to the port number your tests will use to connect to the internal broker
  5. Set the value of the jmsQueueConsumeRequestsFromConnectionId property in the pom.xml to USE-TRAFFIC-PARROT-INTERNAL-BROKER
  6. Set the value of the jmsQueueReplayResponsesToConnectionId property in the pom.xml to USE-TRAFFIC-PARROT-INTERNAL-BROKER
  7. The mappings will be replayed by Traffic Parrot during the integration-test phase
To replay JMS queue traffic using an external broker:
  1. Define JMS connections that will be used for replay in the src/test/resources/trafficparrot/jms-connections.json file
  2. Place the JMS queue mappings in the src/test/resources/trafficparrot/jms-mappings directory
  3. Set the value of the jmsConnectionsFile property in the pom.xml to be file:///${project.build.testOutputDirectory}/trafficparrot/jms-connections.json
  4. Set the value of the jmsReplayQueue property in the pom.xml to be true
  5. Set the value of the jmsBrokerType property in the pom.xml to be EXTERNAL
  6. Set the value of the jmsQueueConsumeRequestsFromConnectionId property in the pom.xml to the connection id of the broker to consume request messages from.
  7. Set the value of the jmsQueueReplayResponsesToConnectionId property in the pom.xml to the connection id of the broker to replay response messages to.
  8. The mappings will be replayed by Traffic Parrot during the integration-test phase

JMS topic replay

To replay JMS topic traffic using an internal broker:
  1. Place the JMS topic mappings in the src/test/resources/trafficparrot/jms-mappings directory
  2. Set the value of the jmsReplayTopic property in the pom.xml to be true
  3. Set the value of the jmsBrokerType property in the pom.xml to be INTERNAL
  4. Set the value of the jmsInternalBrokerPort property in the pom.xml to the port number your tests will use to connect to the internal broker
  5. Set the value of the jmsTopicReplayToConnectionId property in the pom.xml to USE-TRAFFIC-PARROT-INTERNAL-BROKER
  6. The mappings will be replayed by Traffic Parrot during the integration-test phase
To replay JMS topic traffic using an external broker:
  1. Define JMS connections that will be used for replay in the src/test/resources/trafficparrot/jms-connections.json file
  2. Place the JMS topic mappings in the src/test/resources/trafficparrot/jms-mappings directory
  3. Set the value of the jmsConnectionsFile property in the pom.xml to be file:///${project.build.testOutputDirectory}/trafficparrot/jms-connections.json
  4. Set the value of the jmsReplayTopic property in the pom.xml to be true
  5. Set the value of the jmsBrokerType property in the pom.xml to be EXTERNAL
  6. Set the value of the jmsTopicReplayToConnectionId property in the pom.xml to the connection id of the broker that will be used for replay.
  7. The mappings will be replayed by Traffic Parrot during the integration-test phase
To replay IBM® MQ queue traffic using an external broker:
  1. Define IBM® MQ connections that will be used for replay in the src/test/resources/trafficparrot/ibm-mq-connections.json file
  2. Place the IBM® MQ queue mappings in the src/test/resources/trafficparrot/ibm-mq-mappings directory
  3. Define additionalJarFiles in the pom.xml that point to the required JAR files.
  4. Set the value of the ibmMqConnectionsFile property in the pom.xml to be file:///${project.build.testOutputDirectory}/trafficparrot/ibm-mq-connections.json
  5. Set the value of the ibmMqReplayQueue property in the pom.xml to be true
  6. Set the value of the ibmMqBrokerType property in the pom.xml to be EXTERNAL
  7. Set the value of the ibmMqQueueConsumeRequestsFromConnectionId property in the pom.xml to the connection id of the broker to consume request messages from.
  8. Set the value of the ibmMqQueueReplayResponsesToConnectionId property in the pom.xml to the connection id of the broker to replay response messages to.
  9. The mappings will be replayed by Traffic Parrot during the integration-test phase
Replaying IBM® MQ queue traffic using an internal broker is not yet supported, please contact us at support@trafficparrot.com to be notified of when this functionality will be ready.

IBM® MQ topic replay

To replay IBM® MQ topic traffic using an external broker:
  1. Define IBM® MQ connections that will be used for replay in the src/test/resources/trafficparrot/ibm-mq-connections.json file
  2. Define additionalJarFiles in the pom.xml that point to the required JAR files.
  3. Place the IBM® MQ topic mappings in the src/test/resources/trafficparrot/ibm-mq-mappings directory
  4. Set the value of the ibmMqConnectionsFile property in the pom.xml to be file:///${project.build.testOutputDirectory}/trafficparrot/ibm-mq-connections.json
  5. Set the value of the ibmMqReplayTopic property in the pom.xml to be true
  6. Set the value of the ibmMqBrokerType property in the pom.xml to be EXTERNAL
  7. Set the value of the ibmMqTopicReplayToConnectionId property in the pom.xml to the connection id of the broker that will be used for replay.
  8. The mappings will be replayed by Traffic Parrot during the integration-test phase
Replaying IBM® MQ topic traffic using an internal broker is not yet supported, please contact us at support@trafficparrot.com to be notified of when this functionality will be ready.

Running from Gradle

First, download the examples project which will help you get started. Please follow the instructions below for more information.

The build lifecycle

The Traffic Parrot Gradle plugin has two tasks startTrafficParrot and stopTrafficParrot that you can use. We recommend using the following tasks as part of your build:
  1. clean to delete the files in the build directory
  2. startTrafficParrot to start Traffic Parrot
  3. test to run tests that rely on Traffic Parrot
  4. stopTrafficParrot to stop Traffic Parrot

Changes to your project configuration

You will need the following changes to your settings.gradle file: 
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:
  1. Update the version of the com.trafficparrot plugin to match the version you wish to use. Usually this should match the Traffic Parrot release version number.
  2. Set the value of the acceptLicense property in the build.gradle.kts to true to indicate that you accept the Traffic Parrot license terms. You can find a copy in the examples project.
  3. Set the value of the downloadFrom property in the build.gradle.kts to the URL of the Traffic Parrot release you would like to use.
  4. Set the value of the licenseFile property in the build.gradle.kts to the file(project.projectDir.absolutePath + "/trafficparrot.license").toURL() that points to your license file.
  5. Ensure you have connectivity to https://trafficparrot.com/repository

HTTP replay

To replay HTTP traffic:
  1. Place the HTTP mappings in the src/test/resources/trafficparrot/mappings directory of your project
  2. Set the value of the httpVirtualServicePort property in the build.gradle.kts to the port number your tests will use to connect to the virtual service over HTTP
  3. Set the value of the httpsVirtualServicePort property in the build.gradle.kts to the port number your tests will use to connect to the virtual service over HTTPS
  4. The mappings will be replayed by Traffic Parrot once it has been started with the startTrafficParrot task

HTTP import

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:
  1. Place the Swagger/OpenAPI/RAML files in the src/test/resources/trafficparrot/http-import directory of your project
  2. Set the value of the httpVirtualServicePort property in the build.gradle.kts to the port number your tests will use to connect to the virtual service over HTTP
  3. Set the value of the httpsVirtualServicePort property in the build.gradle.kts to the port number your tests will use to connect to the virtual service over HTTPS
  4. Set the value of the httpImportMappings property in the build.gradle.kts to true
  5. Mappings will generated based on the specification and replayed by Traffic Parrot once it has been started with the startTrafficParrot task

JMS queue replay

To replay JMS queue traffic using an internal broker:
  1. Place the JMS queue mappings in the src/test/resources/trafficparrot/jms-mappings directory
  2. Set the value of the jmsReplayQueue property in the build.gradle.kts to be true
  3. Set the value of the jmsBrokerType property in the build.gradle.kts to be INTERNAL
  4. Set the value of the jmsInternalBrokerPort property in the build.gradle.kts to the port number your tests will use to connect to the internal broker
  5. Set the value of the jmsQueueConsumeRequestsFromConnectionId property in the build.gradle.kts to USE-TRAFFIC-PARROT-INTERNAL-BROKER
  6. Set the value of the jmsQueueReplayResponsesToConnectionId property in the build.gradle.kts to USE-TRAFFIC-PARROT-INTERNAL-BROKER
  7. The mappings will be replayed by Traffic Parrot once it has been started with the startTrafficParrot task
To replay JMS queue traffic using an external broker:
  1. Define JMS connections that will be used for replay in the src/test/resources/trafficparrot/jms-connections.json file
  2. Place the JMS queue mappings in the src/test/resources/trafficparrot/jms-mappings directory
  3. Set the value of the jmsConnectionsFile property in the build.gradle.kts to be file(project.projectDir.absolutePath + "/src/test/resources/trafficparrot/jms-connections.json").toURL()
  4. Set the value of the jmsReplayQueue property in the build.gradle.kts to be true
  5. Set the value of the jmsBrokerType property in the build.gradle.kts to be EXTERNAL
  6. Set the value of the jmsQueueConsumeRequestsFromConnectionId property in the build.gradle.kts to the connection id of the broker to consume request messages from.
  7. Set the value of the jmsQueueReplayResponsesToConnectionId property in the build.gradle.kts to the connection id of the broker to replay response messages to.
  8. The mappings will be replayed by Traffic Parrot once it has been started with the startTrafficParrot task

JMS topic replay

To replay JMS topic traffic using an internal broker:
  1. Place the JMS topic mappings in the src/test/resources/trafficparrot/jms-mappings directory
  2. Set the value of the jmsReplayTopic property in the build.gradle.kts to be true
  3. Set the value of the jmsBrokerType property in the build.gradle.kts to be INTERNAL
  4. Set the value of the jmsInternalBrokerPort property in the build.gradle.kts to the port number your tests will use to connect to the internal broker
  5. Set the value of the jmsTopicReplayToConnectionId property in the build.gradle.kts to USE-TRAFFIC-PARROT-INTERNAL-BROKER
  6. The mappings will be replayed by Traffic Parrot once it has been started with the startTrafficParrot task
To replay JMS topic traffic using an external broker:
  1. Define JMS connections that will be used for replay in the src/test/resources/trafficparrot/jms-connections.json file
  2. Place the JMS topic mappings in the src/test/resources/trafficparrot/jms-mappings directory
  3. Set the value of the jmsConnectionsFile property in the build.gradle.kts to be file(project.projectDir.absolutePath + "/src/test/resources/trafficparrot/jms-connections.json").toURL()
  4. Set the value of the jmsReplayTopic property in the build.gradle.kts to be true
  5. Set the value of the jmsBrokerType property in the build.gradle.kts to be EXTERNAL
  6. Set the value of the jmsTopicReplayToConnectionId property in the build.gradle.kts to the connection id of the broker that will be used for replay.
  7. The mappings will be replayed by Traffic Parrot once it has been started with the startTrafficParrot task

Running in Docker

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:

  1. Copy trafficparrot-x.y.z-bin.zip to the current directory
    • We recommend to use the bundled JRE distribution we provide per OS, which means you do not need a base image with Java installed. Linux is typically used for Docker.
    • The examples below show how to use a Java base image, in case you are using the no-JRE bundle
  2. Save the following file as Dockerfile. These are only example files, to help get you started, but you can modify them to suit your needs.
    Eclipse Temurin OpenJDK base image example
    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"]
    Alpine base image example
    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"]
  3. Build the image, for example: 
    docker build -t trafficparrot .
  4. Run the container, for example: 
    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
  5. Wait for the container to start, for example: 
    until docker logs trafficparrot | grep "Started Traffic Parrot"; do sleep 1; done
  6. Open http://127.0.0.1:8080 in a web browser to view the Traffic Parrot UI
  7. Stop the container, for example: 
    docker stop trafficparrot
  8. View the container logs, for example: 
    docker logs trafficparrot
  9. Remove the container, for example: 
    docker rm -v trafficparrot

Please be aware of these important points when running Traffic Parrot in Docker:

  • DO prefer to use the bundled JRE distribution we provide per OS instead of the no-JRE bundle. This ensures Traffic Parrot runs with a Java version that has passed our compatibility tests.
  • DO expose ports for the protocols you require; you can check the trafficparrot.properties file for port numbers.
  • DO make sure you are using start-foreground.sh to ensure that Traffic Parrot is started as a foreground process that will correctly receive process termination signals such as SIGTERM when a docker stop command is issued.
  • DO stop the container using a docker stop command that will issue a SIGTERM signal, allowing graceful shutdown of Traffic Parrot. This will ensure the license seat that was in use is immediately available for use by new instances.
  • DO NOT use docker kill or docker rm -fv commands that will issue a SIGKILL signal, circumventing graceful shutdown of Traffic Parrot. This will result in the license seat that was in use remaining checked out until the timeout period has expired, which is typically set at 5 minutes for most customers.
  • DO see references
We highly recommend using the OpenJDK base JRE images which are well tested with Java. If you choose to use a custom base image, keep in mind these requirements:
  • bash is required for the start and stop scripts
  • java is required when using the no-JRE bundle, otherwise the bundled Java version will be used
  • glibc is a key library required by Java that is sometimes not included in small images e.g. Alpine Linux
How to copy mapping files from Docker to Git
When running in Docker, to commit mapping files edited via the UI to Git, there are a number of approaches possible:
  • You can use Docker volume mounts so the mappings are saved on your localhost file system or use Docker cp to extract files from the container
  • Or you can run outside of Docker locally when editing mappings so the filesystem is directly accessible
  • Or you can use Traffic Parrot APIs to view the JSON for the current mappings

Running in OpenShift

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.

Upgrading Traffic Parrot

You can use the upgrade script (upgrade.sh on Linux/Mac or upgrade.exe on Windows) to help you upgrade from a previous version to a new version:
  • First, unzip the new release, and you will find the upgrade script there
  • For example on Linux/Mac in a terminal: 
    ./upgrade.sh /path/to/previous-trafficparrot
  • For example on Windows at the command prompt: 
    upgrade.exe "C:\path\to\previous-trafficparrot"
  • Your configuration changes from the previous installation will be merged into the new installation
  • (optional) Additional arguments can be used with the upgrade script:
    • --replace-existing will automatically replace the previous installation with the new installation, and backup the previous installation into a new folder
    • --interactive will prompt for user input to decide whether to stop the old instance and start the new instance
    • --automatic-stop will automatically stop a previously running instance before upgrading
    • --automatic-start will automatically start the new instance after upgrading

License Server

For details on how to use Traffic Parrot with an on premise license server have a look at the Traffic Parrot License Server documentation.

Monitoring via JMX

Enabling JMX connectors

You can use JMX to monitor Traffic Parrot, for example by using JConsole.

The JMX connectors are disabled by default. In order to enable them you need to set the following properties:
  • trafficparrot.gui.jmx.enabled=true
  • trafficparrot.virtualservice.jmx.enabled=true

Typical environments

Manual exploratory testing QA and development working in isolation

If you cannot see a video frame below please download it here
 

Starting with automated testing

If you cannot see a video frame below please download it here
 

Continuous Delivery team sharing stubs or virtual services

If you cannot see a video frame below please download it here
 

Proof of concept with on-premises installation at a large enterprise

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.

Stage 0: a 1-hour installation plan

After completing this first step, you will have a Traffic Parrot installation ready to virtualize assets. This step is usually combined with Stage 1.

Prerequisites:
  1. Access to the Traffic Parrot installation files
  2. Access to the server where Traffic Parrot will be installed
  3. Correct Java version installed on the server
  4. Access to a user account able to bind ports on the server
  5. Access to a modern web browser
  6. An SSH client
Steps to perform:
  1. Copy the provided trafficparrot-x.y.z-bin.zip to the destination directory
  2. Unzip trafficparrot-x.y.z-bin.zip
  3. Start Traffic Parrot
  4. Access http://server-address:8080
  5. Stop Traffic Parrot

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.

Stage 1: a one to five day proof of concept

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.

Prerequisites:
  1. Completed the 1 hour installation plan
  2. Identified a test plan to virtualize
    1. Only stateless transactions
    2. Causing much pain because of system unavailability, third party transaction costs, etc. Virtualizing these services will help prove value faster and will less effort.
  3. Access from SUT server to the Traffic Parrot server (unblocked firewalls, etc.)
  4. Access from Traffic Parrot server to the virtualized system
  5. Access to the SUT application configuration files
  6. Team
    1. A small 2-5 people team for pilot deployment of Traffic Parrot
    2. A team member able to configure SUT to point to Traffic Parrot available for the day
Potential blockages to successful implementation of Stage 1:
  1. Not able to Download Traffic Parrot binaries inside the organization. Downloads are often blocked.
  2. Test plan/suite issues
    1. No stateless HTTP(S) transactions.
    2. No simple transactions that would demonstrate high ROI after virtualizing.
    3. No small team to lead the pilot project
    4. No team member available to help with SUT configuration.
  3. No access to a modern web browser.
Potential blockages to successful implementation of Stage 1 on the System Under Test server:
  1. No SSH access to the application server. This type of access often requires prior setup.
  2. No user with HDD write and port binding access on the SUT server. This type of access often requires prior setup.
  3. No RAM and HDD space available on the application server. Often servers come with limited resources.
  4. No Java installation on SUT server. Downloads are often blocked.
Potential blockages to successful implementation of Stage 1 on a dedicated server or cloud:
  1. No SSH access to the Traffic Parrot server. This type of access often requires prior setup.
  2. No user with HDD write and port binding access on the Traffic Parrot server. This type of access often requires prior setup.
  3. No RAM and HDD space available on the Traffic Parrot. Often servers come with limited resources.
  4. No Java installation on Traffic Parrot server. Downloads are often blocked.
  5. No firewall routes from SUT server to Traffic Parrot server.

Stage 2: enable the team in 4 weeks

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.

Next steps

Introducing Traffic Parrot to other teams. Showcasing the successful implementation in the first team. Repeat steps 0-2 for other teams.

Dynamic responses and custom extensions

Have a look at available custom extensions and how to generate responses dynamically

Old version warning!

This documentation is for an old version of Traffic Parrot. There is a more recent Traffic Parrot version available for download at trafficparrot.com

Browse documentation for recent version