Ruby

这份入门指南能够帮助你通过Ruby开始使用Pact。更多详情或高级话题，可移步至Ruby Pact在GitHub上的代码库。

入门指南

这个workshop可以带你从头到尾完成一个例子，涉及Pact支持的大部分概念。大约需要2小时完成。

安装

在应用的Gemfile里面增加这一行：

  1. gem 'pact'

然后执行：

  1. $ bundle

或者这样自己安装：

  1. $ gem install pact

使用方法——一个示例场景

我们打算用Pact测试在消费者Zoo App和提供者Animal Service之间写一个集成测试。在消费者项目中，我们打算使用一个模型（Alligator类）来表示从Animal Service返回的数据，以及一个客户端（AnimalServiceClient）来负责向Animal Service发起HTTP请求。

Example

在Zoo App（消费者）项目中

1. 从模型类开始

设想有一个类似这样的模型类。Alligator的属性依赖于远程服务，需要通过向Animal Service发送HTTP请求才能获取到。

  1. class Alligator
  2.   attr_reader :name
  4.   def initialize name
  5.     @name = name
  6.   end
  8.   def == other
  9.     other.is_a?(Alligator) && other.name == name
  10.   end
  11. end

2. 创建Animal Service客户端类的骨架

设想有一个类似这样的Animal Service客户端类。

  1. require 'httparty'
  3. class AnimalServiceClient
  4.   include HTTParty
  5.   base_uri 'http://animal-service.com'
  7.   def get_alligator
  8.     # Yet to be implemented because we're doing Test First Development...
  9.   end
  10. end

3. 配置Animal Service的模拟服务

以下代码将在localhost:1234端口上创建一个模拟服务，用于对应用的HTTP查询请求作出响应，正如真实的“Animal Service”应用一样。这里还创建了一个模拟的服务提供者对象，用于设置期望值。用于访问模拟服务提供者的方法名你可以通过服务参数任意指定——在本例中为“animal_service”。`

  1. # In /spec/service_providers/pact_helper.rb
  3. require 'pact/consumer/rspec'
  4. # or require 'pact/consumer/minitest' if you are using Minitest
  6. Pact.service_consumer "Zoo App" do
  7.   has_pact_with "Animal Service" do
  8.     mock_service :animal_service do
  9.       port 1234
  10.     end
  11.   end
  12. end

4. 给Animal Service客户端写一个失败的测试用例

  1. # In /spec/service_providers/animal_service_client_spec.rb
  3. # When using RSpec, use the metadata `:pact => true` to include all the pact functionality in your spec.
  4. # When using Minitest, include Pact::Consumer::Minitest in your spec.
  6. describe AnimalServiceClient, :pact => true do
  8.   before do
  9.     # Configure your client to point to the stub service on localhost using the port you have specified
  10.     AnimalServiceClient.base_uri 'localhost:1234'
  11.   end
  13.   subject { AnimalServiceClient.new }
  15.   describe "get_alligator" do
  17.     before do
  18.       animal_service.given("an alligator exists").
  19.         upon_receiving("a request for an alligator").
  20.         with(method: :get, path: '/alligator', query: '').
  21.         will_respond_with(
  22.           status: 200,
  23.           headers: {'Content-Type' => 'application/json'},
  24.           body: {name: 'Betty'} )
  25.     end
  27.     it "returns a alligator" do
  28.       expect(subject.get_alligator).to eq(Alligator.new('Betty'))
  29.     end
  30.   end
  31. end

5. 执行测试用例

执行AnimalServiceClient用例，将会在配置好的pact文件夹（默认为spec/pacts）下生成一个pact文件。日志将输出在一个配置好的日志文件夹（默认为log）下，用于诊断问题。

当然，以上用例将会失败，因为Animal Service的客户端方法还没有实现，那么下一步，来实现提供者的客户端代码吧。

6. 实现Animal Service的消费者客户端方法

  1. class AnimalServiceClient
  2.   include HTTParty
  3.   base_uri 'http://animal-service.com'
  5.   def get_alligator
  6.     name = JSON.parse(self.class.get("/alligator").body)['name']
  7.     Alligator.new(name)
  8.   end
  9. end

7. 再次运行该用例

测试通过！现在你会得到一个pact文件，它可用于在Animal Service提供者的项目中验证期望。

现在，对于其他可能的返回状态码重复上述步骤。例如，考虑以下场景中你的客户端需要如何响应：

  • 404（返回null，还是抛出错误？）
  • 500（具体说明响应体中所包含的错误信息，并确保客户端日志记录下了这些错误信息，这样当出现问题时会省很多事）
  • 校验授权时是否需要返回401/403。

在Animal Service（提供者）项目中

1. 创建API相关类的骨架

使用你所选择的框架创建API类（Pact的作者更喜欢使用Webmachine和Roar）——先不用实现方法，我们要先写测试，后写实现，还记得吧？

2. 告诉提供者需要遵守之前的pact文件中的规约

在Rakefile中引入pact/tasks。

  1. # In Rakefile
  2. require 'pact/tasks'

在服务提供者项目中创建名为pact_helper.rb的文件。推荐放在spec/service_consumers/pact_helper.rb下。

更多信息，查看配置文档中的 验证契约和提供者章节。

  1. # In specs/service_consumers/pact_helper.rb
  3. require 'pact/provider/rspec'
  5. Pact.service_provider "Animal Service" do
  7.   honours_pact_with 'Zoo App' do
  9.     # This example points to a local file, however, on a real project with a continuous
  10.     # integration box, you would use a [Pact Broker](https://github.com/bethesque/pact_broker) or publish your pacts as artifacts,
  11.     # and point the pact_uri to the pact published by the last successful build.
  13.     pact_uri '../zoo-app/specs/pacts/zoo_app-animal_service.json'
  14.   end
  15. end

3. 运行失败的测试

  1. $ rake pact:verify

恭喜你！现在你有一个失败的测试需要通过了。

在这一阶段，你可能会希望在每实现一个特性之后可以只运行众多用例中的某一个。在pact:verify的失败输出结果的底部，你可以看到用于重新独立运行每条失败的请求的命令。只运行一条请求的命令类似这样：

  1. $ rake pact:verify PACT_DESCRIPTION="a request for an alligator" PACT_PROVIDER_STATE="an alligator exists"

4. 实现代码让你的第一个测试用例通过

然后重复上述步骤。

5. 继续直到所有测试通过

耶！你的Animal Service现在已经可以遵守与你的Zoo App消费者之间的契约了。现在你就有把握让你的消费者和提供者能够一起很好地工作了。

使用提供者状态

契约中的各个交互应该是在互相隔离状态下进行验证的，不得持有前一个交互中的上下文。那么怎样测试那些依赖于在提供者端已存在的数据的请求呢？请在这里查看关于提供者状态的介绍。