EasyVCR 0.10.0

dotnet add package EasyVCR --version 0.10.0
NuGet\Install-Package EasyVCR -Version 0.10.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="EasyVCR" Version="0.10.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add EasyVCR --version 0.10.0
#r "nuget: EasyVCR, 0.10.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install EasyVCR as a Cake Addin
#addin nuget:?package=EasyVCR&version=0.10.0

// Install EasyVCR as a Cake Tool
#tool nuget:?package=EasyVCR&version=0.10.0

EasyVCR

CI Coverage Status NuGet

EasyVCR is a library for recording and replaying HTTP interactions in your test suite.

This can be useful for speeding up your test suite, or for running your tests on a CI server which doesn't have connectivity to the HTTP endpoints you need to interact with.

How to use EasyVCR

Step 1.

Run your test suite locally against a real HTTP endpoint in recording mode

using EasyVCR;

// Create a cassette to handle HTTP interactions
var cassette = new Cassette("path/to/cassettes", "my_cassette");

// create an EasyVcrHttpClient using the cassette
var recordingHttpClient = HttpClients.NewHttpClient(cassette, Mode.Record);

// Use this EasyVcrHttpClient in any class making HTTP calls
// Note: EasyVcrHttpClient implements HttpClient, so it can be used anywhere a HttpClient is expected
// For example, RestSharp v107+ supports custom HTTP clients
RestClient restClient = new RestClient(recordingHttpClient, new RestClientOptions()));

// Or make HTTP calls directly
var response = await recordingHttpClient.GetAsync("https://api.example.com/v1/users");

Real HTTP calls will be made and recorded to the cassette file.

Step 2.

Switch to replay mode:

using EasyVCR;

// Create a cassette to handle HTTP interactions
var cassette = new Cassette("path/to/cassettes", "my_cassette");

// create an EasyVcrHttpClient using the cassette
var replayingHttpClient = HttpClients.NewHttpClient(cassette, Mode.Replay);

Now when tests are run, no real HTTP calls will be made. Instead, the HTTP responses will be replayed from the cassette file.

Available modes

  • Mode.Auto: Play back a request if it has been recorded before, or record a new one if not. (default mode for VCR)
  • Mode.Record: Record a request, including overwriting any existing matching recording.
  • Mode.Replay: Replay a request. Throws an exception if no matching recording is found.
  • Mode.Bypass: Do not record or replay any requests (client will behave like a normal HttpClient).

Features

EasyVCR comes with a number of features, many of which can be customized via the AdvancedOptions class.

Censoring

Censor sensitive data in the request and response, such as API keys and auth tokens.

Can censor:

  • Request and response headers (via key name)
  • Request and response bodies (via key name) (JSON only)
  • Request query parameters (via key name)
  • Request URL path elements (via regex pattern matching)

Default: Disabled

using EasyVCR;

var cassette = new Cassette("path/to/cassettes", "my_cassette");

var censors = new Censors().CensorHeadersByKeys(new List<string> { "Authorization" }) // Hide the Authorization header
censors.CensorBodyElementsByKeys(new List<CensorElement> { new CensorElement("table", true) }); // Hide the table element (case sensitive) in the request and response body
censors.CensorPathElementsByPatterns(new List<string> { ".*\\d{4}.*" }); // Hide any path element that contains 4 digits

var advancedOptions = new AdvancedOptions()
{
    Censors = censors
};

var httpClient = HttpClients.NewHttpClient(cassette, Mode.Record, advancedSettings);

Delay

Simulate a delay when replaying a recorded request, either using a specified delay or the original request duration.

NOTE: Delays may suffer from a small margin of error on certain .NET versions. Do not rely on the delay being exact down to the millisecond.

Default: No delay

using EasyVCR;

var cassette = new Cassette("path/to/cassettes", "my_cassette");
var advancedOptions = new AdvancedOptions()
{
    SimulateDelay = true, // Simulate a delay of the original request duration when replaying (overrides ManualDelay)
    ManualDelay = 1000 // Simulate a delay of 1000 milliseconds when replaying
};

var httpClient = HttpClients.NewHttpClient(cassette, Mode.Replay, advancedSettings);

Expiration

Set expiration dates for recorded requests, and decide what to do with expired recordings.

Default: No expiration

using EasyVCR;

var cassette = new Cassette("path/to/cassettes", "my_cassette");
var advancedOptions = new AdvancedOptions()
{
    ValidTimeFrame = new TimeFrame() {  // Any matching request is considered expired if it was recorded more than 30 days ago
        Days = 30,
    },
    WhenExpired = ExpirationActions.ThrowException // Throw exception if the recording is expired
};

var httpClient = HttpClients.NewHttpClient(cassette, Mode.Replay, advancedSettings);

Matching

Customize how a recorded request is determined to be a match to the current request.

Default: Method and full URL must match

using EasyVCR;

var cassette = new Cassette("path/to/cassettes", "my_cassette");
var advancedOptions = new AdvancedOptions()
{
    MatchRules = new MatchRules().ByBody().ByHeader("X-My-Header"), // Match recorded requests by body and a specific header
};

var httpClient = HttpClients.NewHttpClient(cassette, Mode.Replay, advancedSettings);

Ordering

Customize how elements of a recorded request are organized in the cassette file. Helpful to avoid unnecessary git differences between cassette file versions.

Default: Elements are stored alphabetically

NOTE: This setting must be used when creating the cassette.

using EasyVCR;

var order = new CassetteOrder.None(); // elements of each request in a cassette won't be ordered in any particular way
var cassette = new Cassette("path/to/cassettes", "my_cassette", order);

var httpClient = HttpClients.NewHttpClient(cassette, Mode.Replay, advancedSettings);

Logging

Have EasyVCR integrate with your custom logger to log warnings and errors.

Default: Logs to console

using EasyVCR;

var cassette = new Cassette("path/to/cassettes", "my_cassette");
var advancedOptions = new AdvancedOptions()
{
    Logger = new MyCustomLogger(), // Have EasyVCR use your custom logger when making log entries
};

var httpClient = HttpClients.NewHttpClient(cassette, Mode.Replay, advancedSettings);

HttpClient Conversion

Override how HttpClient request and response objects are converted into EasyVCR request and response objects, and vice versa. Useful if HttpClient suffers breaking changes in future .NET versions.

using EasyVCR;

var cassette = new Cassette("path/to/cassettes", "my_cassette");
var advancedOptions = new AdvancedOptions()
{
    InteractionConverter = new MyInteractionConverter(), // use a custom interaction converter by implementing IInteractionConverter
};

var httpClient = HttpClients.NewHttpClient(cassette, Mode.Replay, advancedSettings);

VCR

In addition to individual recordable HttpClient instances, EasyVCR also offers a built-in VCR, which can be used to easily switch between multiple cassettes and/or modes. Any advanced settings applied to the VCR will be applied on every request made using the VCR's HttpClient.

using EasyVCR;

var advancedSettings = new AdvancedSettings
{
    Censors = new Censors().CensorQueryParametersByKeys(new List<string> { "api_key" }) // hide the api_key query parameter
};

// Create a VCR with the advanced settings applied
var vcr = new VCR(advancedSettings);

// Create a cassette and add it to the VCR
var cassette = new Cassette("path/to/cassettes", "my_cassette");
vcr.Insert(cassette);
       
// Set the VCR to record mode     
vcr.Record();
            
// Get an HttpClient using the VCR
var httpClient = vcr.Client;
            
// Use the HttpClient as you would normally.
var response = await httpClient.GetAsync("https://google.com");

// Remove the cassette from the VCR            
vcr.Eject();
Credit
Product Compatible and additional computed target framework versions.
.NET net5.0 is compatible.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 is compatible. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
0.10.0 747 2/10/2024
0.9.0 9,795 5/17/2023
0.8.0 16,950 12/20/2022
0.7.0 329 11/18/2022
0.6.0 355 10/19/2022
0.5.1 4,231 10/5/2022
0.5.0 398 10/4/2022
0.4.0 980 6/13/2022
0.3.1 1,626 5/26/2022
0.3.0 397 5/24/2022
0.2.0 449 5/18/2022
0.1.0 690 4/27/2022