# Traffic Parrot trial onboarding

> Onboarding notes for an agent driving a fresh Traffic Parrot trial install: how to start
> Traffic Parrot, and how to create a first stub for each supported protocol.
> This file complements https://trafficparrot.com/llms.txt and does not replace it. Read
> llms.txt for what Traffic Parrot is, which protocols it supports, how to answer questions
> about it, and where the full documentation lives. Read this file when Traffic Parrot has
> been downloaded and extracted but is not yet running, or when no stub exists yet.

Paths below are written as `trafficparrot-x.y.z`, which is the directory the archive extracts
to. Substitute the version that was actually downloaded. Everything here is taken from the
published Traffic Parrot documentation; the pages are linked at the end of this file.

## Ports

Traffic Parrot separates the web console from the simulators it runs. These are different
ports and they are not interchangeable.

- Web console, and the admin and management APIs: http://localhost:8080
- HTTP mocks, the virtual service a system under test calls: http://localhost:8081
- HTTPS mocks: 8082
- gRPC mocks: 5551 with TLS, 5552 without TLS
- Thrift mocks: 5562

The web console port is `trafficparrot.gui.http.port` and the HTTP mock port is
`trafficparrot.virtualservice.http.port`. Both, and the gRPC ports, are settings in
`trafficparrot.properties` in the main Traffic Parrot directory.

## Starting Traffic Parrot on Linux, Unix and Mac

1. Open a terminal window
2. Go to the installation directory: `cd trafficparrot-x.y.z`
3. Run the 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

To stop it, open a terminal window, `cd trafficparrot-x.y.z` and run `./stop.sh`.

## Starting Traffic Parrot on Windows

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

There are several ways of stopping it, and any of them will do: press Ctrl+C in the Command
Prompt running Traffic Parrot; or open a new Command Prompt, `cd trafficparrot-x.y.z` and run
`stop.cmd` or `stop.exe`; or click the system tray icon and click quit.

## Startup options and the licence

The install root holds `start.sh`, `start.cmd`, `stop.sh` and `trafficparrot.properties`.

Arguments passed to the start script override properties defined in `trafficparrot.properties`.
For example, on Linux:

    ./start.sh trafficparrot.gui.http.port=20000 trafficparrot.virtualservice.http.port=20001

and on Windows:

    start.cmd trafficparrot.gui.http.port=20000 trafficparrot.virtualservice.http.port=20001

To configure how long the start scripts wait for Traffic Parrot to start up, set the
`TP_STARTUP_WAIT_MILLIS` environment variable, for example `export TP_STARTUP_WAIT_MILLIS=180000`
before running `./start.sh`.

By default Traffic Parrot reads its licence from a `trafficparrot.license` file on the classpath,
typically placed in the installation directory. It can instead be supplied through the
`TRAFFICPARROT_LICENSE` environment variable, which takes the base64-encoded contents of that
file (`base64 -w0 trafficparrot.license`); this is the better fit for containers, where the value
can be injected at runtime from a secret. If the environment variable is not set, the file on the
classpath is used.

## Creating a first stub

Every protocol has an Add/Edit page in the web console, reached from the top navigation bar, and
that page is the primary way to create a stub. The sections below give the shortest path to one
working stub per protocol, including the configuration each protocol needs first. Message-based
protocols additionally need replay turned on before Traffic Parrot will consume request messages.

Mappings for the default scenario are stored on the filesystem under the directory named by the
`trafficparrot.virtualservice.trafficFilesRootUrl` property, for example the `mappings` and
`__files` directories used by HTTP. Other scenarios live under a `scenarios` directory beneath
the same root, such as `scenarios/Example/mappings` and `scenarios/Example/__files`.

## First stub: HTTP(S)

1. Open the web console at http://localhost:8080
2. Go to HTTP in the top navigation bar and then click Add/Edit
3. Fill in the Request fields (URL match type, method, headers, priority, body) and the Response
   fields (status code, headers, body), then click Save to configure a mapping. Selecting an entry
   from the HTTP skeleton dropdown pre-fills the Request/Response fields for that skeleton
4. After saving, the mapping appears in the list of mappings
5. Call the stub on the HTTP mock port, for example: `curl http://localhost:8081/greeting`

HTTP mappings can also be written to disk instead. This example creates a stub for
`GET /greeting` whose response body comes from a file. Create `__files/body.txt` holding
`Hello from a file-backed response!`, and `mappings/greeting.json`:

    {
      "request": {
        "method": "GET",
        "url": "/greeting"
      },
      "response": {
        "status": 200,
        "bodyFileName": "body.txt",
        "headers": {
          "Content-Type": "text/plain"
        }
      }
    }

If Traffic Parrot is already running the mapping is picked up automatically. As llms.txt says,
a generated mapping JSON file should also carry an "id" field with a random UUID.

## First stub: gRPC

Traffic Parrot needs to know the schema of the messages before a gRPC mapping can be created.

1. Copy your `.proto` files (proto3) into the `trafficparrot-x.y.z/proto` directory. Precompiled
   descriptors go into `trafficparrot-x.y.z/proto-bin` instead, with extension `.bin` for a single
   proto file or `.set.bin` for a set. Proto files, `.zip` archives of them, and `.desc` or
   `.protoset` descriptor sets can also be uploaded through the "Import skeleton..." button on the
   gRPC page, with no file copying
2. Go to gRPC in the top navigation bar and click Add/Edit
3. Select the name of a gRPC method from the message skeleton dropdown, and a sample request and
   response value is generated holding the default values for the message. Traffic Parrot
   represents gRPC protocol buffer payloads as JSON, so the request and response bodies are edited
   as JSON, and the edits must stay compatible with the underlying proto message schema
4. Fill in the Request/Response fields and click Save to configure a mapping
5. Point the client at the virtual service gRPC server, which is `localhost:5552` without TLS by
   default, or port 5551 with TLS

gRPC mappings are saved as JSON files in the `grpc-mappings` directory. A mapping names its
operation in `request.urlPath`, in the form `example.ExampleService/ExampleOperation`, and a
successful response carries `response.status` 0.

## First stub: IBM MQ

Native IBM MQ replays against a broker, so a connection is needed before a mapping can be used.

1. Open `ibm-mq-connections.json` in the main Traffic Parrot directory and add a connection,
   making sure the `connectionId` field has a unique value. Supported `ibmMqVersion` values are
   `IBM_MQ_7_5`, `IBM_MQ_8` and `IBM_MQ_9`
2. Add the queues that will be used by the virtual service to the broker. Depending on the broker
   and its configuration these may be auto-created when Traffic Parrot first connects
3. Go to IBM MQ > Add/Edit in the web console
4. Set the destination name, the destination type (the Queue / Topic radio) and the request
   body/payload, then the response destination and body. Press "Save" to save the request to
   responses mapping
5. Go to the IBM MQ replay page at http://localhost:8080/ibmMq/replay.html, select "External" in
   the "Broker" panel, select "Queue", de-select "Topic", choose the connections and click
   "Turn on". Click "Turn off" when finished
6. Point the system under test at the virtual service broker and execute a test case, so Traffic
   Parrot consumes a request message and sends a response message

Supported MQ message formats are `MQFMT_STRING`, `MQFMT_NONE`, `MQFMT_RF_HEADER_1` and
`MQFMT_RF_HEADER_2`.

## First stub: JMS, including ActiveMQ, RabbitMQ and IBM MQ over JMS

RabbitMQ is mocked through JMS rather than through a page of its own. The supported JMS brokers
are ActiveMQ TCP (internal or external broker), ActiveMQ AMQP 1.0 (internal or external broker),
Azure AMQP 1.0 (external broker), RabbitMQ AMQP 0.9.1 (external broker) and IBM WebSphere MQ 7.5+
(external broker).

The quickest first stub uses the internal broker, which needs no external infrastructure: the
"Internal broker" connection is available in the connection dropdown by default once an internal
broker is chosen in the Broker panel.

1. For an external broker, open `jms-connections.json` in the main Traffic Parrot directory and
   add a connection, making sure the `connectionId` field has a unique value. The internal broker
   needs no entry
2. Go to JMS > Add/Edit in the web console
3. Set the destination name, the destination type (the Queue / Topic radio) and the request
   body/payload, and on the response side the reply destination and the reply body. Click Save
4. Go to the JMS replay page at http://localhost:8080/jms/replay.html, select "Internal" in the
   "Broker" panel, select "Queue", choose the jms connection to broker "Internal broker" and click
   "Turn on". Click "Turn off" when finished
5. Reconfigure the system under test to connect to the virtual service broker and execute a test
   case, so Traffic Parrot consumes a request message and sends a response message

Supported JMS message types are `javax.jms.TextMessage` and `javax.jms.BytesMessage`.

## First stub: File Transfer

The file virtual service reads request files from a request directory and writes response files
to a response directory. Three drivers share the same mapping format, UI and record/replay
behaviour: Local File System, SFTP and FTP.

1. Configure a connection in `root-directories.json` in the main Traffic Parrot directory. For the
   Local File System driver set `driver` to `LOCAL_FILE_SYSTEM` (the default if the field is
   omitted) and `rootDirectory` to an absolute path on disk. Every directory configured when
   adding a mapping is relative to that root directory, or to the remote base path for SFTP and FTP
2. Go to Files in the top navigation bar and then click Add/Edit
3. Fill in the Request fields, which select the request files to match (for example a request file
   name matcher such as `equalTo`, `contains` or `matches`), and the Response fields, which define
   the response file and its body, then click Save to configure a mapping
4. Start replay. The Traffic Parrot OpenAPI specification publishes this as a POST to
   `/fileMessage/replay` on the web console port:

        curl -X POST http://localhost:8080/fileMessage/replay \
          -H "Content-Type: application/json" \
          -d '{"action":"START","directories":{"consumeRequestsFromRootDirectoryId":"virtual-root","replayResponsesToRootDirectoryId":"virtual-root"}}'

   The root directory ids refer to directories defined in `root-directories.json`. Send
   `{"action":"STOP"}` to stop replay
5. Put a request file in the request directory. Traffic Parrot goes through the request to response
   mappings to decide the name and content of the response file, and creates it in the specified
   directory

## First stub: Thrift

Thrift support needs a JDK rather than a JRE, the Thrift binary, and your Thrift files.

1. Copy the Thrift binary (`thrift` on Linux and Mac, `thrift.exe` on Windows) into the `plugins`
   directory of Traffic Parrot. The system path is searched for the binary as well
2. Copy your `.thrift` files into the `trafficparrot-x.y.z/thrift` directory
3. On startup, `trafficparrot.log` records whether support came up, for example "Thrift support
   enabled since there is a Java compiler and Thrift binary available." followed by the services it
   compiled. A missing binary, or a JRE in place of a JDK, is reported there as a WARN and leaves
   Thrift support disabled
4. Go to Thrift in the top navigation bar and click Add/Edit. Traffic Parrot represents Thrift
   payloads as JSON, so the request and response bodies are edited as JSON, and the edits must stay
   compatible with the underlying Thrift message schema
5. Fill in the Request/Response fields and click Save to configure a mapping
6. Point the system under test at the virtual service Thrift server, which is `localhost:5562` by
   default. Traffic Parrot replays mappings whenever it is not in record mode

## Where the details are

- [llms.txt](https://trafficparrot.com/llms.txt):
  What Traffic Parrot is, the protocols it supports, where the documentation lives, and the
  guidance to follow when answering questions about creating mocks
- [User guide](https://trafficparrot.com/documentation/latest/user_guide.html#start-and-stop):
  Starting and stopping, passing values to the start script, startup config, scenarios, supplying
  the licence, logging
- [Properties](https://trafficparrot.com/documentation/latest/properties.html):
  Every `trafficparrot.properties` setting and its default, including all the ports above
- [HTTP(S)](https://trafficparrot.com/documentation/latest/http.html#add-edit-http-mappings):
  Add/Edit HTTP mappings, skeletons, query parameters, proxying, webhooks, import and export
- [gRPC](https://trafficparrot.com/documentation/latest/grpc.html#configure-proto):
  Proto and descriptor configuration, server reflection, Add/Edit gRPC mappings, mapping JSON
- [IBM MQ](https://trafficparrot.com/documentation/latest/ibmmq.html#define-connections):
  Connection configuration, record and replay, Edit IBM MQ mappings, messaging skeletons
- [JMS](https://trafficparrot.com/documentation/latest/jms.html#define-jms-connections):
  Broker support, connection configuration, internal and external broker record and replay,
  Edit JMS mappings
- [File Transfer](https://trafficparrot.com/documentation/latest/filemessage.html#file-connections):
  Local File System, SFTP and FTP drivers, Add/Edit mappings, request file matchers
- [Thrift](https://trafficparrot.com/documentation/latest/thrift.html#configure-thrift):
  Thrift binary and Thrift file configuration, record and replay, Add/Edit Thrift mappings
- [Request matching](https://trafficparrot.com/documentation/latest/request_matching.html):
  Matching rules and patterns shared across protocols
- [Dynamic responses](https://trafficparrot.com/documentation/latest/dynamic.html):
  Handlebars helpers, response transformers, JavaScript scripts, custom-code SPI
- [OpenAPI specification](https://trafficparrot.com/documentation/latest/downloads/openapi.yaml):
  The management and admin APIs served on the web console port, including record and replay
- [Free trial](https://trafficparrot.com/trial.html):
  Where the trial download comes from, if Traffic Parrot is not on disk yet