pacto 0.3.1 → 0.4.0.rc1

data/samples/consumer.rb

@@ -0,0 +1,15 @@
+# -*- encoding : utf-8 -*-
+require 'pacto'
+Pacto.load_contracts 'contracts', 'http://localhost:5000'
+WebMock.allow_net_connect!
+
+interactions = Pacto.simulate_consumer :my_client do
+  request 'Ping'
+  request 'Echo', body: ->(body) { body.reverse },
+                  headers: (proc do |headers|
+                    headers['Content-Type'] = 'text/json'
+                    headers['Accept'] = 'none'
+                    headers
+                  end)
+end
+puts interactions

data/samples/contracts/README.md

@@ -0,0 +1 @@
+This folder contains sample contracts.

data/samples/contracts/contract.js

@@ -0,0 +1,93 @@
+// Pacto Contracts describe the constraints we want to put on interactions between a consumer and a provider.  It sets some expectations about the headers expected for both the request and response, the expected response status code.  It also uses [json-schema](http://json-schema.org/) to define the allowable request body (if one should exist) and response body.
+{
+  // The Request section comes first.  In this case, we're just describing a simple get request that does not require any parameters or a request body.
+  "request": {
+    "headers": {
+      // A request must exactly match these headers for Pacto to believe the request matches the contract, unless `Pacto.configuration.strict_matchers` is false.
+      "Accept": "application/vnd.github.beta+json",
+      "Accept-Encoding": "gzip;q=1.0,deflate;q=0.6,identity;q=0.3"
+    },
+    // The `method` and `path` are required.  The `path` may be an [rfc6570 URI template](http://tools.ietf.org/html/rfc6570) for more flexible matching.
+    "method": "get",
+    "path": "/repos/thoughtworks/pacto/readme"
+  },
+  "response": {
+    "headers": {
+      "Content-Type": "application/json; charset=utf-8",
+      "Status": "200 OK",
+      "Cache-Control": "public, max-age=60, s-maxage=60",
+      "Etag": "\"fc8e78b0a9694de66d47317768b20820\"",
+      "Vary": "Accept, Accept-Encoding",
+      "Access-Control-Allow-Credentials": "true",
+      "Access-Control-Expose-Headers": "ETag, Link, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval",
+      "Access-Control-Allow-Origin": "*"
+    },
+    "status": 200,
+    "body": {
+      "$schema": "http://json-schema.org/draft-03/schema#",
+      "description": "Generated from https://api.github.com/repos/thoughtworks/pacto/readme with shasum 3ae59164c6d9f84c0a81f21fb63e17b3b8ce6894",
+      "type": "object",
+      "required": true,
+      "properties": {
+        "name": {
+          "type": "string",
+          "required": true
+        },
+        "path": {
+          "type": "string",
+          "required": true
+        },
+        "sha": {
+          "type": "string",
+          "required": true
+        },
+        "size": {
+          "type": "integer",
+          "required": true
+        },
+        "url": {
+          "type": "string",
+          "required": true
+        },
+        "html_url": {
+          "type": "string",
+          "required": true
+        },
+        "git_url": {
+          "type": "string",
+          "required": true
+        },
+        "type": {
+          "type": "string",
+          "required": true
+        },
+        "content": {
+          "type": "string",
+          "required": true
+        },
+        "encoding": {
+          "type": "string",
+          "required": true
+        },
+        "_links": {
+          "type": "object",
+          "required": true,
+          "properties": {
+            "self": {
+              "type": "string",
+              "required": true
+            },
+            "git": {
+              "type": "string",
+              "required": true
+            },
+            "html": {
+              "type": "string",
+              "required": true
+            }
+          }
+        }
+      }
+    }
+  }
+}

data/samples/contracts/get_album_cover.json

@@ -0,0 +1,48 @@
+{
+  "request": {
+    "headers": {
+    },
+    "http_method": "get",
+    "path": "/api/album/{id}/cover"
+  },
+  "response": {
+    "headers": {
+      "Content-Type": "application/json"
+    },
+    "status": 200,
+    "schema": {
+      "$schema": "http://json-schema.org/draft-03/schema#",
+      "description": "Generated from http://localhost:5000/api/album/1/cover with shasum db640385d2b346db760dbfd78058101663197bcf",
+      "type": "object",
+      "required": true,
+      "properties": {
+        "cover": {
+          "type": "string",
+          "required": true
+        }
+      }
+    }
+  },
+  "examples": {
+    "default": {
+      "request": {
+        "method": "get",
+        "uri": "http://localhost:5000/api/album/1/cover",
+        "headers": {
+          "User-Agent": "Faraday v0.9.0",
+          "Accept-Encoding": "gzip;q=1.0,deflate;q=0.6,identity;q=0.3",
+          "Accept": "*/*"
+        }
+      },
+      "response": {
+        "status": 200,
+        "headers": {
+          "Content-Type": "application/json",
+          "Content-Length": "17"
+        },
+        "body": "{\"cover\":\"image\"}"
+      }
+    }
+  },
+  "name": "Get Album Cover"
+}

data/samples/contracts/localhost/api/echo.json

@@ -0,0 +1,37 @@
+{
+  "name": "Echo",
+  "request": {
+    "headers": {
+      "Content-Type": "text/plain"
+    },
+    "http_method": "post",
+    "path": "/api/echo",
+    "schema": {
+      "$schema": "http://json-schema.org/draft-03/schema#",
+      "oneOf": [
+        { "type": "string", "required": true },
+        { "type": "object", "required": true }
+      ]
+    }
+  },
+  "response": {
+    "status": 201,
+    "schema": {
+      "$schema": "http://json-schema.org/draft-03/schema#",
+      "oneOf": [
+        { "type": "string", "required": true },
+        { "type": "object", "required": true }
+      ]
+    }
+  },
+  "examples": {
+    "foo": {
+      "request": {
+        "body": "foo"
+      },
+      "response": {
+        "body": "foo"
+      }
+    }
+  }
+}

data/samples/contracts/localhost/api/ping.json

@@ -0,0 +1,38 @@
+{
+  "name": "Ping",
+  "request": {
+    "headers": {
+    },
+    "http_method": "get",
+    "path": "/api/ping"
+  },
+  "response": {
+    "headers": {
+      "Content-Type": "application/json"
+    },
+    "status": 200,
+    "schema": {
+      "$schema": "http://json-schema.org/draft-03/schema#",
+      "description": "Generated from http://localhost:9292/api/ping with shasum 2cf3478c18e3ce877fb823ed435cb75b4a801aaa",
+      "type": "object",
+      "required": true,
+      "properties": {
+        "ping": {
+          "type": "string",
+          "required": true
+        }
+      }
+    }
+  },
+  "examples": {
+    "default": {
+      "request": {
+      },
+      "response": {
+        "body": {
+          "ping": "pong - from the example!"
+        }
+      }
+    }
+  }
+}

data/samples/cops.rb

@@ -0,0 +1,30 @@
+# -*- encoding : utf-8 -*-
+require 'pacto'
+Pacto.configure do |c|
+  c.contracts_path = 'contracts'
+end
+Pacto.validate!
+
+# You can create a custom cop that investigates the request/response and sees if it complies with a
+# contract. The cop should return a list of citations if it finds any problems.
+class MyCustomCop
+  def investigate(_request, _response, contract)
+    citations = []
+    citations << 'Contract must have a request schema' if contract.request.schema.empty?
+    citations << 'Contract must have a response schema' if contract.response.schema.empty?
+    citations
+  end
+end
+
+Pacto::Cops.active_cops << MyCustomCop.new
+
+contracts = Pacto.load_contracts('contracts', 'http://localhost:5000')
+contracts.stub_providers
+puts contracts.simulate_consumers
+
+# Or you can completely replace the default set of validators
+Pacto::Cops.registered_cops.clear
+Pacto::Cops.register_cop Pacto::Cops::ResponseBodyCop
+
+contracts = Pacto.load_contracts('contracts', 'http://localhost:5000')
+puts contracts.simulate_consumers

data/samples/forensics.rb

@@ -0,0 +1,54 @@
+# -*- encoding : utf-8 -*-
+# Pacto has a few RSpec matchers to help you ensure a **consumer** and **producer** are
+# interacting properly. First, let's setup the rspec suite.
+require 'rspec/autorun' # Not generally needed
+require 'pacto/rspec'
+WebMock.allow_net_connect!
+Pacto.validate!
+Pacto.load_contracts('contracts', 'http://localhost:5000').stub_providers
+
+# It's usually a good idea to reset Pacto between each scenario. `Pacto.reset` just clears the
+# data and metrics about which services were called. `Pacto.clear!` also resets all configuration
+# and plugins.
+RSpec.configure do |c|
+  c.after(:each)  { Pacto.reset }
+end
+
+# Pacto provides some RSpec matchers related to contract testing, like making sure
+# Pacto didn't received any unrecognized requests (`have_unmatched_requests`) and that
+# the HTTP requests matched up with the terms of the contract (`have_failed_investigations`).
+describe Faraday do
+  let(:connection) { described_class.new(url: 'http://localhost:5000') }
+
+  it 'passes contract tests' do
+    connection.get '/api/ping'
+    expect(Pacto).to_not have_failed_investigations
+    expect(Pacto).to_not have_unmatched_requests
+  end
+end
+
+# There are also some matchers for collaboration testing, so you can make sure each scenario is
+# calling the expected services and sending the right type of data.
+describe Faraday do
+  let(:connection) { described_class.new(url: 'http://localhost:5000') }
+  before(:each) do
+    connection.get '/api/ping'
+
+    connection.post do |req|
+      req.url '/api/echo'
+      req.headers['Content-Type'] = 'application/json'
+      req.body = '{"foo": "bar"}'
+    end
+  end
+
+  it 'calls the ping service' do
+    expect(Pacto).to have_validated(:get, 'http://localhost:5000/api/ping').against_contract('Ping')
+  end
+
+  it 'sends data to the echo service' do
+    expect(Pacto).to have_investigated('Ping').with_response(body: hash_including('ping' => 'pong - from the example!'))
+    expect(Pacto).to have_investigated('Echo').with_request(body: hash_including('foo' => 'bar'))
+    echoed_body = { 'foo' => 'bar' }
+    expect(Pacto).to have_investigated('Echo').with_request(body: echoed_body).with_response(body: echoed_body)
+  end
+end

data/samples/generation.rb

@@ -0,0 +1,48 @@
+# -*- encoding : utf-8 -*-
+# Some generation related [configuration](configuration.rb).
+require 'pacto'
+WebMock.allow_net_connect!
+Pacto.configure do |c|
+  c.contracts_path = 'contracts'
+end
+WebMock.allow_net_connect!
+
+# Once we call `Pacto.generate!`, Pacto will record contracts for all requests it detects.
+Pacto.generate!
+
+# Now, if we run any code that makes an HTTP call (using an
+# [HTTP library supported by WebMock](https://github.com/bblimke/webmock#supported-http-libraries))
+# then Pacto will generate a Contract based on the HTTP request/response.
+#
+# This code snippet will generate a Contract and save it to `contracts/samples/contracts/localhost/api/ping.json`.
+require 'faraday'
+conn = Faraday.new(url: 'http://localhost:5000')
+response = conn.get '/api/ping'
+# We're getting back real data from GitHub, so this should be the actual file encoding.
+puts response.body
+
+# The generated contract will contain expectations based on the request/response we observed,
+# including a best-guess at an appropriate json-schema.  Our heuristics certainly aren't foolproof,
+# so you might want to customize schema!
+
+# Here's another sample that sends a post request.
+conn.post do |req|
+  req.url '/api/echo'
+  req.headers['Content-Type'] = 'application/json'
+  req.body = '{"red fish": "blue fish"}'
+end
+
+# You can provide hints to Pacto to help it generate contracts. For example, Pacto doesn't have
+# a good way to know a good name and correct URI template for the service. That means that Pacto
+# will not know if two similar requests are for the same service or two different services, and
+# will be forced to give names based on the URI that are not good display names.
+
+# The hint below tells Pacto that requests to http://localhost:5000/album/1/cover and http://localhost:5000/album/2/cover
+# are both going to the same service, which is known as "Get Album Cover". This hint will cause Pacto to
+# generate a Contract for "Get Album Cover" and save it to `contracts/get_album_cover.json`, rather than two
+# contracts that are stored at `contracts/localhost/album/1/cover.json` and `contracts/localhost/album/2/cover.json`.
+Pacto::Generator.configure do |c|
+  c.hint 'Get Album Cover', http_method: :get, host: 'http://localhost:5000', path: '/api/album/{id}/cover'
+end
+conn.get '/api/album/1/cover'
+conn.get '/api/album/2/cover'

data/samples/rake_tasks.sh

@@ -0,0 +1,7 @@
+# # Rake tasks
+
+# ## This is a test!
+# [That](www.google.com) markdown works
+bundle exec rake pacto:meta_validate['contracts']
+
+bundle exec rake pacto:validate['http://localhost:5000','contracts']

data/samples/rspec.rb

@@ -0,0 +1 @@
+# -*- encoding : utf-8 -*-

data/samples/samples.rb

@@ -0,0 +1,92 @@
+# -*- encoding : utf-8 -*-
+# # Overview
+# Welcome to the Pacto usage samples!
+# This document gives a quick overview of the main features.
+#
+# You can browse the Table of Contents (upper right corner) to view additional samples.
+#
+# In addition to this document, here are some highlighted samples:
+# <ul>
+#   <li><a href="configuration">Configuration</a>: Shows all available configuration options</li>
+#   <li><a href="generation">Generation</a>: More details on generation</li>
+#   <li><a href="rspec">RSpec</a>: More samples for RSpec expectations</li>
+# </ul>
+
+# You can also find other samples using the Table of Content (upper right corner), including sample contracts.
+
+# # Getting started
+# Once you've installed the Pacto gem, you just require it.  If you want, you can also require the Pacto rspec expectations.
+require 'pacto'
+require 'pacto/rspec'
+# Pacto will disable live connections, so you will get an error if
+# your code unexpectedly calls an service that was not stubbed.  If you
+# want to re-enable connections, run `WebMock.allow_net_connect!`
+WebMock.allow_net_connect!
+
+# Pacto can be configured via a block.  The `contracts_path` option tells Pacto where it should load or save contracts.  See the [Configuration](configuration.html) for all the available options.
+Pacto.configure do |c|
+  c.contracts_path = 'contracts'
+end
+
+# # Generating a Contract
+
+# Calling `Pacto.generate!` enables contract generation.
+# Pacto.generate!
+
+# Now, if we run any code that makes an HTTP call (using an
+# [HTTP library supported by WebMock](https://github.com/bblimke/webmock#supported-http-libraries))
+# then Pacto will generate a Contract based on the HTTP request/response.
+#
+# We're using the sample APIs in the sample_apis directory.
+require 'faraday'
+conn = Faraday.new(url: 'http://localhost:5000')
+response = conn.get '/api/ping'
+# This is the real request, so you should see {"ping":"pong"}
+puts response.body
+
+# # Testing providers by simulating consumers
+
+# The generated contract will contain expectations based on the request/response we observed,
+# including a best-guess at an appropriate json-schema.  Our heuristics certainly aren't foolproof,
+# so you might want to modify the output!
+
+# We can load the contract and validate it, by sending a new request and making sure
+# the response matches the JSON schema.  Obviously it will pass since we just recorded it,
+# but if the service has made a change, or if you alter the contract with new expectations,
+# then you will see a contract investigation message.
+contracts = Pacto.load_contracts('contracts', 'http://localhost:5000')
+contracts.simulate_consumers
+
+# # Stubbing providers for consumer testing
+# We can also use Pacto to stub the service based on the contract.
+contracts.stub_providers
+# The stubbed data won't be very realistic, the default behavior is to return the simplest data
+# that complies with the schema.  That basically means that you'll have "bar" for every string.
+response = conn.get '/api/ping'
+# You're now getting stubbed data.  You should see {"ping":"bar"} unless you recorded with
+# the `defaults` option enabled, in which case you will still seee {"ping":"pong"}.
+puts response.body
+
+# # Collaboration tests with RSpec
+
+# Pacto comes with rspec matchers
+require 'pacto/rspec'
+
+# It's probably a good idea to reset Pacto between each rspec scenario
+RSpec.configure do |c|
+  c.after(:each)  { Pacto.clear! }
+end
+
+# Load your contracts, and stub them if you'd like.
+Pacto.load_contracts('contracts', 'http://localhost:5000').stub_providers
+# You can turn on investigation mode so Pacto will detect and validate HTTP requests.
+Pacto.validate!
+
+describe 'my_code' do
+  it 'calls a service' do
+    conn = Faraday.new(url: 'http://localhost:5000')
+    response = conn.get '/api/ping'
+    # The have_validated matcher makes sure that Pacto received and successfully validated a request
+    expect(Pacto).to have_validated(:get, 'http://localhost:5000/api/ping')
+  end
+end