charlatan

Description:

charlatan

charlatan #




This package provides the ability to configure and return fake HTTP
responses from your Dio HTTP Client.
This makes it easy to test the behavior of code that interacts with
HTTP services without having to use mocks.
It consists of two components and a few helper functions:

Charlatan - a class for configuring and providing fake HTTP responses
based on HTTP method and URI template.
CharlatanHttpClientAdapter - an implementation of Dio's
HttpClientAdapter that returns responses from a configured
Charlatan instance.
charlatanResponse and request matching helpers - utilites for concisely
matching HTTP requests and generating fake responses.

Usage #
Add charlatan to your pubspec.yaml's dev_dependencies:
# pubspec.yaml
dev_dependencies:
charlatan:
copied to clipboard
Configuring fake responses #
Create an instance of Charlatan and call the corresponding
configuration method for the HTTP method you want to map a request to.
You can configure fakes responses using a specific path or a URI
template. You can also use the request object to customize your
response. The easiest way to configure a response is with the
charlatanResponse helper function.
final charlatan = Charlatan();
charlatan.whenPost('/users', charlatanResponse(body: { 'id': 1, 'bilbo' }));
charlatan.whenGet('/users/{id}', charlatanResponse(body: { 'name': 'bilbo' }));
charlatan.whenPut('/users/{id}/profile', charlatanResponse(statusCode: 204));
charlatan.whenDelete('/users/{id}', (req) => CharlatanHttpResponse(statusCode: 204, body: { 'uri': req.path }));
copied to clipboard
If you need to further customize the response, you can expand
your fake response handler to include whatever you need. The
only requirement is that it returns a CharlatanHttpResponse.
This allows you to provide dynamic values for the status code,
body, and headers in the response.
charlatan.whenPost('/users', (req) {
final data = req.body as Map<String, Object?>? ?? {};
final name = data['name'] as String?;
if (name == null) {
return CharlatanHttpResponse(
statusCode: 422,
body: {
'errors': {
'name': ['cannot be blank'],
},
},
);
}

return CharlatanHttpResponse(
statusCode: 201,
body: { 'id': 1, 'name': name },
);
});
copied to clipboard
Additionally, if you need to match requests using other properties of the
request or with different logic, you can use whenMatch.
charlatan.whenMatch(
(req) => req.method == 'GET' && req.path.toLowerCase() == '/posts',
charlatanResponse(statusCode: 200),
);
copied to clipboard
Building a fake HTTP client #
Build the CharlatanHttpClientAdapter from the Charlatan instance and then
assign it to your Dio instance's httpClientAdapter.
final charlatan = Charlatan();
// ... configure fake responses ...
final dio = Dio()..httpClientAdapter = charlatan.toFakeHttpClientAdapter();
copied to clipboard
Now make HTTP requests like your normally would and they will be routed
through your configured fakes.
final result = await dio.get<Object?>('/users/1');
expect(result.data, {'id', 1, 'name': 'bilbo'});
copied to clipboard
FAQ #

What happens if I make a request that doesn't match a configured fake
response?

You get a helpful error message like this:
Unable to find matching fake http response definition for:

GET /blahhhh

Did you configure it?

The fake http response definitions configured were:
GET /users
POST /users
PUT /users
DELETE /users
copied to clipboard

How can I configure a fake response that relies upon the result of
another fake request? e.g. a POST followed by a GET that can "read its
own writes"

Check out the example directory.