README.md

Note: This document is intended as a quick introduction to Voodoo. As Voodoo has a large number of features, please refer to Voodoo's Github Wiki for detailed information on how to use Voodoo.

Intro

Voodoo is a mock server specifically designed to support debugging and automated testing of applications with a particular emphasis on being run as part of a regression or automated UI test suite.

It primary features are:

• Fast checkout and build via the Swift Package Manager.

• Direct integration into XCode test suites or to be run as a stand alone server (for Android or other non-Xcode environments).

• Fast startup. Typically < 1sec.

• Parallel test friendly via port ranges.

• Configurable via a Swift API (for XCTest), and/or YAML and Javascript (for command line).

• RESTful and GraphQL query support.

• Fixed and dynamic response definitions that can return raw text, JSON, YAML, or custom data.

• Response templating via {{mustache}} with a pan-query cache for sharing data between endpoints.

• General file serving of non-API resources.

Installation

iOS/OSX SPM package

Voodoo comes as an SPM module which can be added using Xcode to add it as a package to your UI test targets. Simply add https://github.com/drekka/Voodoo as a package to your test targets and...

import Voodoo

Linux, Windows, Docker, etc

Note that there is a more detailed install guide for other platforms here.

You will need to have a working Swift environment. Then clone https://github.com/drekka/Voodoo and build Voodoo:

cd Voodoo
swift build -c release

Once finished you will find the voodoo-server command line executable in .build/release which has a variety of options for starting Voodoo. For example:

.build/release/voodoo-server run --config Tests/files/TestConfig1 --template-dir tests/templates --file-dir tests/files

At a minimum you have to specify the run and --config arguments so Voodoo knows which directory or YAML file to load the endpoint configurations from, but the rest is optional.

Endpoints

Voodoo uses the concept of Endpoint to configure how it will respond to incoming requests. Each endpoint is defined by two things, a way to identify an incoming request and the response to return.

In a XCTest suite endpoints can be passed as part of the VoodooServer initialiser. They can also be added later. Here is a Swift example of starting Voodoo with some endpoints (see the Xcode configuration guide) for more details:

server = try VoodooServer {

            HTTPEndpoint(.GET, "/config", response: .json(["featureFlag": true])

            HTTPEndpoint(.POST, "/login", response: .dynamic { request, cache in
                cache.loggedIn = true
                cache.username = request.formParameters.username
                return .ok()
            })

            HTTPEndpoint(.GET, "/profile", response: .dynamic { request, cache in
                if cache.loggedIn ?? false {
                    return .unauthorised()
                }
                return .ok(body: .json(["username": cache.username]))
            })
        }

On the command line voodoo-server loads the endpoints from YAML files. For example, here is a YAML file with the same endpoints, (see the YAML configuration guide) for details:

Sample.yml

- http:
    api: get /config
    response:
      json:
        featureFlag: true
      
- http:
    api: post /login
    javascript: |
      function response(request, cache) {
          cache.loggedIn = true;
          cache.username = request.formParameters.username;
          return Response.ok();
      }
      
- http:
    api: get /profile
    javascript: |
      function response(request, cache) {
          if cache.loggedIn ?? false {
              return Response.unauthorised();
          }
          return Response.ok(Body.json({
              username: cache.username 
          }));
      }          

And here is how we would start Voodoo via voodoo-server:

$ voodoo-server -c Sample.yml

voodoo-server has a variety of options and there are many ways to setup the YAML configuration files. See the YAML endpoint setup guide for details.

Getting the URL

On starting Voodoo will automatically scan the configured port range for a free port (8080...8090 by default). When it finds an unused port it starts the server on it.

To get the URL (including the port) of the server in Swift:

server.url.absoluteString

On the command line, voodoo-server outputs the server URL which means you can do something like this:

export VOODOO=`voodoo-server -c Sample.yml`