企业官网建设流程全解析

• 测试
• 开发工具

导读

在 RSpec 测试中，HTTP 请求往往是不稳定、不可控的外部依赖。VCR 提供了开箱即用的 RSpec metadata 集成方案：只需在VCR.configure中调用一次configure_rspec_metadata!，即可通过给 example group 或 example 打上:vcr标签自动插入/弹出 cassette，实现 HTTP 交互的录制与回放，让测试快速、确定且准确。读完本文，你将掌握 metadata 模式的完整配置、cassette 自动命名规则、通过字符串/哈希覆盖选项的两种写法，以及allow_unused_http_interactions的失败断言行为与源码级实现原理。

1. 快速上手：在 spec_helper 中开启 metadata 集成

VCR 与 RSpec 的 metadata 集成由configure_rspec_metadata!开启，其源码位于 lib/vcr/configuration.rb，内部通过幂等标记@rspec_metadata_configured确保只注册一次钩子，随后调用VCR::RSpec::Metadata.configure!。

一个完整的spec/spec_helper.rb配置如下：

require 'vcr' VCR.configure do |c| c.cassette_library_dir = 'spec/cassettes' c.hook_into :webmock c.configure_rspec_metadata! end RSpec.configure do |c| # so we can use `:vcr` rather than `vcr: true`; # in RSpec 3 this will no longer be necessary. c.treat_symbols_as_metadata_keys_with_true_values = true end

配置要点说明：

• cassette_library_dir：指定 cassette 文件的存储目录，此处为spec/cassettes；
• hook_into :webmock：将 VCR 挂载到 WebMock 上拦截 HTTP 请求（也可以选择 excon、faraday、typhoeus 等库，详见 lib/vcr/library_hooks 目录）；
• configure_rspec_metadata!：核心开关，向 RSpec 注册before(:each)/after(:each)钩子；
• treat_symbols_as_metadata_keys_with_true_values：允许把:vcr直接当作vcr: true使用，这是 RSpec 2 时代的老配置，注释明确说明在 RSpec 3 中不再需要。

1.1 预置的 cassette 示例

若已有先前录制好的 cassette 文件spec/cassettes/Group/optionally_raises_an_error.yml，其内容结构如下：

--- http_interactions: - request: method: get uri: http://example.com/foo body: encoding: UTF-8 string: "" headers: {} response: status: code: 200 message: OK headers: Content-Length: - "5" body: encoding: UTF-8 string: Hello http_version: "1.1" recorded_at: Tue, 01 Nov 2011 04:58:44 GMT recorded_with: VCR 2.0.0

该结构展示了 VCR 序列化交互的字段布局：http_interactions列表中的每个条目包含request（method、uri、body、headers）与response（status、headers、body、http_version）两大部分，外加recorded_at时间戳与recorded_with版本标记。这个示例在后续验证allow_unused_http_interactions断言时会作为"未被使用的历史交互"出现。

2. 三种使用姿势：:vcr、字符串与哈希

开启 metadata 集成后，example group 或单个 example 可以通过三种方式声明使用 VCR：

其分支解析逻辑位于 lib/vcr/test_frameworks/rspec.rb：哈希类型会dup一份副本再从中提取cassette_name，字符串类型直接作为 cassette 名，其余（:vcr或vcr: true）则使用空选项哈希，最终通过VCR.insert_cassette(cassette_name, options)插入 cassette。

2.1 完整示例：group 级与 example 级 metadata

以下 spec 文件综合演示了三种姿势及嵌套 example group 的行为：

$server = start_sinatra_app do get('/') { "Hello" } end def make_http_request Net::HTTP.get_response('localhost', '/', $server.port).body end require 'spec_helper' describe "VCR example group metadata", :vcr do it 'records an http request' do expect(make_http_request).to eq('Hello') end it 'records another http request' do expect(make_http_request).to eq('Hello') end it 'records an http request with a custom file name', vcr: 'my_cassette' do expect(make_http_request).to eql('Hello') end context 'in a nested example group' do it 'records another one' do expect(make_http_request).to eq('Hello') end end end describe "VCR example metadata" do it 'records an http request', :vcr do expect(make_http_request).to eq('Hello') end end

运行rspec spec/vcr_example_spec.rb后，测试以5 examples, 0 failures通过，并生成以下 cassette 文件：

• spec/cassettes/VCR_example_group_metadata/records_an_http_request.yml
• spec/cassettes/VCR_example_group_metadata/records_another_http_request.yml
• spec/cassettes/my_cassette.yml（由vcr: 'my_cassette'强制命名，无 group 前缀）
• spec/cassettes/VCR_example_group_metadata/in_a_nested_example_group/records_another_one.yml（嵌套 context 继续拼接路径）
• spec/cassettes/VCR_example_metadata/records_an_http_request.yml（example 级 metadata 单独成组）

2.2 自动命名规则的源码原理

cassette 的自动命名由VCR::RSpec::Metadata.vcr_cassette_name_for递归完成，见 lib/vcr/test_frameworks/rspec.rb。其算法要点：

• 取metadata[:description]作为当前层名称；若描述为空（如it { is_expected.to ... }单行块），则回退到metadata[:scoped_id]保证名称唯一；
• 通过metadata[:example_group]（或回退的parent_example_group）递归向上拼接父级名称，各层之间用/连接，最终形成Group/SubGroup/example_description的层级路径；
• 该层级结构与cassette_library_dir拼接后即得到磁盘上的实际文件路径。

因此"基于 example 完整描述自动命名"实际上是一个随嵌套深度逐层累加的描述拼接过程，这正是上文第 4、5 个 cassette 文件产生目录嵌套的原因。

3. 通过哈希覆盖 cassette 选项

当需要覆盖名称以外的选项（如录音模式record）时，使用哈希形式。注意哈希中的cassette_name键与字符串形式的优先级一致，且会被options.delete弹出，不参与后续insert_cassette的选项合并：

require 'spec_helper' vcr_options = { cassette_name: "example", record: :new_episodes } describe "Using an options hash", vcr: vcr_options do it 'uses the provided cassette name' do expect(VCR.current_cassette.name).to eq("example") end it 'sets the given options' do expect(VCR.current_cassette.record_mode).to eq(:new_episodes) end end

运行rspec spec/vcr_example_spec.rb后以2 examples, 0 failures通过。这里通过VCR.current_cassette断言了 cassette 的名称与record_mode，直观证明哈希中的每一项都真实作用于当前 cassette。

可传入的选项与insert_cassette完全一致，常见包括：record（:once、:new_episodes、:none、:all、:record_on_error）、match_requests_on、allow_playback_repeats、allow_unused_http_interactions、serialize_with、persist_with等（完整文档化选项见 lib/vcr.rb）。所有选项都会先与default_cassette_options合并，见 lib/vcr/cassette.rb。

4.allow_unused_http_interactions: false：严格校验每个交互都被消费

VCR 默认允许 cassette 中存在未被使用的历史交互。若希望严格约束——即 cassette 弹出（eject）时，所有预录交互都已被请求消费，否则直接报错——可在哈希中传入allow_unused_http_interactions: false。

4.1 场景一：未使用的交互导致失败

使用上一节预置的spec/cassettes/Group/optionally_raises_an_error.yml（内含一个对http://example.com/foo的 GET 交互），编写如下 spec：

require 'spec_helper' describe "Group", vcr: { allow_unused_http_interactions: false } do it 'optionally raises an error' do # don't fail end end

运行rspec spec/vcr_example_spec.rb，测试将以类似如下错误失败：

There are unused HTTP interactions left in the cassette: - [get http://example.com/foo] => [200 "Hello"]

4.2 场景二：example 已失败时不追加断言

若 example 自身已经抛错，VCR 不会再用"未使用交互"的断言去掩盖原始错误：

require 'spec_helper' describe "Group", vcr: { allow_unused_http_interactions: false } do it 'optionally raises an error' do raise "boom" end end

运行后测试以"boom"失败，且输出中不包含"There are unused HTTP interactions"。

4.3 源码实现：$!变量与断言跳过

该行为在 lib/vcr/cassette.rb 的eject中触发，核心判断位于：

def should_assert_no_unused_interactions? !(@allow_unused_http_interactions || $!) end

（见 lib/vcr/cassette.rb）

关键点有二：

1. 默认值：allow_unused_http_interactions默认为true（配置于 lib/vcr/configuration.rb），因此默认不执行该断言，只有显式传false才启用；
2. $!保护：Ruby 全局变量$!保存当前异常。当 example 抛出异常时，$!非 nil，即使allow_unused_http_interactions: false，断言也会被跳过，从而保留原始错误信息（官方注释称之为"几乎肯定更有趣/更重要"的错误，见 lib/vcr.rb）。

4.4 断言在弹出阶段的触发链路

在 RSpec 集成层，after(:each)钩子调用VCR.eject_cassette(skip_no_unused_interactions_assertion: !!example.exception)（见 lib/vcr/test_frameworks/rspec.rb）。注意此处已通过example.exception提前判断 example 是否失败并显式跳过断言——这是 RSpec 集成层的第二道"失败保护"；而Cassette#eject内部的$!判断则是更底层的兜底机制，两者共同保证失败时原始错误优先、不被 unused-interactions 错误覆盖。

5. 完整行为验证：Cucumber 场景

上述全部行为均有对应的端到端验证场景，见 features/test_frameworks/rspec_metadata.feature，其覆盖了四类场景：

• Use:vcrmetadata：验证 group/example 级:vcr、字符串自定义名称、嵌套 context 的 cassette 生成路径；
• allow_unused_http_interactions: falsecauses a failure if there are unused interactions：验证未消费交互时的报错文案；
• allow_unused_http_interactions: falsedoes not raise if the example already failed：验证失败时断言被跳过；
• Pass a hash to set the cassette options：验证哈希选项（cassette_name、record）真实生效。

同时 docs/test_frameworks/rspec_metadata.md 作为面向用户的文档版本，与 feature 文件内容一一对应，可作为阅读与调试的参考。

6. 注意事项与最佳实践

• metadata 键的语义：:vcr会被解析为vcr: true，哈希与字符串两种形式优先于自动命名；字符串形式无法携带其他选项，需要组合选项时请改用哈希并放入cassette_name键；
• cassette 命名与 CI 稳定性：自动命名依赖 example 描述文本，重构描述字符串会导致 cassette 文件路径变化，必要时用显式cassette_name固定文件名；
• 严格校验的取舍：allow_unused_http_interactions: false适合"每个预录交互都必须被消费"的严格回归场景，但它会因任何未消费的预录交互而失败，首次接入存量 cassette 时需注意清理无用交互（可配合 drop_unused_requests 相关能力）；
• RSpec 版本前提：treat_symbols_as_metadata_keys_with_true_values仅 RSpec 2 需要，RSpec 3 中符号 metadata 天然为真，可省略该行（仓库文档明确注明）。

• 测试
• 开发工具