Use VCR to Test Integrations

This guide will focus on why you should use a VCR for testing against the EasyPost API and the features that we recommend to use.

Unit testing external APIs can be time-consuming and non-deterministic because the unit test has to rely on the external service, and assertions would fail if the API response is inconsistent. Down below, you can see the potential problem and the workaround to fix it.

When you're writing a unit test that makes a live API call to EasyPost, our system communicates with other carriers in real-time, meaning you cannot be certain that a valid response will be received, network connectivity issues, downtime and internal problems could cause an API call to return irregular data, which may result in unit test failures. In the past, we have seen a few users making thousands of live API calls in unit testing, which resulted in a Rate Limit for the user to our server and caused issues with the unit testing as the API is returning status code 429.

To prevent these issues and improve your backend unit testing performance, you should use a VCR for the unit testing. A VCR is a tool that records HTTP requests and responses to a "cassette" file which can be replayed on later runs of the test suite as if it was the real response. This effectively enables offline testing as well as ensuring that a given API call will always return the exact same data every time. In one of our engineering blogs about why you should use VCR for API testing(opens in a new tab), we have proved that the unit testing speed went up 50x by using the VCR in our Python Client Library.

VCR provides flexibility by offering some advanced features. We highly recommend you use the below features.

To replay previously-recorded cassettes, the VCR needs to match a pending HTTP request against the details of the recorded one. By default, a recording is often matched based only on the HTTP method and URI. You can customize the rules to account for other elements of a recorded request during the matching process, such as:

• Host: The domain name of the server
• Body: The body of the API request
• Header: The request headers
• Path: The path of the URI
• Query: The query string of the request URI

This feature is highly recommended if you have many unit tests that make API calls to the same endpoint, where matching only by method and URI could accidentally cause the wrong recording to be used.

When interacting with an API service, you will often need to provide sensitive information in the request, such as an API key for authentication. This data may be written to the cassette file in plaintext, which can pose a serious problem in a public repository or when checking code into a version control system. Most VCR tools come with an option to censor data prior to storing the request in the cassette file. Our client libraries test suites utilize censoring to redact sensitive data, including API keys and PII such as phone numbers and email addresses, in our cassettes.You can find an example of the full code configuration in our Ruby library(opens in a new tab) which uses the built-in filter_sensitive_data feature.

While recording and replaying cassettes can help prevent data inconsistencies in your testing, you may want to eventually re-record your cassettes to account for any changes to response schemas. In most VCR tools, you can set an expiration date for a given cassette or recording, which the VCR will check during the replay process. You can often configure different actions for the VCR to take when it discovers an expired recording, such as warning the user, throwing an error, or even automatically re-recording the request.