Testing External Services with RSpec, VCR, and WebMock in Ruby on Rails
For quick setup, just run:
rails app:template LOCATION='https://railsbytes.com/script/X8Bsyo'
👉 View template source
Introduction
When building Rails applications that integrate with external services, it's crucial to have reliable tests that don't depend on actual HTTP requests. This tutorial will show you how to use VCR and WebMock to record and replay HTTP interactions in your RSpec tests.
Setup
First, add these gems to your Gemfile:
group :test do
gem 'rspec-rails'
gem 'vcr'
gem 'webmock'
end
Run bundle install to install the gems.
Configuring VCR and WebMock
Create a new file at spec/support/vcr.rb:
require 'vcr'
require 'webmock/rspec'
# Disable all real HTTP connections, except to localhost
WebMock.disable_net_connect!(allow_localhost: true)
VCR.configure do |c|
# Where VCR will store the recorded HTTP interactions
c.cassette_library_dir = Rails.root.join('spec', 'cassettes')
# Ignore localhost requests
c.ignore_localhost = true
# Tell VCR to use WebMock
c.hook_into :webmock
# Allow VCR to be configured through RSpec metadata
c.configure_rspec_metadata!
# Allow real HTTP connections when no cassette is in use
c.allow_http_connections_when_no_cassette = true
# Configure how requests are matched
c.default_cassette_options = {
match_requests_on: [:method, :uri, :body]
}
# Filter sensitive data before recording
c.before_record do |interaction|
interaction.request.headers['Authorization'] = '[FILTERED]'
end
# Ignore specific hosts
ignored_hosts = ['codeclimate.com']
c.ignore_hosts *ignored_hosts
end
# Configure RSpec to use VCR
RSpec.configure do |config|
config.around(:each) do |example|
options = example.metadata[:vcr] || {}
options[:allow_playback_repeats] = true
if options[:record] == :skip
VCR.turned_off(&example)
else
custom_name = example.metadata[:vcr]&.delete(:cassette_name)
generated_name = example.metadata[:full_description]
.split(/\s+/, 2)
.join('/')
.underscore
.tr('.', '/')
.gsub(/[^\w\/]+/, '_')
.gsub(/\/$/, '')
name = custom_name || generated_name
VCR.use_cassette(name, options, &example)
end
end
end
Using VCR in Your Tests
Here are some examples of how to use VCR in your specs:
Basic Usage
# spec/services/weather_service_spec.rb
RSpec.describe WeatherService do
describe '#get_forecast' do
it 'fetches weather data from the API' do
service = WeatherService.new
forecast = service.get_forecast('London')
expect(forecast).to include('temperature')
end
end
end
Custom Cassette Names
RSpec.describe WeatherService do
describe '#get_forecast' do
it 'fetches weather data', vcr: { cassette_name: 'weather_api/london_forecast' } do
# Your test code
end
end
end
It will make a first connection to the external service and record the response into a cassete
Skipping VCR
it 'makes real HTTP requests', vcr: { record: :skip } do
# VCR will be disabled for this test
end
Best Practices
- Sensitive Data: Always filter sensitive information like API keys and tokens:
VCR.configure do |c|
c.filter_sensitive_data('<API_KEY>') { ENV['API_KEY'] }
end
- Match Request Bodies: When testing POST requests, make sure to match on body content:
vcr: {
match_requests_on: [:method, :uri, :body],
record: :new_episodes
}
- Regular Cassette Updates: Periodically re-record your cassettes to ensure they match current API responses:
Troubleshooting
Common Issues
-
Unmatched Requests: If VCR can't find a matching request, check:
- Request method (GET, POST, etc.)
- URL (including query parameters)
- Request body
- Headers (if matching on headers)
-
Playback Failures: If recorded responses aren't playing back:
- Verify the cassette file exists
- Check if the request matching criteria are too strict
- Ensure sensitive data is being filtered consistently
Conclusion
VCR and WebMock provide a robust solution for testing external service integrations in Rails. By following these patterns and best practices, you can create reliable, maintainable tests that don't depend on external services being available.
Remember to:
- Filter sensitive data
- Organize cassettes logically
- Update cassettes periodically
- Match requests appropriately
- Handle errors gracefully
Top comments (0)