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 (applicaiton under test) connects directly to the virtual service on different ports. For more details see HTTP architecture or JMS architecture.

HTTP

For details on HTTP service virtualization have a look at HTTP

JMS

For details on JMS service virtualization have a look at JMS

Starting and stopping

Linux, Unix and Mac

Start
  1. Open a terminal window
  2. Go to the installation directory cd trafficparrot-release-x.y.z
  3. Run start script ./start.sh
  4. (Optional) Inspect the main 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-release-x.y.z
  3. Run stop script ./stop.sh

Windows

Start
  1. Go to the installation directory trafficparrot-release-x.y.z
  2. Double click start.cmd 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 two 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 stop.cmd:
  1. Open a new Command Prompt.
  2. Go to the installation directory cd trafficparrot-release-x.y.z
  3. Run stop script stop.cmd

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.

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 Web UI trafficparrot.gui.http.port=18080
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
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
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
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
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

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

Logging

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

Running from Maven

Maven plugin

To start, should download the examples project which will help you get started. Also, please follow the instructions below.

The build lifecycle

We recommend using the following lifecycle phases:
  1. pre-integration-test to start Traffic Parrot
  2. integration-test to run tests that rely on Traffic Parrot
  3. post-integration-test to stop Traffic Parrot
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>3.10</version>
            <executions>
                <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>

                <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>plugin-repository</id>
        <releases>
            <checksumPolicy>ignore</checksumPolicy>
        </releases>
        <url>file://${project.basedir}/repo</url>
    </repository>
</repositories>
You will need to:
  1. 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.
  2. Set the value of the downloadFrom property in the pom.xml to the URL of the Traffic Parrot release you would like to use.
  3. Set the value of the licenseFile property in the pom.xml to the file:/// that points to your license file.
  4. 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.
  5. Ensure you have a local repo folder that contains the Traffic Parrot plugin. This is referenced by the repositories section of the pom.xml. See the examples project for more details.

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

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 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-enterprise-release-x.y.z-bin.zip to the current directory
  2. Save the following file as TrafficParrotDockerfile. This is only an example file, it should get you started, but you can modify it to suit your needs. 
    FROM openjdk:8u141-jre

WORKDIR /opt
COPY trafficparrot-*-release-*-bin.zip trafficparrot.zip
RUN unzip trafficparrot.zip && rm trafficparrot.zip && mv trafficparrot-*-release-* trafficparrot

WORKDIR /opt/trafficparrot
CMD ["./start-foreground.sh"]
  3. Build an image, for example: 
    docker build -t trafficparrot -f TrafficParrotDockerfile .
  4. Run a container, for example: 
    docker run -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. Open http://127.0.0.1:8080 in a web browser

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-release-x.y.z-bin.zip to the destination directory
  2. Unzip trafficparrot-release-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.

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