Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A tool for simple faking APIs of HTTP webservices.
Ruby CoffeeScript

This branch is even with jopek:editor

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
bin
features
javascripts/lib
lib
spec
views
.gitignore
Gemfile
Gemfile.lock
LICENSE
README.rdoc
Rakefile
config.ru
holoserve.gemspec

README.rdoc

Holoserve - Simple faking of HTTP APIs

This tool can be used to fake HTTP web APIs. It's meant to be used in a testing environment, to make the test suite run faster and be independent from other API and network problems.

Concept

HoloServe runs a rack application server, that matches any incoming request to a list of request profiles defined in the server layout. If a match is found, the defined static response is returned. The response is defined by a default and the current server situation. The name of the matched request/response pair is saved in a request history. If no match is found, a 404 is returned and the request data is stored in the bucket for unhandeled requests. These informations can be used to extend the server layout with missing request handlers.

The layout, situation, history and bucket can be accessed via control routes, which are described below.

Installation

Assuming that ruby and gem are installed, simply type…

gem install holoserve

Run from the command line

To start up an empty Holoserve instance, type…

holoserve

To load a server layout and define a situation during start up, use these parameters.

holoserve -l layout.yaml -s backend_without_users

Notice, that the layout file must have either the .yaml or the .json extension.

Control routes

If you're using Ruby, you can control Holoserve via the Holoserve Connector gem.

POST /_control/layout.:format

It should receive a parameter named file that contains a file with the server layout. The format of the file should fit the specified format. The format can be yaml or json. See {Layout file format}[rdoc-label:Layout-file-format] below.

GET /_control/layout.:format

Returns the server layout in the requested format.

DELETE /_control/layout

Removes the server layout.

PUT /_control/situation/:name

Sets the current situation.

GET /_control/situation

Returns the name of the current situation.

Response example

backend_without_users

GET /_control/bucket/requests

Returns a list of all requests that has been received, but couldn't be handled.

Response example

[
  {
    "method": "POST",
    "path": "test",
    "headers": {
      "REMOTE_ADDR": "127.0.0.1",
      "REQUEST_METHOD": "GET",
      "REQUEST_PATH": "/test",
      "PATH_INFO": "/test",
      "REQUEST_URI": "/test",
      "SERVER_PROTOCOL": "HTTP/1.1",
      "HTTP_VERSION": "HTTP/1.1",
      "HTTP_ACCEPT": "*/*",
      "HTTP_USER_AGENT": "Ruby",
      "HTTP_HOST": "localhost:8080",
      "SERVER_NAME": "localhost",
      "SERVER_PORT": "8080",
      "QUERY_STRING": "",
      "SCRIPT_NAME": "",
      "SERVER_SOFTWARE": "Unicorn 4.1.1"
    }
  }
]

GET /_control/history

Returns a list of all names of pairs that has been triggered.

Response example

[ "create_received", "update_received" ]

DELETE /_control/history

Removes all entries from the history.

Layout file format

The server layout file should have the following format.

-
  name: "test_received"
  request:
    method: "POST"
    path: "/test"
    headers:
      HTTP_USER_AGENT: "Ruby"
      HTTP_AUTHORIZATION: "OAuth oauth_token=12345"
    body:
      "test=value"
    parameters:
      test: "value"
    oauth:
      oauth_token: "12345"
  responses:
    default:
      status: 200
    one:
      body:
        "ok"
-
  request:
    method: "GET"
    path: "/test"
  responses:
    default:
      status: 200
      body:
        "ok too"

This example would define a server layout that has two request/response pairs. The first pair would have the name test_received and would match a POST request to the path /test.

Notice, that the given request attributes are the minimal values that have to match the incomong one. An incoming request may has much more attributes (see bucket example above). If a request is matched, the corresponding pair name is placed in the history.

As the sections headers and body are raw values from the request, the sections parameters and oauth contain high-level values. The parameters hash is taken from the request body or the query and the hash containing the OAuth values is parsed from a fitting HTTP_AUTHORIZATION header.

The response is defined in the responses section of each pair. The server will response a merge of default response and the response defined by the current situation.

Something went wrong with that request. Please try again.