Latest 0.0.2
License MIT
Platforms ios 8.0, osx 10.10, requires ARC

Carthage compatible

Velociraptor is a network stubbing framework written in pure Swift for iOS and OS X.


  • iOS 8.1+ / Mac OS X 10.10+
  • Xcode 6.3


  • If you found a bug, open an issue.
  • If you have a feature request, open an issue.
  • If you want to contribute, feel free to submit a pull request.


Use CocoaPods or Carthage to integrate Velociraptor into your test target. Other approaches are not recommended.


CocoaPods is a dependency manager for Cocoa projects.

CocoaPods 0.36 adds supports for Swift and embedded frameworks. You can install it with the following command:

$ gem install cocoapods

To integrate Velociraptor into your Xcode project using CocoaPods, specify it in your Podfile:

target :YourTestTarget do
  pod 'Velociraptor'

Then, run the following command:

$ pod install


Carthage is a decentralized dependency manager for Cocoa application. You can use Homebrew to install Carthage.

$ brew update
$ brew install carthage

To integrate Velociraptor into your Xcode project using Carthage, please follow the instructions:

  1. Add Velociraptor to your Cartfile.private:
github "mrahmiao/Velociraptor"
  1. Run carthage update.

  2. From your Carthage/Build/[platform]/ directory, add Velociraptor.framework to your test target’s "Link Binary With Libraries" build phase:

  3. For your test target, create a new build phase of type "Copy Files":

  4. Set the "Destination" to "Frameworks", then add both frameworks:


The following examples are described using Quick.

Activate && Deactivate Velociraptor

Since method swizzling is used in Velociraptor, you should activate and deactivate Velociraptor manually in order to avoid strange behaviors.

import Quick
import Nimble
import Velociraptor

class VelociraptorSpec: QuickSpec {
  override func spec() {
    beforeSuite {

    afterSuite {

    describe(“Stubbing requests”) {
      // …

If you are using XCTest, use the following code:

import Foundation
import XCTest
import Velociraptor

class VelociraptorTests: XCTestCase {

  override class func setUp() {

  override class func tearDown() {

  func testExample() {
    // ...

Stubbing requests

Stubbing a Simple GET Request

You can use String, NSURL and NSURLRequest directly to stub simple GET requests. And if you do not
specify any response you want to retrieve, you will receive a default response which has a status code of
200 and empty body data.

let URLString = ""
let URL = NSURL(string: URLString)!
let request = NSURLRequest(URL: URL)

// String


// NSURLRequest

Stubbing Requests with an VLRStubbedRequest Object

With VLRStubbedRequest object, you can set the full condition of requests you want to stub. And requests
with those information you set would be stubbed.

let stubbedRequest = VLRStubbedRequest(URL: URL)
stubbedRequest.HTTPMethod = .GET
stubbedRequest.HTTPBody = "Hello World".dataUsingEncoding(NSUTF8StringEncoding, allowLossyConversion: false)
stubbedRequest.HTTPHeaderFields = ["Auth": "jk1234"]


Stubbing Requests with Different HTTP Methods

Besides GET requests, you can stub requests with any other HTTP methods that defined in RFC-7231.


And there are 5 convenience methods for you to stub the most commonly used HTTP methods:


Stubbing Requests With Specified Header Fields

You can stub either one particular header field or multiple header fields simultaneously.

// Stubs one particuluar header field
Velociraptor.GET(URL)?.requestHeaderValue("*", forHTTPHeaderField: "Accept")

// Stubs multiple header fields
let headerFields = [
  "Accept": "*",
  "Other": "HeaderFields"

Header Field Matching Options

Velociraptor.VLRHeaderFieldMatchingOptions lists the option you will use when matching header fields.

public enum VLRHeaderFieldMatchingOptions {
  case .Exactly
  case .Partially(UInt)
  case .StrictSubset
  case .Arbitrarily

The default header field matching option is .Exactly, which indicates that only when two header fields (both incoming request and stubbed request) are identicial, the request would be matched.

Or you can set the option to the other options.

Velociraptor.headerFieldMatchingOption = .Partially(3)
  • Exactly: indicates that the header fields of incoming request and the header fields of stubbed request must be exactly the same.
  • Partially(UInt): Uses the associated UInt value to specify the minimum number of common header fields of both incoming request and stubbed request. When the number of common header fields greater or equal than the specified minimum number, the incoming request will be matched. Note that if the number is set to 0, and this option is identical to .Arbitrarily. And the maximum of it is the number of the stubbed header fields.
  • StrictSubset: Only when the header fields of incoming request are a strict subset of the header fields of stubbed request, the match will succeed.
  • Arbitrarily: Match requests with arbitray header fields.

Stubbing HTTP Body Data

When setting the http body, the Content-Length header field will be added to the header fields of stubbed request.

let data = "Hello World".dataUsingEncoding(NSUTF8StringEncoding, allowLossyConversion: false)

Stubbing HTTP Responses

Stubbing Single Header Fields of Responses

You can stub either a single header value or multiple header fields

// Single Header Field
Velociraptor.GET(URL)?.responseHeaderValue("application/json", forHTTPHeaderField: "Content-Type")

// Multiple Header Fields
let headerFields = [
  "Content-Type": "application/json",
  "ReceivedRes": "Response"

Stubbing Status Code

Use this method to specify the status code you want to receive in completion handlers:


Stubbing Error Response

If you want to stub an error response, use the method below:

let errorCode = 1234
let userInfo = ["Error": "StubbedError"]
let domain = "com.code4blues.mrahmiao.velociraptor"
let stubbedError = NSError(domain: domain, code: errorCode, userInfo: userInfo)


Stubbing Body Data

You can stub NSData as the body data:

let data = "Hello World".dataUsingEncoding(NSUTF8StringEncoding, allowLossyConversion: false)

Stubbing JSON Body Data:

You can encode ordinary objects into JSON and use them as the body data:

let JSONObject: AnyObject = [
  "Number": 5,
  "Bool": false,
  "Array": [5, 4, 3]


Note that only objects that satisfied the conditions listed in the documentation
of NSJSONSerialization could be converted to JSON. Otherwise, an exception will be raised.

You can also stubbed the JSON data rather than JSON object, and the following two code snippets
are equivalent:

let JSONObject: AnyObject = [
  "Number": 5,
  "Bool": false,
  "Array": [5, 4, 3]

let JSONData = NSJSONSerialization.dataWithJSONObject(object, options: NSJSONWritingOptions.allZeros, error: nil)!


// Equivalent to
    .responseHeaderValue(value: "application/json; charset=utf-8", forHTTPHeaderField: "Content-Type")

When stubbing JSON data, Content-Type will be set to application/json; charset=utf-8

Stubbing Body Data with File

If you have files that contains data you want to use as the HTTP body data, just use them:

Velociraptor.request(URL)?.responseContentsOfFile("content.json", contentType: "application/json")

The file should be located in your test bundle.

Put Them Together

Supposed that I want to stub a POST request:

let URL = ""
let requestHeader = [
  "Authorization": "3721"
let requestData = "Hello World".dataUsingEncoding(NSUTF8StringEncoding, allowLossyConversion: false)

let responseHeaders = [
  "Status": "Success"
  "uID": "3214"


Stubbing Response Using VLRStubbedResponse Object

Instead of using a series of methods, you can use a single VLRStubbedResponse object to stub resopnse:

let statusCode = 201
let bodyData = "Hello World".dataUsingEncoding(NSUTF8StringEncoding, allowLossyConversion: false)!
let expectedResponse = VLRStubbedResponse(URL: URL, statusCode: statusCode)
expectedResponse.HTTPHeaderFields = [
  "Content-Type": "text/plain",
  "Content-Length": String(bodyData.length)
expectedResponse.HTTPBody = bodyData



Any requests that not stubbed will result in a fatal error.


Velociraptor is released under the MIT license. See the LICENSE file for details.

Latest podspec

    "name": "Velociraptor",
    "version": "0.0.2",
    "summary": "A network stubbing framework written in pure Swift for iOS and OS X.",
    "description": "Velociraptor is a network stubbing framework written in pure Swift for iOS and OS X.",
    "homepage": "",
    "license": {
        "type": "MIT",
        "file": "LICENSE"
    "authors": "mrahmiao",
    "platforms": {
        "ios": "8.0",
        "osx": "10.10"
    "source": {
        "git": "",
        "tag": "0.0.2"
    "source_files": [
    "requires_arc": true

Pin It on Pinterest

Share This