Working with files

« Back to documentation home

Mocks as files

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.

Where to start

You want toRead
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

The UI, the file and the API side by side

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 UIThe fileThe 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.

Going further with an AI assistant

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.