A mock in Traffic Parrot is a set of files. A mapping is a JSON file, a response body or template can be a file of its own, and the settings are properties and JSON files. The web UI edits those same files, so you can leave it closed: write the files in your editor, keep them in git, and load and check them from a script.
With the settings Traffic Parrot ships with, a mapping or template file you save is used by the next request, with no restart and no reload call. The file layout page says when that is not so.
| You want to | Read |
|---|---|
| Write a mapping in your editor, with autocomplete, and see it answer | Write a mapping by hand, for HTTP, gRPC, JMS, native IBM MQ and file messages |
| Know which file holds what, and when an edit takes effect | The file layout |
| See every key a mapping file can carry | The mapping explorer, a searchable tree of the keys, or the key reference for HTTP, gRPC, JMS, native IBM MQ and file messages. The mapping schemas your instance serves give your editor the same keys |
| Match requests and build responses | Request Matching for the matchers, Dynamic Responses for the Handlebars helpers and template files |
| Check the files before they are loaded, by hand or in CI | The validate command |
| Check the files, start Traffic Parrot with them and run your tests in a CI job | The CI example, a script and a GitHub Actions workflow to copy |
| Find out why a request got no answer | When a request gets no answer |
| Drive Traffic Parrot from a script | The table below and the Management API reference |
| Add your own matcher, helper or transformer | Custom extensions, with the SDK Javadoc and the SDK workspace project to start from |
Each thing the web UI does is a file it writes, a call on the management port (8080 unless you changed it), or both. The calls are in the Management API reference.
| In the UI | The file | The API call |
|---|---|---|
| Add or edit an HTTP mapping | One JSON file in mappings/, and a file in __files/ when the body is kept in a file | POST /api/http/__admin/mappings with "persistent": true in the mapping. Without it the mapping is held in memory and is gone at a restart. |
| Turn on response templating | Nothing to turn on: a response body is a template already, with no transformers entry |
None |
| Import and export HTTP mappings | The files in mappings/ and __files/ | POST /http/management/importMappings, GET /http/management/exportMappings |
| Record HTTP traffic | The recorded mappings, in mappings/ and __files/ | POST /http/management/startRecording, POST /http/management/stopRecording, GET /http/management/currentRecordingStatus |
| The warning that a mapping file was not loaded | None | GET /http/management/skippedMappingFiles, GET /grpc/management/skippedMappingFiles |
| Choose the virtual service to serve | One folder per virtual service, scenarios/Name/ | GET /api/scenarios lists them. PUT /api/scenarios/{name} with {"enabled": true} selects one. |
| Add or edit a gRPC mapping | A JSON file in grpc-mappings/, served from the .proto files in proto/ | POST /api/grpc/mapping, GET /grpc/management/mappings, POST /grpc/management/importMappings |
| Add or edit a JMS mapping | A JSON file in jms-mappings/ | POST /jms/management/prime, GET /jms/mappings, POST /jms/management/importMappings |
| Add or edit a native IBM MQ mapping | A JSON file in ibm-mq-mappings/ | POST /api/ibmMq/mappings, GET /ibmMq/mappings |
| Add or edit a file message mapping | A JSON file in file-mappings/ | POST /fileMessage/management/importMappings |
| Start and stop replay or recording for JMS, IBM MQ or file messages | None | POST to /jms/replay, /ibmMq/replay or /fileMessage/replay, and to the matching /record path. GET reads the state. |
| The connections to brokers, queue managers, file roots and databases, which the UI lists and does not edit | jms-connections.json, ibm-mq-connections.json, root-directories.json, database-connections.json | None: edit the file |
| A setting, which the UI does not change | trafficparrot.properties | None: edit the file, or pass the value to the start script, then restart |
How a mapping gets loaded shows the HTTP mapping call and the virtual service call with their answers, and the messaging samples show the replay calls.
An AI coding assistant can write and check these files with you. The install directory holds a brief for it, AGENTS.md, and a running instance serves the mapping schemas and the helper and matcher catalogues it reads. See Generate mocks with AI and the MCP endpoint reference.