Start Traffic Parrot and work in its install directory. The ports below are the defaults: 8080 for management and 8081 for the HTTP virtual service.
Create mappings/hello.json:
{
"request": {
"method": "GET",
"urlPath": "/hello"
},
"response": {
"status": 200,
"body": "Hello from a file"
}
}
Call it:
curl -i http://localhost:8081/hello
HTTP/1.1 200 OK Vary: Origin Matched-Stub-Id: 0d2b8e97-9989-31af-aa1f-695144ab9b6e Matched-Stub-Name: hello.json Content-Length: 17 Hello from a file
Nothing was restarted or reloaded: the file was read when the request arrived. Matched-Stub-Name names the file that answered. The file layout says when a saved file takes effect for every kind of file.
A running instance serves a JSON schema for each mapping format, listed at http://localhost:8080/schemas/index.json. They ship inside Traffic Parrot, so they describe the version you run.
| Format | Directory | Schema, under http://localhost:8080 |
|---|---|---|
| HTTP | mappings/ | /schemas/http-mapping.schema.json |
| gRPC | grpc-mappings/ | /schemas/grpc-mapping.schema.json: the HTTP keys, with gRPC's urlPath, method and status |
| JMS | jms-mappings/ | /schemas/jms-mapping.schema.json |
| Native IBM MQ | ibm-mq-mappings/ | /schemas/ibm-mq-mapping.schema.json |
| File messages | file-mappings/ | /schemas/file-message-mapping.schema.json |
Make $schema the first key of a mapping file, with the
schema's address as its value:
{
"$schema": "http://localhost:8080/schemas/http-mapping.schema.json",
"request": {
"method": "GET",
"urlPath": "/hello"
},
"response": {
"status": 200,
"body": "Hello from a file"
}
}
An editor that reads JSON schemas then offers each key as you type, and marks a key the format does not have or a value of the wrong type. Traffic Parrot ignores the line when it loads the file.
$schema line
and needs nothing else. To cover a whole folder without the line in each
file, add the schema to .vscode/settings.json:
{
"json.schemas": [
{
"fileMatch": ["**/mappings/*.json"],
"url": "http://localhost:8080/schemas/http-mapping.schema.json"
}
]
}
To work with the instance stopped, save the schema in a folder of its own beside mappings/, and use that file's path in place of the address. Run this in the directory that holds mappings/:
curl --create-dirs -o schemas/http-mapping.schema.json http://localhost:8080/schemas/http-mapping.schema.json
Do not save it in mappings/ or a folder inside it: Traffic
Parrot reads every JSON file there as a mapping, and a schema is loaded as
one that matches any request. A request that none of your mappings matches
is then answered 200 with an empty body.
One thing to know if you also use the web UI: saving a mapping there
rewrites its file without the $schema line. The file name and
the id are kept.
A mapping you keep in git is easier to live with when it has a
name and an id of its own and its response body
in a file. Three files:
mappings/orders-open.json
{
"$schema": "http://localhost:8080/schemas/http-mapping.schema.json",
"id": "5c7e6e1a-3f0b-4d38-9d0e-0d7c4a1f2b10",
"name": "orders-open",
"request": {
"method": "GET",
"urlPath": "/orders",
"queryParameters": {
"status": {
"equalTo": "open"
}
}
},
"response": {
"status": 200,
"headers": {
"Content-Type": "application/json"
},
"bodyFileName": "orders-open.hbs"
}
}
__files/orders-open.hbs
{
"status": "{{request.query.status}}",
"orders": [
{ "id": "A-1001", "total": 42.50 }
],
{{> templates/page-footer}}
}
templates/page-footer.hbs
"servedBy": "Traffic Parrot", "path": "{{request.path}}"
curl -i "http://localhost:8081/orders?status=open"
HTTP/1.1 200 OK
Vary: Origin
Content-Type: application/json
Matched-Stub-Id: 5c7e6e1a-3f0b-4d38-9d0e-0d7c4a1f2b10
Matched-Stub-Name: orders-open
Content-Length: 133
{
"status": "open",
"orders": [
{ "id": "A-1001", "total": 42.50 }
],
"servedBy": "Traffic Parrot", "path": "/orders"
}
bodyFileName is a path under __files/. The
file is rendered as a
Handlebars template, as an inline
body is; neither needs a transformers entry.
name and the id come back in the
Matched-Stub-Name and Matched-Stub-Id response
headers, so a test or a log line can say which mapping answered. A
mapping with no name is reported under its file name, as
hello.json was above.
A running instance does not check a mapping file against its schema: a key it does not know is dropped without a word. The validate command does check, without starting a server, so it suits a commit hook or a CI step. Give it the directory that holds mappings/ and the other mapping directories:
./trafficparrot.sh validate /path/to/files-root
No mapping schema drift detected.
It exits 0 when every file matches and 1
otherwise, naming each file and key:
Some HTTP mappings do not match the HTTP mapping schema: (1) HTTP mapping 'mappings/dsl-name.json' does not match http-mapping.schema.json: /request: property 'urlEqualTo' is not defined in the schema and the schema does not allow additional properties; 'urlEqualTo' is the Java DSL name of a matcher, not a mapping key: write 'url'
The result follows a few logging warnings that start SLF4J or log4j, which you can ignore.
bodyFileName
naming a file that is not in __files.
The check is stricter than loading in a few more ways. It refuses some
values that Traffic Parrot accepts, such as an HTTP method the schema does
not list, or a priority below 1 in a JMS, native
IBM MQ or file message mapping. Those three kinds of mapping must also be
strict JSON: a comment or a single-quoted string, which Traffic Parrot reads
when it loads the file, is reported as not valid JSON. An HTTP mapping is
read as Traffic Parrot reads it, so a comment passes, and a file that holds
several mappings under a mappings key has each of them checked.
An editor that checks such a file against the HTTP schema reports it,
because the schema describes one mapping.
The CI example workspace is a small repository to copy from. It holds two HTTP mappings and a template under traffic-parrot/, one script, ci/run-traffic-parrot.sh, and a GitHub Actions workflow that runs the script on every push and pull request. The script runs the same way on a laptop:
TRAFFIC_PARROT_ZIP=/path/to/trafficparrot-release.zip ci/run-traffic-parrot.sh
1, before anything starts; warnings are
printed and pass.
1. A Docker run prints Traffic
Parrot's logs from the container first; a run from the zip leaves them in
the unzipped release, under target/traffic-parrot-ci/release/.
The script takes the release zip without a Java runtime and needs Java on the
PATH, with or without Docker, because it checks the files with
the release itself. TRAFFIC_PARROT_LICENSE_FILE names the
license file to use in place of the one in the zip, and
TRAFFIC_PARROT_HTTP_PORT and TRAFFIC_PARROT_GUI_PORT
move the ports from 8081 and 8080. The header of the
script lists the other settings. It exits 2 when it is not set
up: no zip, or no Java.
The workflow, .github/workflows/traffic-parrot.yml, runs the script twice, from the zip and in Docker. It reads two repository secrets: TRAFFIC_PARROT_ZIP_URL, where the job downloads your release zip from, and TRAFFIC_PARROT_LICENSE_BASE64, your license file base64-encoded. When the zip job fails, it keeps Traffic Parrot's logs as the traffic-parrot-logs-zip artifact.
Save the file. That is all the samples above did. With the shipped settings the next request reads it, and every file is read when Traffic Parrot starts. With the mapping cache turned on, a saved file waits for the reset call that the file layout names.
Post it to the Management API when a script should not
write into the install directory. With "persistent": true
Traffic Parrot writes the file for you. orders-closed.json:
{
"name": "orders-closed",
"persistent": true,
"request": {
"method": "GET",
"urlPath": "/orders",
"queryParameters": {
"status": {
"equalTo": "closed"
}
}
},
"response": {
"status": 200,
"body": "No closed orders"
}
}
curl -i -X POST http://localhost:8080/api/http/__admin/mappings \
-H "Content-Type: application/json" \
-d @orders-closed.json
The answer is 201 Created with the mapping and the
id it was given. mappings/orders-closed.json now
exists, named after the mapping's name, and the mapping
answers at once:
curl -i "http://localhost:8081/orders?status=closed"
HTTP/1.1 200 OK Vary: Origin Matched-Stub-Id: ce51cbd9-5c0e-4cf3-a23a-512f562fdd5a Matched-Stub-Name: orders-closed Content-Length: 16 No closed orders
Without "persistent": true the mapping is held in memory and
is gone when Traffic Parrot restarts. The id above is the one
this run was given; yours will differ unless the mapping sets one.
Put it in another virtual service. A folder scenarios/Orders/ with a mappings/ directory of its own is a virtual service named Orders, listed as soon as the folder exists. Select it:
curl -X PUT http://localhost:8080/api/scenarios/Orders \
-H "Content-Type: application/json" \
-d '{"enabled": true}'
With the shipped settings the default ports then answer from its files. Select Default in the same way to go back.
An HTTP request that no mapping matches is answered with status 900:
curl -i "http://localhost:8081/orders?status=shipped"
HTTP/1.1 900 900 Transfer-Encoding: chunked Traffic Parrot Virtual Service: No responses matched the given request
Three places say why.
curl http://localhost:8080/api/http/requests/unmatched/near-misses
curl http://localhost:8080/http/management/skippedMappingFiles
[ {
"skipped" : "mapping file /opt/trafficparrot/mappings/broken.json",
"reason" : "Unexpected character ('}' (code 125)): was expecting double-quote to start field name"
} ]
A gRPC call, a JMS or IBM MQ message, or a file that no mapping matches is listed on the Requests page of its protocol: gRPC, JMS, IBM MQ and files.
A gRPC mapping is served from a .proto file. proto/greeter.proto:
syntax = "proto3";
package example;
service Greeter {
rpc SayHello (HelloRequest) returns (HelloReply);
}
message HelloRequest {
string name = 1;
}
message HelloReply {
string message = 1;
}
grpc-mappings/say-hello.json:
{
"id": "0b6a3a52-7d0e-4f0c-8a55-3d2f1c9e4a21",
"name": "say-hello",
"request": {
"urlPath": "example.Greeter/SayHello",
"method": "ANY",
"headers": {
"Protocol": {
"equalTo": "GRPC"
}
},
"bodyPatterns": [
{
"matchesJsonPath": "$.name"
}
]
},
"response": {
"status": 0,
"jsonBody": {
"message": "Hello {{jsonPath request.body '$.name'}}"
}
}
}
Call example.Greeter/SayHello with
{"name": "Ada"} from your gRPC client, on port
5552 without TLS. The reply's message is
Hello Ada, with status OK.
urlPath is package.Service/Method, with no slash in front.status is the gRPC status code, and 0 is OK.
A messaging mapping has keys of its own: a destination for
the queue, a bodyMatcher for the request and
text for the reply. jms-mappings/order-status.json:
{
"$schema": "http://localhost:8080/schemas/jms-mapping.schema.json",
"mappingId": "9a1d2c3e-4b5f-4a6b-8c7d-0e1f2a3b4c5d",
"request": {
"destination": {
"name": "orders.request",
"type": "QUEUE"
},
"bodyMatcher": {
"contains": "status"
}
},
"response": {
"destination": {
"name": "orders.response",
"type": "QUEUE"
},
"text": "{\"status\": \"shipped\"}"
}
}
Messages are answered while replay runs. Start it on the web UI's JMS replay page, or with a call. replay.json, for the broker inside Traffic Parrot:
{
"action": "START",
"broker": {
"type": "INTERNAL",
"internalProvider": "ACTIVE_MQ",
"internalPort": 9091
},
"queue": {
"consumeRequestsFromConnectionId": "USE-TRAFFIC-PARROT-INTERNAL-BROKER",
"replayResponsesToConnectionId": "USE-TRAFFIC-PARROT-INTERNAL-BROKER"
}
}
curl -X POST http://localhost:8080/jms/replay \
-H "Content-Type: application/json" \
-d @replay.json
{
"flash" : {
"success" : "Started"
},
"status" : "ON"
}
A message {"order": "A-1001", "status": "?"} sent to
orders.request on tcp://localhost:9091 is
answered on orders.response with
{"status": "shipped"}. For a broker of your own, define a
connection in
jms-connections.json
and choose it when you start replay.
The same mapping in ibm-mq-mappings/, with the IBM MQ schema and the queues of your queue manager, is a native IBM MQ mapping:
{
"$schema": "http://localhost:8080/schemas/ibm-mq-mapping.schema.json",
"mappingId": "3f2e1d0c-9b8a-4c7d-8e6f-5a4b3c2d1e0f",
"request": {
"destination": {
"name": "DEV.QUEUE.1",
"type": "QUEUE"
},
"bodyMatcher": {
"contains": "status"
}
},
"response": {
"destination": {
"name": "DEV.QUEUE.2",
"type": "QUEUE"
},
"text": "{\"status\": \"shipped\"}"
}
}
Start replay with the id of a connection in ibm-mq-connections.json:
curl -X POST http://localhost:8080/ibmMq/replay \
-H "Content-Type: application/json" \
-d '{"action": "START", "queue": {"consumeRequestsFromConnectionId": "1", "replayResponsesToConnectionId": "1"}}'
A message containing status put on the request queue is
answered on the response queue with {"status": "shipped"}.
Every queue the mappings name has to exist on the queue manager, or
replay does not start.
A file message mapping answers a file with a file. Its
destination is a directory under a root directory from
root-directories.json,
fileNameMatcher matches the request file's name, and
fileName names the reply. file-mappings/order-status.json:
{
"$schema": "http://localhost:8080/schemas/file-message-mapping.schema.json",
"mappingId": "7e6d5c4b-3a29-4f18-9e07-1a2b3c4d5e6f",
"request": {
"destination": {
"name": "orders/in",
"type": "QUEUE"
},
"fileNameMatcher": {
"matches": ".*\\.json"
},
"bodyMatcher": {
"contains": "status"
}
},
"response": {
"destination": {
"name": "orders/out",
"type": "QUEUE"
},
"fileName": "order-status.json",
"text": "{\"status\": \"shipped\"}"
}
}
Create orders/in and orders/out under the root directory, and start replay with the root directory's id. In the shipped root-directories.json, id 2 is /tmp/file-transfers-root and id 1 is c:/tmp/file-transfers-root:
curl -X POST http://localhost:8080/fileMessage/replay \
-H "Content-Type: application/json" \
-d '{"action": "START", "directories": {"consumeRequestsFromRootDirectoryId": "2", "replayResponsesToRootDirectoryId": "2"}}'
Move a file order-1001.json holding
{"order": "A-1001", "status": "?"} into
orders/in. Traffic Parrot takes it, and
orders/out/order-status.json holds
{"status": "shipped"}.
Each of these loads without an error. The validate command catches the first two.
mappings/dsl-name.json:
{
"request": {
"method": "GET",
"urlEqualTo": "/orders"
},
"response": {
"status": 200,
"body": "every request gets this"
}
}
urlEqualTo is a method of WireMock's Java API, not a mapping
key. Traffic Parrot drops a key it does not know, so this mapping has no
URL and answers every GET:
curl -i http://localhost:8081/anything/else
HTTP/1.1 200 OK Vary: Origin Matched-Stub-Id: 08deea7a-68a2-35d1-816e-d46931fde25f Matched-Stub-Name: dsl-name.json Content-Length: 23 every request gets this
The URL keys of a mapping file are url, urlPattern,
urlPath, urlPathPattern and
urlPathTemplate.
In jms-mappings/http-keys.json:
"request": {
"destination": {
"name": "orders.request",
"type": "QUEUE"
},
"bodyPatterns": [
{
"contains": "status"
}
]
}
bodyPatterns belongs to HTTP mappings; a messaging mapping
has one bodyMatcher. While this file is in
jms-mappings/, no message on its queue is answered, one
that a correct mapping beside it matches included, and the log does not
name the file:
ERROR QueueReplayService-jms-vs-Default-0 Skipping JMS message because of an unexpected error java.lang.IllegalStateException: Request must either match text or bytes!
validate does name it:
Messaging mapping 'jms-mappings/http-keys.json' does not match jms-mapping.schema.json: /request: required property 'bodyMatcher' not found Messaging mapping 'jms-mappings/http-keys.json' does not match jms-mapping.schema.json: /request: property 'bodyPatterns' is not defined in the schema and the schema does not allow additional properties
urlPath"request": {
"method": "GET",
"urlPath": "/invoices?status=open"
}
urlPath is compared with the path alone, so this mapping
never matches: GET /invoices?status=open is answered with
900. Nothing reports it, validate included.
Put the query in queryParameters, as
orders-open.json does above, or match path and query
together with url.
If you come from WireMock: a response needs no
response-template transformer here. See the page for
WireMock users.