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. 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. Open a Command Prompt. Click Start, type cmd in the "Search programs and files" box or type cmd in Cortana prompt.
  2. Go to the installation directory cd trafficparrot-release-x.y.z
  3. Run start script start.cmd
  4. Inspect the console output and make sure there are no “ERROR”s
  5. Open the web console in any modern web browser (Chrome, Firefox or MS Edge) http://localhost:8080
Stop
  1. Press Ctrl+C in the Command Prompt
  2. Close the Command Prompt

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

Where is the Maven plugin?

An official Traffic Parrot maven plugin in on our road-map for development, please email support@trafficparrot.com to be notified when it is available. In the meantime we suggest using the approach outlined below.

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

Please note that this approach does not currently support Windows environments!

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

You will need to make the following changes to your pom.xml file:
  1. Add the required properties:
    <properties>
        <!-- Traffic Parrot internal properties -->
        <trafficparrot.script.extension>sh</trafficparrot.script.extension>
        <trafficparrot.start.script>${trafficparrot.installation.directory}${file.separator}start.${trafficparrot.script.extension}</trafficparrot.start.script>
        <trafficparrot.stop.script>${trafficparrot.installation.directory}${file.separator}stop.${trafficparrot.script.extension}</trafficparrot.stop.script>
        <trafficparrot.start.out>${trafficparrot.installation.directory}${file.separator}tp.out</trafficparrot.start.out>
        <skipTests>false</skipTests>
    
        <!-- Traffic Parrot configuration -->
        <trafficparrot.installation.directory>/tmp/${trafficparrot.release.file.prefix}</trafficparrot.installation.directory>
        <trafficparrot.virtualservice.jms.broker.type>INTERNAL</trafficparrot.virtualservice.jms.broker.type>
        <trafficparrot.virtualservice.jms.broker.provider>ACTIVE_MQ</trafficparrot.virtualservice.jms.broker.provider>
        <trafficparrot.virtualservice.jms.broker.port>19091</trafficparrot.virtualservice.jms.broker.port>
        <trafficparrot.virtualservice.jms.queue.consume.requests.from.connection.id>USE-TRAFFIC-PARROT-INTERNAL-BROKER</trafficparrot.virtualservice.jms.queue.consume.requests.from.connection.id>
        <trafficparrot.virtualservice.jms.queue.replay.responses.to.connection.id>USE-TRAFFIC-PARROT-INTERNAL-BROKER</trafficparrot.virtualservice.jms.queue.replay.responses.to.connection.id>
        <trafficparrot.virtualservice.jms.topic.replay.to.connection.id>USE-TRAFFIC-PARROT-INTERNAL-BROKER</trafficparrot.virtualservice.jms.topic.replay.to.connection.id>
        <trafficparrot.gui.http.port>18080</trafficparrot.gui.http.port>
        <trafficparrot.virtualservice.http.port>18081</trafficparrot.virtualservice.http.port>
        <trafficparrot.virtualservice.https.port>18082</trafficparrot.virtualservice.https.port>
    </properties>
  2. Change the value of the trafficparrot.installation.directory property to the directory that Traffic Parrot is installed in.
  3. You can also change the port numbers used in the remaining properties if they clash with ports already used on your system.
  4. Add the required plugin execution:
    <build>
        <plugins>
            <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>org.apache.maven.plugins</groupId>
                <artifactId>maven-antrun-plugin</artifactId>
                <version>1.8</version>
                <executions>
                    <!-- Recommended usage for clients -->
                    <execution>
                        <id>start-traffic-parrot</id>
                        <phase>pre-integration-test</phase>
                        <goals>
                            <goal>run</goal>
                        </goals>
                        <configuration>
                            <skip>${skipTests}</skip>
                            <target>
                                <taskdef resource="net/sf/antcontrib/antlib.xml" classpathref="maven.plugin.classpath" />
                                <delete>
                                    <fileset dir="${trafficparrot.installation.directory}">
                                        <include name="mappings/**"/>
                                        <include name="jms-mappings/**"/>
                                    </fileset>
                                </delete>
                                <copy todir="${trafficparrot.installation.directory}">
                                    <fileset dir="${project.basedir}/src/test/resources/trafficparrot">
                                        <include name="mappings/**"/>
                                        <include name="jms-mappings/**"/>
                                    </fileset>
                                </copy>
                                <delete file="${trafficparrot.start.out}" />
                                <exec executable="${trafficparrot.start.script}">
                                    <arg value="trafficparrot.gui.http.port=${trafficparrot.gui.http.port}"/>
                                    <arg value="trafficparrot.virtualservice.http.port=${trafficparrot.virtualservice.http.port}"/>
                                    <arg value="trafficparrot.virtualservice.https.port=${trafficparrot.virtualservice.https.port}"/>
                                </exec>
                                <loadfile property="tp.out.contents" srcFile="${trafficparrot.installation.directory}${file.separator}tp.out"/>
                                <echo>${tp.out.contents}</echo>
                                <post to="http://localhost:${trafficparrot.gui.http.port}/jms/replay.html"
                                      verbose="true" failonerror="true">
                                    <prop name="action" value="START"/>
    
                                    <prop name="broker.type" value="${trafficparrot.virtualservice.jms.broker.type}"/>
                                    <prop name="broker.internalProvider" value="${trafficparrot.virtualservice.jms.broker.provider}"/>
                                    <prop name="broker.internalPort" value="${trafficparrot.virtualservice.jms.broker.port}"/>
    
                                    <prop name="replay.replayQueue" value="true"/>
                                    <prop name="replay.queue.consumeRequestsFromConnectionId" value="${trafficparrot.virtualservice.jms.queue.consume.requests.from.connection.id}"/>
                                    <prop name="replay.queue.replayResponsesToConnectionId" value="${trafficparrot.virtualservice.jms.queue.replay.responses.to.connection.id}"/>
    
                                    <prop name="replay.replayTopic" value="true"/>
                                    <prop name="replay.topic.replayToConnectionId" value="${trafficparrot.virtualservice.jms.topic.replay.to.connection.id}"/>
                                </post>
                            </target>
                        </configuration>
                    </execution>
                    <execution>
                        <id>stop-traffic-parrot</id>
                        <phase>post-integration-test</phase>
                        <goals>
                            <goal>run</goal>
                        </goals>
                        <configuration>
                            <skip>${skipTests}</skip>
                            <target>
                                <exec executable="${trafficparrot.stop.script}"/>
                                <loadfile property="tp.out.contents" srcFile="${trafficparrot.installation.directory}${file.separator}tp.out"/>
                                <echo>${tp.out.contents}</echo>
                            </target>
                        </configuration>
                    </execution>
                </executions>
                <dependencies>
                    <dependency>
                        <groupId>ant-contrib</groupId>
                        <artifactId>ant-contrib</artifactId>
                        <version>1.0b3</version>
                        <exclusions>
                            <exclusion>
                                <groupId>ant</groupId>
                                <artifactId>ant</artifactId>
                            </exclusion>
                        </exclusions>
                    </dependency>
                </dependencies>
            </plugin>
    
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-enforcer-plugin</artifactId>
                <version>3.0.0-M1</version>
                <executions>
                    <execution>
                    <id>check-traffic-parrot-environment</id>
                    <phase>validate</phase>
                    <goals>
                        <goal>enforce</goal>
                    </goals>
                    <configuration>
                        <skip>${skipTests}</skip>
                        <rules>
                        <requireFilesExist>
                            <message>Unable to find Traffic Parrot at the specified installation directory: ${trafficparrot.installation.directory}</message>
                            <files>
                                <file>${trafficparrot.start.script}</file>
                                <file>${trafficparrot.stop.script}</file>
                            </files>
                        </requireFilesExist>
                        <requireOS>
                            <message>The examples project does not support Windows</message>
                            <family>unix</family>
                        </requireOS>
                        </rules>
                        <fail>true</fail>
                    </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

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 trafficparrot.virtualservice.http.port 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 trafficparrot.virtualservice.https.port 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 trafficparrot.virtualservice.jms.broker.type property in the pom.xml to be INTERNAL
  3. Set the value of the trafficparrot.virtualservice.jms.broker.port property in the pom.xml to the port number your tests will use to connect to the internal broker
  4. Set the value of trafficparrot.virtualservice.jms.queue.consume.requests.from.connection.id property in the pom.xml to USE-TRAFFIC-PARROT-INTERNAL-BROKER
  5. Set the value of trafficparrot.virtualservice.jms.queue.replay.responses.to.connection.id 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 queue traffic using an external broker:
  1. Define JMS connections that will be used for replay
  2. Place the JMS queue mappings in the src/test/resources/trafficparrot/jms-mappings directory
  3. Set the value of the trafficparrot.virtualservice.jms.broker.type property in the pom.xml to be EXTERNAL
  4. Set the value of trafficparrot.virtualservice.jms.queue.consume.requests.from.connection.id property in the pom.xml to the connection id of the broker to consume request messages from.
  5. Set the value of trafficparrot.virtualservice.jms.queue.replay.responses.to.connection.id property in the pom.xml to the connection id of the broker to replay response messages to.
  6. 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 trafficparrot.virtualservice.jms.broker.type property in the pom.xml to be INTERNAL
  3. Set the value of the trafficparrot.virtualservice.jms.broker.port property in the pom.xml to the port number your tests will use to connect to the internal broker
  4. Set the value of trafficparrot.virtualservice.jms.topic.replay.to.connection.id property in the pom.xml to USE-TRAFFIC-PARROT-INTERNAL-BROKER
  5. 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
  2. Place the JMS topic mappings in the src/test/resources/trafficparrot/jms-mappings directory
  3. Set the value of the trafficparrot.virtualservice.jms.broker.type property in the pom.xml to be EXTERNAL
  4. Set the value of trafficparrot.virtualservice.jms.topic.replay.to.connection.id property in the pom.xml to the connection id of the broker that will be used for replay
  5. The mappings will be replayed by Traffic Parrot during the integration-test phase

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.