HTTP Recorder

Record and replay HTTP requests and responses, for more repeatable tests.

Features

Ensure repeatability of HTTP requests within tests:

• Automatically record HTTP requests and responses into json files
• Respond to subsequent HTTP requests using prior recordings
• Manually mock responses to specific requests

Usage

The main expected usage of this library is to directly use testRecording() or testRecordingWidgets() inside your tests. Any http clients (a Client from the http package) will be a HttpRecordingClient that can record and replay Http requests and responses.

// Ordinary unit tests can use `testRecording`
testRecording('API service can get equipment list', (interceptor) async {
    // Any http clients created here will be an http recording client
    // ...
});

// Widget tests can use `testRecordingWidgets`
testRecordingWidgets('Home page displays telemetry data', (tester, interceptor) async {
    // ...
});

Recordings will be saved to the test_recordings folder. It is recommended to check in your recordings to source control, so they can be used in tests. This will avoid hitting the network, thus minimizing flakiness.

If you don't have any recordings yet, or if they are outdated, you can update your recordings by running flutter test --dart-define update_recordings=true. If your VS Code launch config is configured correctly, you can also update recordings via context menu. See Configure VS Code for details.

It is also possible to use runWithRecording directly. Any clients created inside the function's callback will also be an Http recording client.

test('An ordinary test', () async {
    // ...
    final data = await runWithRecording((interceptor) => Client().get(url));
    // ...
});

For configuration of these methods, you can set the globalHttpRecorder variable to use your own HttpRecorder. However, it's recommended to create and manage your own recorder instance instead of overriding the global one. For example:

final recorder = HttpRecorder(
    bodyEncoding: base64,
    httpOverrides: _GatewayHttpOverrides(),
);

recorder.testRecording('API can post', (interceptor) {
    // ...
});

Setup

Add a "http_recording" tag to your project

Add a dart_test.yaml file to the root of your project with the following content:

tags:
  http_recording:

This will indicate that http recordings are an expected test tag. All tests that use testRecordings() or testRecordingWidgets() will automatically be given this tag. This allows you to easily target HTTP recording tests from the command-line.

Configure VS Code

If you use VSCode, we highly recommend adding this configuration to you .vscode/launch.json file in the root of your workspace:

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Record HTTP",
            "request": "launch",
            "type": "dart",
            "codeLens": {
                "for": ["run-test", "run-test-file"]
            },
            "args": ["--dart-define", "update_recordings=true"]
        }
    ]
}

This gives you a context menu where you can easily update the HTTP recordings for a particular test directly from the IDE: