Troxy is an highly configurable and extendable application that simulates responses using the HTTP(S) protocol. Troxy can handle many simultaneous requests making it an excellent choice to use when running performance tests against your application.
Build Troxy
mvn clean install
docker build -t troxy .
docker run -p 8080:8080 troxy
Troxy can be started locally by running Troxy.main(). The working directory must be set to troxy/local
Troxy can match requests based on different attributes in the HTTP protocol.
- Protocol
- HTTP Method
- Port
- Host
- Path
- Query parameters
- Header
- Content
All of these attributes use regular expressions.
Troxy can be run in different modes.
In this mode, troxy will forward requests to the specified backend system and responses are then forwarded back to the client.
In this mode, troxy will forward requests to the backend system and make a mock-recording of the responses before forwarding them back to the client. The recordings are then saved on a file and can be viewed under the "Opptak" tab.
In this mode, troxy matches incoming requests with existing mocks. If a match is found, the matching response is sent back. If no match is found, Troxy will return HTTP status 418.
In this mode, Troxy will send back a matching response if found. If a response is not found the request will be forwarded to the backend system and a new recording will be created.
In this mode, Troxy will send back a matching response if found. If a response is not found the request will be forwarded to the backend system but Troxy will not record the response. This mode is designed to be used for manual testing when you want to mock a set of requests, while sending other requests as usual to the backend system.
Troxy provides an API where you can change the mode or upload mocks from disk
curl -v -F directory="troxyfolder/" -F file="@recordings-201909171032.zip" http://localhost:8080/api/upload
curl -v -F directory="troxyfolder/" -F file="@single_recording.troxy" http://localhost:8080/api/upload
Troxy modes
PLAYBACK
RECORD
PLAYBACK_OR_RECORD
PASSTHROUGH
PLAYBACK_OR_PASSTHROUGH
curl 'http://localhost:8080/api/status/mode' -X PUT --data 'RECORD'
Statistics interval (minutes)
0
1
5
10
15
30
60
1440
curl 'http://localhost:8080/api/status/statisticsInterval' -X PUT --data '5'
Recordings are saved as files with a .troxy file extension. All recordings are available for editing in the GUI under the "Opptak" tab. Individual recordings can also be activated or disabled under this tab.
Mocks can be configured using different time delay strategies.
None - The response is returned directly with no delay
Permanent - The response is returned after a configured value is reached
Random - The response is returned after a random time, between the limits that are configured, is reached
Normally distributed - The response time is calculated by a normally distributed curved where min and max values are configured.
Exponential distribution - The response time is calculated using an exponential distribution where min, average and max values are configured.
All HTTP attributes use regular expressions.
Below is an example illustrating how this works. The header must contain a specific SOAPAction but anything else in the same header field uses regular expressions.
Tip: you can press Ctrl + Space to get a small list of commonly used regular expressions.
You can use regular expression group capturing to extract values from the request and insert those in the response.
In this example a social security number is extracted from a request body by using the following group capturing syntax: (?<nnin>[0-9]*). The result (the social security number) is extracted to a group named nnin.
The extracted value can then be used in the response by the following syntax: $content:nnin$
Note that you need to specify where the value was extracted from (in this case content). If the value was extracted from the header the syntax would be $header:nnin$. To get a list of defined regular expression groups in the Response tab, you can again use Ctrl + Space to get a list.
You can fetch environment variables and insert those in the response to provide a more dynamic mock. Syntax is $env:MYENVIRONMENTVARIABLE$
Troxy can use the same request for several different responses. There are two strategies used when this mode is enabled for a recording.
Random - When an expected incoming request is made, one of the available responses are chosen at random. It is possible to weigh responses. For example, one response can have a 25% chance to be returned, and another can have a 75% chance.
Sequential - When an expected incoming request is made, the responses are returned sequentially. If a recording has several responses; the first response will be returned for the first request, the second response for the second request and so on. When the last response is reached, response 1 will be returned next. In this mode we also have the option of weighing responses so that one response can be returned several times before continuing to the next one.
The logging tab shows the content from the log file simulator.log.
In order to get your application to send its traffic through Troxy you have to add the Troxy URL before the backend request url.
# Example
# Original setting
some_rest_api_url=https://some-api.sparebank1.no
# Through Troxy
some_rest_api_url=https://troxy.test.sparebank1.no/https://some-api.sparebank1.no
If you use docker you can link to it instead in the compose file
yourapplication:
image: __IMAGE_REPO_AND_TAG__
links:
- troxy:some-api.sparebank1.no
Filters are a way to extend the functionality of Troxy. Filters have access to modify requests and their respective responses during both recording and playback. Compiled filters (.jar) must be moved to the /opt/troxy/data/filters folder in order to be picked up by Troxy.
A filter can manipulate a request and response in the following five phases in this specific order:
- Upon receiving a client request, before Troxy searches for matching recordings.
- Before a request is forwarded to the backend system
- When receiving a response from the backend system
- When creating a new recording (does not apply to recordings created through the user interface).
- Before responses are sent to the client.
Note: If you do not communicate with a backend system (i.e mode Playback), phases 2, 3 and 4 will not be activated.
Filters can be configured under the "Oppsett" tab.
A filter will not run unless it is first activated
filter.<filtername>.enabled=true
Implemented filters might have their own configuration. This configuration can be accessed as shown below
filter.<filtername>.config.<key>=<value>
There are some filters that are included in Troxy by default. Examples of these can be found in the Troxy configuration file troxy.properties
AutoRegexNewRecording A filter that searches for text in new recordings that matches the specified configured regular expression, It then replaces the text with the configured regular expression or specified value.
DelayResponse A filter that handles time delays for recordings
KeyBasedReplace A filter that searches for a key in the request. If the key is found it will use the key to pick a value from a data file and use this value in the response.
SetRecordingDelay A filter that will set time delays on new recording based on the real time it took during the record.
FunctionReplace
A filter that replaces keys with a support function. Keys are replaced in both the response body and header in the recorded Troxy response. More supported functions may be added at a later time.
One of the functions supported are now. now replaces a specified key with a timestamp on a specified format.
Under the "Statistikk" tab you can see statistics of the number of requests for different recordings. The interval is default set to 60 minutes but can be configured in the file troxy.properties or under the Status page.