TShield

API mocks for development and testing

TShield is an open source proxy for mocks API responses.

• REST
• SOAP
• Session manager to separate multiple scenarios (success, error, sucess variation, ...)
• Lightweight
• MIT license

Table of Contents:

• Basic Usage
• Config options for Pattern Matching
• Config options for VCR
• Manage Sessions
• Custom controllers
• Features
• Examples
• Contributing

Basic Usage

Install

gem install tshield

Using

To run server execute this command

tshield

Default port is 4567

Command Line Options

• -port: Overwrite default port (4567)
• -help: Show all command line options

Config example

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:
      - /users

Config options for Pattern Matching

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.
• 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

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.

Important: If VCR config conflicts with Matching config Matching will be used. Matching config have priority.

Session Configuration

To register stub into a session create an object with following attributes:

• session: name of session.
• stubs: an array with objects described above.

Example of matching configuration

[{
    "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": {
        "body": "matching-example-response-in-session",
        "headers": {},
        "status": 200
      }
    }]
  }
]

Config options for VCR

request:
  timeout: 8
  verify_ssl: <<value>>
domains:
  'http://my-soap-service:80':
    name: 'my-soap-service'
    headers:
      HTTP_AUTHORIZATION: Authorization
      HTTP_COOKIE: Cookie
    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

  'http://localhost:9092':
    name: 'my-other-service'
    headers:
      HTTP_AUTHORIZATION: Authorization
      HTTP_COOKIE: Cookie
    not_save_headers:
      - transfer-encoding
    paths:
      - /users

request

• 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
• 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"

Manage Sessions

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 TShield session

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 TShield session

Stop current session

DELETE to http://localhost:4567/sessions

curl -X DELETE \
  http://localhost:4567/sessions

Custom controllers

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
end

Features

Description of some tshield features can be found in the features directory. This features files are used as base for the component tests.

Examples

Basic example for a client app requesting an API

examples/client-api-nodejs

Basic example for component/acceptance test

[WIP]

Contributing

Hacking or Contributing to TShield