Write a mapping by hand

« Back to documentation home

An HTTP mapping from an empty file

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.

Autocomplete and validation in your editor

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.

FormatDirectorySchema, under http://localhost:8080
HTTPmappings//schemas/http-mapping.schema.json
gRPCgrpc-mappings//schemas/grpc-mapping.schema.json: the HTTP keys, with gRPC's urlPath, method and status
JMSjms-mappings//schemas/jms-mapping.schema.json
Native IBM MQibm-mq-mappings//schemas/ibm-mq-mapping.schema.json
File messagesfile-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.

  • Visual Studio Code reads the $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"
        }
      ]
    }
  • IntelliJ IDEA: under Settings, Languages & Frameworks, Schemas and DTDs, add a mapping in JSON Schema Mappings with the schema's address and your mappings folder. A schema at an address is downloaded when Allow downloading JSON Schemas from remote sources is ticked in Remote JSON Schemas, in the same group.

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 name, an id, a template file and a partial

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.
  • {{> templates/page-footer}} includes templates/page-footer.hbs from the install directory, a partial any template can share.
  • The 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.
  • The helpers and matchers your instance has are listed, each with a snippet, at http://localhost:8080/helpers-catalogue.json and http://localhost:8080/matchers-catalogue.json, and described under Dynamic Responses and Request Matching.

Check the files before they are loaded

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.

  • It checks HTTP, JMS, native IBM MQ and file message mappings against their schemas, and gRPC mappings against the .proto files.
  • It also lists warnings, which leave the exit code as it was: a gRPC mapping that does not match its schema, and a bodyFileName naming a file that is not in __files.
  • It also checks HTTP mappings against any OpenAPI specification in the directory's openapi/ folder. A new install ships an example specification there, so validate run on the install directory itself reports your mappings as missing from that example. Move the example out, or keep your files in a directory of their own.

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.

An example for CI

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. It unzips the release into a scratch folder, target/traffic-parrot-ci unless you move it, and copies traffic-parrot/ beside it, so nothing Traffic Parrot writes lands in traffic-parrot/.
  2. It runs validate on the copy. An error stops the run here with exit code 1, before anything starts; warnings are printed and pass.
  3. It starts Traffic Parrot with the files and waits for it to answer: from the unzipped release, or, with TRAFFIC_PARROT_DOCKER=true, in a Docker image built from the release and the files (ci/Dockerfile). If Traffic Parrot does not start, the run stops here with exit code 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/.
  4. It runs your test command with TRAFFIC_PARROT_URL set to the virtual service's address, stops Traffic Parrot and exits with the test's exit code. With no command it runs ci/smoke-test.sh, which calls the two example mappings.

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.

How a mapping gets loaded

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.

When a request gets no answer

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.

  • The closest mappings. The Request Log in the web UI compares the request with the closest mappings field by field. From a script, this call lists each unmatched request with the mappings closest to it, the closest first:
    curl http://localhost:8080/api/http/requests/unmatched/near-misses
  • Files that were not loaded. A file that is not valid JSON, or holds a value of the wrong type, is skipped, and the mappings beside it go on answering. The HTTP pages show a warning, the log has an ERROR line that starts Skipping mapping file, and this call lists the files:
    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"
    } ]
  • The mapping that did answer. When the wrong mapping answers, Matched-Stub-Name in the response names it.

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.

gRPC, JMS, native IBM MQ and file messages

gRPC

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.
  • Messages are written and matched as JSON. See gRPC.

JMS

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.

Native IBM MQ

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.

File messages

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"}.

Three mistakes to know

Each of these loads without an error. The validate command catches the first two.

A Java method name used as a key

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.

HTTP keys in a messaging mapping

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

A query string in 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.