A Swift / ObjeciveC DSL for creating pacts.
Swift Objective-C Shell Groovy Ruby
Clone or download
andrewspinks Merge pull request #40 from surpher/master
Updates README to encourage usage of pact-ruby-standalone
Latest commit 58387dd May 18, 2018
Permalink
Failed to load latest commit information.
PactConsumerObjCTests Adds support for macOS and tvOS targets using Carthage and SwiftPM (#32) Oct 2, 2017
PactConsumerSwift.xcodeproj Adds support for macOS and tvOS targets using Carthage and SwiftPM (#32) Oct 2, 2017
Sources wait on verify to complete before allowing tests to continue to preve… Apr 24, 2018
Tests Adds support for macOS and tvOS targets using Carthage and SwiftPM (#32) Oct 2, 2017
certificates update build certificate. Oct 10, 2015
scripts Removed reference to non-standalone pact mock service May 18, 2018
.codecov.yml Adds support for macOS and tvOS targets using Carthage and SwiftPM (#32) Oct 2, 2017
.gitignore Update release script to work better with cocoa pods May 8, 2018
.ruby-version Update gems May 8, 2018
.swift-version Adds support for macOS and tvOS targets using Carthage and SwiftPM (#32) Oct 2, 2017
.swiftlint.yml Adds support for macOS and tvOS targets using Carthage and SwiftPM (#32) Oct 2, 2017
.travis.yml move to brew update Jan 5, 2018
Brewfile Create Brewfile Jan 4, 2018
CHANGELOG.md update changelog for release 0.5.2 May 8, 2018
CONTRIBUTING.md Updates documentation Oct 3, 2017
Cartfile Update BrightFutures Apr 25, 2018
Cartfile.resolved Adds support for macOS and tvOS targets using Carthage and SwiftPM (#32) Oct 2, 2017
Gemfile Build script improvements Oct 3, 2017
Gemfile.lock Update gems May 8, 2018
LICENSE Add license Jul 1, 2015
Package.resolved Adds support for macOS and tvOS targets using Carthage and SwiftPM (#32) Oct 2, 2017
Package.swift Adds support for macOS and tvOS targets using Carthage and SwiftPM (#32) Oct 2, 2017
PactConsumerSwift.podspec bump cocoapods version to 0.5.2 May 8, 2018
README.md Removed reference to non-standalone pact mock service May 18, 2018
release.groovy Update release script to work better with cocoa pods May 8, 2018

README.md

Pact Consumer Swift

Build Status Codecov Carthage compatible Swift Package Manager Swift Badge w/ CocoaPod Version Badge w/ Supported Platforms License: MIT Twitter

This library provides a Swift / Objective C DSL for creating Consumer Pacts. It provides support for Consumer Driven Contract Testing between dependent systems where the integration is based on HTTP (or message queues for some of the implementations).

But why? To test communication boundaries between your app and services.
You can view a presentation on how Pact can work in a mobile context here: Yow! Connected 2016 Andrew Spinks - Increasing The Confidence In Your Service Integrations.

Implements Pact Specification v2, including flexible matching.

This DSL relies on the Ruby pact-mock_service gem to provide the mock service for the tests.

Installation

Note: see Upgrading for notes on upgrading from 0.2 to 0.3

Install Pact Mock Service

Install the pact-ruby-standalone as per installation instructions.

Xcode Setup

In Xcode, edit your scheme and add pre- and post-actions to Test to start and stop pact-mock-service. Make sure you select your target in Provide build settings from the drop down menu.

# Pre-actions
PATH=/path/to/your/standalone/pact/bin:$PATH
pact-mock-service start --pact-specification-version 2.0.0 --log "${SRCROOT}/tmp/pact.log" --pact-dir "${SRCROOT}/tmp/pacts" -p 1234

# Post-actions
PATH=/path/to/your/standalone/pact/bin:$PATH
pact-mock-service stop

Note: your generated Pact files will be dropped into "${SRCROOT}/tmp/pacts" folder.

Xcode Scheme Test Pre-actions

Add the PactConsumerSwift library to your project

Using Carthage

  • See the PactSwiftExample Swift, Carthage Example - Build Status for an example project using pact-consumer-swift with Carthage for an iOS target.
  • See the PactMacOSExample Build Status for an example project using pact-consumer-swift through Carthage for a macOS target.

Using CocoaPods

  • See the PactObjectiveCExample Build Status for an example project using pact-consumer-swift with CocoaPods for an iOS target.

Using Swift Package Manager

  • See the PactSwiftPMExample Build Status for an example project using pact-consumer-swift library through Swift Package Manager for an executable that runs in terminal.

Writing Pact Tests

Testing with Swift

Write a Unit test similar to the following (NB: this example is using the Quick test framework)

import PactConsumerSwift

...
  beforeEach {
    animalMockService = MockService(provider: "Animal Service", consumer: "Animal Consumer Swift")
    animalServiceClient = AnimalServiceClient(baseUrl: animalMockService!.baseUrl)
  }

  it("gets an alligator") {
    animalMockService!.given("an alligator exists")
                      .uponReceiving("a request for an alligator")
                      .withRequest(method:.GET, path: "/alligator")
                      .willRespondWith(status:200,
                                       headers: ["Content-Type": "application/json"],
                                       body: ["name": "Mary"])

    //Run the tests
    animalMockService!.run { (testComplete) -> Void in
      animalServiceClient!.getAlligator { (alligator) in
        expect(alligator.name).to(equal("Mary"))
        testComplete()
      }
    }
  }

An optional timeout (seconds) parameter can be included on the run function. This defaults to 30 seconds.

...
    animalMockService!.run(timeout: 60) { (testComplete) -> Void in
      animalServiceClient!.getAlligator { (alligator) in
        expect(alligator.name).to(equal("Mary"))
        testComplete()
      }
    }

Testing with Objective-C

Write a Unit test similar to the following

@import PactConsumerSwift;
...
- (void)setUp {
  [super setUp];
  self.animalMockService = [[MockService alloc] initWithProvider:@"Animal Provider"
                                                        consumer:@"Animal Service Client Objective-C"];
  self.animalServiceClient = [[OCAnimalServiceClient alloc] initWithBaseUrl:self.animalMockService.baseUrl];
}

- (void)testGetAlligator {
  typedef void (^CompleteBlock)();

  [[[[self.animalMockService given:@"an alligator exists"]
                             uponReceiving:@"oc a request for an alligator"]
                             withRequestHTTPMethod:PactHTTPMethodGET
                                              path:@"/alligator"
                                             query:nil headers:nil body:nil]
                             willRespondWithHTTPStatus:200
                                               headers:@{@"Content-Type": @"application/json"}
                                                  body: @"{ \"name\": \"Mary\"}" ];

  [self.animalMockService run:^(CompleteBlock testComplete) {
      Animal *animal = [self.animalServiceClient getAlligator];
      XCTAssertEqualObjects(animal.name, @"Mary");
      testComplete();
  }];
}

An optional timeout (seconds) parameter can be included on the run function. This defaults to 30 seconds.

...
  [self.animalMockService run:^(CompleteBlock testComplete) {
      Animal *animal = [self.animalServiceClient getAlligator];
      XCTAssertEqualObjects(animal.name, @"Mary");
      testComplete();
  } timeout:60];
}

Testing with XCTest

Write a Unit Test similar to the following:

import PactConsumerSwift
...
  var animalMockService: MockService?
  var animalServiceClient: AnimalServiceClient?

  override func setUp() {
    super.setUp()

    animalMockService = MockService(provider: "Animal Provider", consumer: "Animal Service Client")
    animalServiceClient = AnimalServiceClient(baseUrl: animalMockService!.baseUrl)
  }

  func testItGetsAlligator() {
    // Prepare the expecated behaviour using pact's MockService
    animalMockService!
      .given("an alligator exists")
      .uponReceiving("a request for alligator")
      .withRequest(method: .GET, path: "/alligator")
      .willRespondWith(status: 200,
                       headers: ["Content-Type": "application/json"],
                       body: [ "name": "Mary" ])

    // Run the test
    animalMockService!.run(timeout: 60) { (testComplete) -> Void in
      self.animalServiceClient!.getAlligator { (response) -> in
        XCTAssertEqual(response.name, "Mary")
        testComplete()
      }
    }
  }
  ...

An optional timeout (seconds) parameter can be included on the run function. Defaults to 30 seconds.

...
    // Run the test
    animalMockService!.run(timeout: 60) { (testComplete) -> Void in
      self.animalServiceClient!.getAlligator { (response) -> in
        XCTAssertEqual(response.name, "Mary")
        testComplete()
      }
    }

Matching

In addition to verbatim value matching, you have 3 useful matching functions in the Matcher class that can increase expressiveness and reduce brittle test cases.

  • Matcher.term(matcher, generate) - tells Pact that the value should match using a given regular expression, using generate in mock responses. generate must be a string.
  • Matcher.somethingLike(content) - tells Pact that the value itself is not important, as long as the element type (valid JSON number, string, object etc.) itself matches.
  • Matcher.eachLike(content, min) - tells Pact that the value should be an array type, consisting of elements like those passed in. min must be >= 1. content may be a valid JSON value: e.g. strings, numbers and objects.

NOTE: One caveat to note, is that you will need to use valid Ruby regular expressions and double escape backslashes.

See the PactSpecs.swift, PactObjectiveCTests.m for examples on how to expect error responses, how to use query params, and Matchers.

For more on request / response matching, see Matching.

Using in you CI

Xcode's pre-actions and post-actions do not honour non-zero script exits and therefore would not fail your build if publishing to a Pact Broker would fail. If you would like to upload your Pact files to a Pact Broker as part of your CI, we would suggest that you create a separate step in your CI workflow with that responsibility.

See pact-ruby-standalone page for installation instructions and how to use pact-broker client.

Verifying your client against the service you are integrating with

If your setup is correct and your tests run against the pack mock server, then you should see a log file here: $YOUR_PROJECT/tmp/pact.log And the generated pacts here: $YOUR_PROJECT/tmp/pacts/...

Publish your generated pact file(s) to your Pact Broker or a Hosted Pact Broker so your API provider can always retrieve them from one location, even when pacts change. Or even just by simply sending the pact file to your API provider devs so they can used them in their tests of their API responses. See Verifying pacts for more information. For an end-to-end example with a ruby back end service, have a look at the KatKit example.

Also, check out this article on using a dockerized Node.js service that uses provider states.

More reading

  • The Pact website Pact
  • The pact mock server that the Swift library uses under the hood Pact mock service
  • A pact broker for managing the generated pact files (so you don't have to manually copy them around!) Pact broker

Contributing

Please read CONTRIBUTING.md