TShield is an open source proxy for mocks API responses.
- REST
- SOAP
- Session manager to separate multiple scenarios (success, error, sucess variation, ...)
- gRPC [EXPERIMENTAL]
- Lightweight
- MIT license
- Basic Usage
- Config options for Pattern Matching
- Config options for VCR
- Manage Sessions
- Custom controllers
- Features
- Examples
- Contributing
gem install tshield
To run server execute this command
tshield
Default port is 4567
- -port: Overwrite default port (4567)
- -help: Show all command line options
Before run tshield command is necessary to create config file.
This is an example of config/tshield.yml
request:
# wait time for real service
timeout: 8
# list of domains that will be used
domains:
# Base URI of service
'https://service.com':
# name to identify the domain in the generated files
name: 'service'
# paths list of all services that will be called
paths:
- /usersWindows Compatibility: If you need to use Tshield in Windows SO, change the config file and set the windows_compatibility to true.
Eg:
windows_compatibility: true
request:
# wait time for real service
timeout: 8
...An example of file to create a stub:
All files should be in matching directory.
Each file should be a valid JSON array of objects and each object must contain
at least the following attributes:
- method: a http method.
- path: url path. This attribute accept regex, see example in regex.json
- response: object with response data. Into session can be used an array of objects to return different responses like vcr mode. See example: multiples_response.json. External file can be used as body content, see example in file.json.
Response must be contain the following attributes:
- headers: key value object with expected headers to match. In the evaluation process this stub will be returned if all headers are in request.
- status: integer used http status respose.
- body: content to be returned.
Optional request attributes:
- headers: key value object with expected headers to match. In the evaluation process this stub will be returned if all headers are in request.
- query: works like headers but use query params.
Optional response attributes:
- delay: integer that represents time in seconds that the response will be delayed to return
Important: If VCR config conflicts with Matching config Matching will be used. Matching config have priority.
To register stub into a session create an object with following attributes:
- session: name of session.
- stubs: an array with objects described above.
[
{
"method": "GET",
"path": "/matching/example",
"query": {
"user": 123
},
"response": {
"body": "matching-example-response-with-query",
"headers": {},
"status": 200
}
},
{
"method": "GET",
"path": "/matching/example",
"response": {
"body": "matching-example-response",
"headers": {},
"status": 200
}
},
{
"method": "POST",
"path": "/matching/example",
"headers": {
"user": "123"
},
"response": {
"body": "matching-example-response-with-headers",
"headers": {},
"status": 200
}
},
{
"method": "POST",
"path": "/matching/example",
"response": {
"body": "matching-example-response-with-post",
"headers": {},
"status": 200
}
},
{
"session": "example-session",
"stubs": [{
"method": "GET",
"path": "/matching/example",
"response": {
"delay": 5,
"body": "matching-example-response-in-session",
"headers": {},
"status": 200
}
}]
}
]request:
timeout: 8
verify_ssl: <<value>>
domains:
'http://my-soap-service:80':
name: 'my-soap-service'
headers:
HTTP_AUTHORIZATION: Authorization
HTTP_COOKIE: Cookie
send_header_content_type: true
not_save_headers:
- transfer-encoding
cache_request: <<value>>
filters:
- <<value>>
excluded_headers:
- <<value>>
paths:
- /Operation
'http://localhost:9090':
name: 'my-service'
headers:
HTTP_AUTHORIZATION: Authorization
HTTP_COOKIE: Cookie
HTTP_DOCUMENTID: DocumentId
not_save_headers:
- transfer-encoding
paths:
- /secure
delay:
'/secure': 10
'http://localhost:9092':
name: 'my-other-service'
headers:
HTTP_AUTHORIZATION: Authorization
HTTP_COOKIE: Cookie
not_save_headers:
- transfer-encoding
paths:
- /users
delay:
'/users': 5request
- timeout: wait time for real service in seconds
- verify_ssl: ignores invalid ssl if false
domain
- Define Base URI of service
- name: Name to identify the domain in the generated files
- headers: github-issue #17
- send_header_content_type: Boolean domain config to send header 'Content-Type' when requesting this domain
- not_save_headers: List of headers that should be ignored in generated file
- skip_query_params: List of query params that should be ignored in generated file
- cache_request: <<some_description>>
- filters: Implementation of before or after filters used in domain requests
- excluded_headers: <<some_description>>
- paths: Paths list of all services that will be called. Used to filter what domain will "receive the request"
- delay: List of times in seconds that the response will be delayed to return for an specific path defined above
You can use TShield sessions to separate multiple scenarios for your mocks
By default TShield save request/response into
requests/<<domain_name>>/<<resource_with_param>>/<<http_verb>>/<<index_based.content and json>>
If you start a session a folder with de session_name will be placed between "requests/" and "<<domain_name>>"
Start new or existing session
POST to http://localhost:4567/sessions?name=<<same_name>>
curl -X POST \
'http://localhost:4567/sessions?name=my_valid'
Stop current session
DELETE to http://localhost:4567/sessions
curl -X DELETE \
http://localhost:4567/sessions
Append session. Secondary sessions will used only for read content in VCR mode, writes will be do in the main session. Append only works if exists a current session setted.
POST to http://localhost:4567/sessions?name=<<same_name>>
curl -X POST \
'http://localhost:4567/sessions/append?name=my_valid'
grpc:
port: 5678
proto_dir: 'proto'
services:
'helloworld_services_pb':
module: 'Helloworld::Greeter'
hostname: '0.0.0.0:50051'- Matching
First, generate ruby files from proto files. Use grpc_tools_ruby_protoc
present in the gem grpc-tools. Example:
grpc_tools_ruby_protoc -I proto --ruby_out=proto --grpc_out=proto proto/<INPUT>.proto
Call example in component_tests using grpcurl:
grpcurl -plaintext -import-path component_tests/proto -proto helloworld.proto -d '{"name": "teste"}' localhost:5678 helloworld.Greeter/SayHello
All custom controller should be created in controllers directory.
Example of controller file called controllers/foo_controller.rb
require 'json'
require 'tshield/controller'
module FooController
include TShield::Controller
action :tracking, methods: [:post], path: '/foo'
module Actions
def tracking(params, request)
status 201
headers 'Content-Type' => 'application/json'
{message: 'foo'}.to_json
end
end
endDescription of some tshield features can be found in the features directory. This features files are used as base for the component tests.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent