{"id":19429422,"url":"https://github.com/betterment/charlatan","last_synced_at":"2025-06-12T15:06:27.097Z","repository":{"id":37316445,"uuid":"429826803","full_name":"Betterment/charlatan","owner":"Betterment","description":"A library for configuring and providing fake http responses to your dio HTTP client.","archived":false,"fork":false,"pushed_at":"2025-03-03T16:03:29.000Z","size":129,"stargazers_count":16,"open_issues_count":2,"forks_count":1,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-24T18:49:49.833Z","etag":null,"topics":["dart","fake","flutter","http"],"latest_commit_sha":null,"homepage":"https://pub.dev/packages/charlatan","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Betterment.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-11-19T14:29:32.000Z","updated_at":"2025-03-03T16:02:42.000Z","dependencies_parsed_at":"2025-02-24T22:20:54.564Z","dependency_job_id":"0075b15c-9631-4d5d-9244-e1c6fcbe16b9","html_url":"https://github.com/Betterment/charlatan","commit_stats":{"total_commits":21,"total_committers":4,"mean_commits":5.25,"dds":0.6190476190476191,"last_synced_commit":"4a8b5bcaeb020b4d4b59d579ed80f661ada9dfe3"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/Betterment/charlatan","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Betterment%2Fcharlatan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Betterment%2Fcharlatan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Betterment%2Fcharlatan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Betterment%2Fcharlatan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Betterment","download_url":"https://codeload.github.com/Betterment/charlatan/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Betterment%2Fcharlatan/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259490544,"owners_count":22865765,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dart","fake","flutter","http"],"created_at":"2024-11-10T14:19:26.901Z","updated_at":"2025-06-12T15:06:27.077Z","avatar_url":"https://github.com/Betterment.png","language":"Dart","readme":"# charlatan\n\n[![pub package](https://img.shields.io/pub/v/charlatan.svg)](https://pub.dev/packages/charlatan)\n[![Build status](https://github.com/Betterment/charlatan/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Betterment/charlatan/actions/workflows/ci.yml?query=branch%3Amain)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://GitHub.com/Betterment/charlatan/pulse)\n\nThis package provides the ability to configure and return fake HTTP\nresponses from your [Dio HTTP Client](https://pub.dev/packages/dio).\nThis makes it easy to test the behavior of code that interacts with\nHTTP services without having to use mocks.\n\nIt consists of two components and a few helper functions:\n\n- `Charlatan` - a class for configuring and providing fake HTTP responses\n  based on HTTP method and URI template.\n- `CharlatanHttpClientAdapter` - an implementation of Dio's\n  `HttpClientAdapter` that returns responses from a configured\n  `Charlatan` instance.\n- `charlatanResponse` and request matching helpers - utilites for concisely\n  matching HTTP requests and generating fake responses.\n\n## Usage\n\nAdd `charlatan` to your pubspec.yaml's `dev_dependencies`:\n\n```yaml\n# pubspec.yaml\ndev_dependencies:\n  charlatan:\n```\n\n### Configuring fake responses\n\nCreate an instance of `Charlatan` and call the corresponding\nconfiguration method for the HTTP method you want to map a request to.\n\nYou can configure fakes responses using a specific path or a URI\ntemplate. You can also use the request object to customize your\nresponse. The easiest way to configure a response is with the\n`charlatanResponse` helper function.\n\n```dart\nfinal charlatan = Charlatan();\ncharlatan.whenPost('/users', charlatanResponse(body: { 'id': 1, 'bilbo' }));\ncharlatan.whenGet('/users/{id}', charlatanResponse(body: { 'name': 'bilbo' }));\ncharlatan.whenPut('/users/{id}/profile', charlatanResponse(statusCode: 204));\ncharlatan.whenDelete('/users/{id}', (req) =\u003e CharlatanHttpResponse(statusCode: 204, body: { 'uri': req.path }));\n```\n\nIf you need to further customize the response, you can expand\nyour fake response handler to include whatever you need. The\nonly requirement is that it returns a `CharlatanHttpResponse`.\nThis allows you to provide dynamic values for the status code,\nbody, and headers in the response.\n\n```dart\ncharlatan.whenPost('/users', (req) {\n  final data = req.body as Map\u003cString, Object?\u003e? ?? {};\n  final name = data['name'] as String?;\n  if (name == null) {\n    return CharlatanHttpResponse(\n      statusCode: 422,\n      body: {\n        'errors': {\n          'name': ['cannot be blank'],\n        },\n      },\n    );\n  }\n\n  return CharlatanHttpResponse(\n    statusCode: 201,\n    body: { 'id': 1, 'name': name },\n  );\n});\n```\n\nAdditionally, if you need to match requests using other properties of the\nrequest or with different logic, you can use `whenMatch`.\n\n```dart\ncharlatan.whenMatch(\n  (req) =\u003e req.method == 'GET' \u0026\u0026 req.path.toLowerCase() == '/posts',\n  charlatanResponse(statusCode: 200),\n);\n```\n\n### Building a fake HTTP client\n\nBuild the `CharlatanHttpClientAdapter` from the `Charlatan` instance and then\nassign it to your `Dio` instance's `httpClientAdapter`.\n\n```dart\nfinal charlatan = Charlatan();\n// ... configure fake responses ...\nfinal dio = Dio()..httpClientAdapter = charlatan.toFakeHttpClientAdapter();\n```\n\nNow make HTTP requests like your normally would and they will be routed\nthrough your configured fakes.\n\n```dart\nfinal result = await dio.get\u003cObject?\u003e('/users/1');\nexpect(result.data, {'id', 1, 'name': 'bilbo'});\n```\n\n### FAQ\n\n\u003e What happens if I make a request that doesn't match a configured fake\n\u003e response?\n\nYou get a helpful error message like this:\n\n```\nUnable to find matching fake http response definition for:\n\nGET /blahhhh\n\nDid you configure it?\n\nThe fake http response definitions configured were:\nGET /users\nPOST /users\nPUT /users\nDELETE /users\n```\n\n\u003e How can I configure a fake response that relies upon the result of\n\u003e another fake request? e.g. a POST followed by a GET that can \"read its\n\u003e own writes\"\n\nCheck out the example directory.\n\n### Contributing\n\nIf you run into a bug or limitation when using Charlatan, we'd love your help in resolving it. First, it would be awesome if you could [open an issue](https://github.com/Betterment/charlatan/issues/new/choose) to discuss. If we feel like we should move forward with a change and you're willing to contribute, create a fork of `Charlatan` and open a PR against the main repo. Keep the following in mind when doing so:\n\n- Prior to opening the PR, be sure to run `dart format .` in the root of `Charlatan` which will format the code so it passes CI checks\n- When opening the PR, include one of `(MINOR)`, `(MAJOR)`, or `(NOBUMP)` at the _end_ of your PR title. Otherwise, it will fail CI. These tokens aid in the automation of our releases. Use `(MINOR)` to denote that your changes warrant a minor bump (they don't break the public API). Use `(MAJOR)` to denote that your changes warrant a major bump (they break the public API). Lastly, use `(NOBUMP)` to denote that your changes don't warrant a version bump (perhaps you fixed a docs typo).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbetterment%2Fcharlatan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbetterment%2Fcharlatan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbetterment%2Fcharlatan/lists"}