A flexible mock server for automated and regression testing of iOS, Android and other apps.

Related tags

Testing Voodoo


Maintenance GitHub license GitHub tag

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.


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.


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 magic command line executable in .build/release/magic which has a variety of options for starting Voodoo. For example:

.build/release/magic 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.


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 magic loads the endpoints from YAML files. For example, here is a YAML file with the same endpoints, (see the YAML configuration guide) for details:


- http:
    api: get /config
        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 magic:

$ magic -c Sample.yml

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


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

export VOODOO=`magic -c Sample.yml`
  • Promote body type

    Promote body type

    In the YAML body payloads, replace the type key with the relevant type key. json, text, etc. We don't need the extra key and can use the type values as keys.

    opened by drekka 0
  • Feature: Generic decoding of bodies

    Feature: Generic decoding of bodies

    Added the ability to decode the body (Swift API only as it's pointless in javascript) to decode the body into a known Decodable type. Probably with a function like

    func bodyJSON<T>(as type: T.Type) -> T? where T: Decodable

    Or something like that.

    opened by drekka 0
  • Feature: Request forwarding.

    Feature: Request forwarding.

    Add the ability to call out and get responses from external servers. This comes from a prior custom server which was used for testing payment gateways and had to call out to payment test servers to obtain token to be returned to the app.

    opened by drekka 0
  • Expectations


    Was recently asked about applying expectations to registered APIs. Figure it should not be hard to do so. Am thinking of using a wrapper with counts calls along with some functions on Endpoint to set them up. So something like:


    Not sure about ordering. Will think on that.

    opened by drekka 0
  • Feature: Hot reloading for YAML configurations.

    Feature: Hot reloading for YAML configurations.

    Investigate whether we can do hot reloading. This will probably mean some work with the Hummingbird team to see if we can add an option to reset the router.

    opened by drekka 0
  • Feature: Multiple template engines.

    Feature: Multiple template engines.

    Add support for multiple template engines so that we can pull templates from multiple directories. This will also allow for templates with different extensions.

    opened by drekka 0
  • Feature: Add form and other data to mustache models.

    Feature: Add form and other data to mustache models.

    Currently passing data from the cache and any data added by the developer. Also need to add in form data, query data, REST path arguments, etc so that mustache can access it all.

    opened by drekka 0
  • 0.3.1(Nov 21, 2022)

  • 0.3.0(Nov 21, 2022)


    • Added the ability to set a delay. Delays affect all requests after being set. Use the admin path _admin/delay/<n.n> where 'n.nis the number of seconds to set. ie. a 2 second delay on all request from now on. Setting to 0 stops delaying requests. Delays can also be updated at any time in a XCTest withserver.delay = n.n`.
    • Added missing unauthorised and forbidden to response decoding from YAML files.



    • Adjusted YAML model for responses. the type field has been removed and replaced with the individual types as it was an unnecessary abstraction. For example


        type: text
        text: Hello


        text: hello
    Source code(tar.gz)
    Source code(zip)
  • 0.2.2(Nov 14, 2022)

  • 0.1.0(Oct 27, 2022)

Derek Clarkson
Got my start on IBM mainframes, did time in enterprise and java servers, now doing iOS and Swift.
Derek Clarkson
🐤Dynamically Mock server behaviors and responses in Swift

Kakapo Dynamically Mock server behaviors and responses. Contents Why Kakapo? Features Installation Usage Serializable protocol Router: Register and In

DevLucky 764 Aug 23, 2022
SwiftCheck is a testing library that automatically generates random data for testing of program properties

SwiftCheck QuickCheck for Swift. For those already familiar with the Haskell library, check out the source. For everybody else, see the Tutorial Playg

TypeLift 1.4k Dec 21, 2022
Testing the UI without UI Testing, a Swift experiment.

UI tests without UI Testing experiment This repo is a small experiment to see if there's an "in-between" for testing iOS applications. More feature-le

Joe Masilotti 20 Sep 26, 2022
A Popover that mock iOS SkinTone Selection Popover.

IMessage SkinTone Popover This is a popover mock the iOS iMessage Skin Tone Selection Menu (Popover) Features Long press to invoeke the popover, and t

Vincent Liu 1 Dec 9, 2021
Mock Alamofire and URLSession requests without touching your code implementation

Mocker is a library written in Swift which makes it possible to mock data requests using a custom URLProtocol. Features Requirements Usage Activating

WeTransfer 898 Dec 26, 2022
MockSwift is a Mock library written in Swift.

Welcome to MockSwift MockSwift allows you to write mocks and make better tests. Because MockSwift is an open source library 100% written in Swift, it

Jordhan Leoture 82 Dec 17, 2022
Automatic testing of your Pull Requests on GitHub and BitBucket using Xcode Server. Keep your team productive and safe. Get up and running in minutes. @buildasaur

Buildasaur Automatic testing of your Pull Requests on GitHub and BitBucket using Xcode Server. Keep your team productive and safe. Get up and running

Buildasaurs 774 Dec 11, 2022
Swifty tool for visual testing iPhone and iPad apps. Every pixel counts.

Cribble Cribble - a tool for visual testing iPhone and iPad apps. Every pixel counts. Getting Started An example app is included demonstrating Cribble

Max Sokolov 273 Nov 4, 2022
Implementing and testing In-App Purchases with StoreKit2 in Xcode 13, Swift 5.5 and iOS 15.

StoreHelper Demo Implementing and testing In-App Purchases with StoreKit2 in Xcode 13, Swift 5.5, iOS 15. See also In-App Purchases with Xcode 12 and

Russell Archer 192 Dec 17, 2022
Snapshot testing tool for iOS and tvOS

SnapshotTest is a simple view testing tool written completely in Swift to aid with development for Apple platforms. It's like unit testing for views.

Pär Strindevall 44 Sep 29, 2022
A Mac and iOS Playgrounds Unit Testing library based on Nimble.

Spry Spry is a Swift Playgrounds Unit Testing library based on Nimble. The best thing about Spry is that the API matches Nimble perfectly. Which means

Quick 327 Jul 24, 2022
Multivariate & A/B Testing for iOS and Mac

This library is no longer being maintained. You can continue to use SkyLab in your projects, but we recommend switching another solution whenever you

Mattt 792 Dec 15, 2022
Remote configuration and A/B Testing framework for iOS

MSActiveConfig v1.0.1 Remote configuration and A/B Testing framework for iOS. Documentation available online. MSActiveConfig at a glance One of the bi

Elevate 78 Jan 13, 2021
Sample project for testing out focus in SwiftUI and iOS 15

This project was to test out different ways of enabling focus in a SwiftUI app.

null 3 Dec 21, 2021
AB testing framework for iOS

ABKit Split Testing for Swift. ABKit is a library for implementing a simple Split Test that: Doesn't require an HTTP client written in Pure Swift Inst

Recruit Marketing Partners Co.,Ltd 113 Nov 11, 2022
Keep It Functional - An iOS Functional Testing Framework

IMPORTANT! Even though KIF is used to test your UI, you need to add it to your Unit Test target, not your UI Test target. The magic of KIF is that it

KIF Framework 6.2k Dec 29, 2022
An understated approach to iOS integration testing.

Subliminal is a framework for writing iOS integration tests. Subliminal provides a familiar OCUnit/XCTest-like interface to Apple's UIAutomation frame

Inkling 762 Nov 8, 2022
Bluepill is a reliable iOS testing tool that runs UI tests using multiple simulators on a single machine

Bluepill is a tool to run iOS tests in parallel using multiple simulators. Motivation LinkedIn created Bluepill to run its large iOS test suite in a r

Mobile Native Foundation 3.1k Jan 3, 2023
iOS Simulator type agnostic snapshot testing, built on top of the FBSnapshotTestCase.

SnappyTestCase iOS Simulator type agnostic snapshot testing, built on top of the FBSnapshotTestCase. Why? Snapshot testing helps to deliver views that

Tooploox 15 Oct 11, 2019