{"id":38716002,"url":"https://github.com/empire/go-httpmock","last_synced_at":"2026-01-17T11:03:30.217Z","repository":{"id":65051803,"uuid":"581110950","full_name":"empire/go-httpmock","owner":"empire","description":"Proof of concept to mock go http server","archived":false,"fork":false,"pushed_at":"2023-01-13T16:31:24.000Z","size":225,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-06-20T05:11:05.561Z","etag":null,"topics":["go","mock","server-mocking","testing"],"latest_commit_sha":null,"homepage":"","language":"Go","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/empire.png","metadata":{"files":{"readme":"README.md","changelog":"History.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-12-22T09:54:51.000Z","updated_at":"2024-06-20T05:11:05.562Z","dependencies_parsed_at":"2023-02-09T16:16:05.085Z","dependency_job_id":null,"html_url":"https://github.com/empire/go-httpmock","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/empire/go-httpmock","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/empire%2Fgo-httpmock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/empire%2Fgo-httpmock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/empire%2Fgo-httpmock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/empire%2Fgo-httpmock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/empire","download_url":"https://codeload.github.com/empire/go-httpmock/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/empire%2Fgo-httpmock/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28506593,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T10:25:30.148Z","status":"ssl_error","status_checked_at":"2026-01-17T10:25:29.718Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["go","mock","server-mocking","testing"],"created_at":"2026-01-17T11:03:29.625Z","updated_at":"2026-01-17T11:03:30.196Z","avatar_url":"https://github.com/empire.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# httpmock [![Build Status](https://travis-ci.org/empire/go-httpmock.svg?branch=master)](https://travis-ci.org/empire/go-httpmock) [![GitHub release](https://img.shields.io/badge/version-v1.0-orange.svg?style=flat)](https://github.com/empire/go-httpmock/releases) [![GoDoc](https://godoc.org/github.com/empire/go-httpmock?status.svg)](https://godoc.org/github.com/empire/go-httpmock) [![Coverage Status](https://coveralls.io/repos/github/empire/go-httpmock/badge.svg?branch=master)](https://coveralls.io/github/empire/go-httpmock?branch=master) [![Go Report Card](https://img.shields.io/badge/go_report-A+-brightgreen.svg)](https://goreportcard.com/report/github.com/empire/go-httpmock) [![license](https://img.shields.io/badge/license-MIT-blue.svg)]()\n\nVersatile HTTP mocking made easy in [Go](https://golang.org) that works with any `net/http` based stdlib implementation.\n\nHeavily inspired by [gock](https://github.com/h2non/gock).\nThere is also its Python port, [pook](https://github.com/h2non/pook).\n\nTo get started, take a look to the [examples](#examples).\n\n## Features\n\n- Simple, expressive, fluent API.\n- Semantic API DSL for declarative HTTP mock declarations.\n- Built-in helpers for easy JSON/XML mocking.\n- Supports persistent and volatile TTL-limited mocks.\n- Full regular expressions capable HTTP request mock matching.\n- Designed for both testing and runtime scenarios.\n- Match request by method, URL params, headers and bodies.\n- Extensible and pluggable HTTP matching rules.\n- Ability to switch between mock and real networking modes.\n- Ability to filter/map HTTP requests for accurate mock matching.\n- Supports map and filters to handle mocks easily.\n- Works with any `net/http` compatible client, such as [gentleman](https://github.com/h2non/gentleman).\n- Network timeout/cancelation delay simulation.\n- Extensible and hackable API.\n- Dependency free.\n\n## Installation\n\n```bash\ngo get -u github.com/empire/go-httpmock\n```\n\n## API\n\nSee [godoc reference](https://pkg.go.dev/github.com/empire/go-httpmock) for detailed API documentation.\n\n## How it mocks (TODO refine the following items)\n\n1. ~Intercepts any HTTP outgoing request via `http.DefaultTransport` or custom `http.Transport` used by any `http.Client`.~\n2. Matches outgoing HTTP requests against a pool of defined HTTP mock expectations in FIFO declaration order.\n3. If at least one mock matches, it will be used in order to compose the mock HTTP response.\n4. If no mock can be matched, it will resolve the request with an error, unless real networking mode is enable, in which case a real HTTP request will be performed.\n\n## Tips\n\n#### Testing\n\nDeclare your mocks before you start declaring the concrete test logic:\n\n```go\nfunc TestFoo(t *testing.T) {\n  s := httpmock.Server()\n\n  httpmock.New(s.URL).\n    Get(\"/bar\").\n    Reply(200).\n    JSON(map[string]string{\"foo\": \"bar\"})\n\n  // Your test code starts here...\n}\n```\n\n#### Race conditions\n\nIf you're running concurrent code, be aware that your mocks are declared first to avoid unexpected\nrace conditions while configuring `httpmock` or intercepting custom HTTP clients.\n\n`httpmock` is not fully thread-safe, but sensible parts are.\nAny help making `httpmock` more reliable in this sense is appreciated.\n\n#### Define complex mocks first\n\nIf you're mocking a bunch of mocks in the same test suite, it's recommended to define the more\nconcrete mocks first, and then the generic ones.\n\nThis approach usually avoids matching unexpected generic mocks (e.g: specific header, body payload...) instead of the generic ones that performs less complex matches.\n\n## Examples\n\nSee [examples](https://github.com/empire/go-httpmock/tree/master/examples) directory for more featured use cases.\n\n#### Simple mocking via tests\n\n```go\npackage test\n\nimport (\n  \"io/ioutil\"\n  \"net/http\"\n  \"testing\"\n\n  \"github.com/empire/go-httpmock\"\n  \"github.com/stretchr/testify/require\"\n)\n\nfunc TestSimple(t *testing.T) {\n  s := httpmock.Server(t)\n  httpmock.New(s.URL).\n    Get(\"/bar\").\n    Reply(200).\n    JSON(map[string]string{\"foo\": \"bar\"})\n\n  res, err := http.Get(s.URL + \"/bar\")\n  require.Equal(t, err, nil)\n  require.Equal(t, res.StatusCode, 200)\n\n  body, _ := ioutil.ReadAll(res.Body)\n  require.Equal(t, string(body)[:13], `{\"foo\":\"bar\"}`)\n\n  // Verify that we don't have pending mocks\n  require.True(t, httpmock.IsDone(t))\n}\n```\n\n#### Request headers matching\n\n```go\npackage test\n\nimport (\n  \"io/ioutil\"\n  \"net/http\"\n  \"testing\"\n\n  \"github.com/empire/go-httpmock\"\n  \"github.com/stretchr/testify/require\"\n)\n\nfunc TestMatchHeaders(t *testing.T) {\n  s := httpmock.Server(t)\n\n  httpmock.New(s.URL).\n    MatchHeader(\"Authorization\", \"^foo bar$\").\n    MatchHeader(\"API\", \"1.[0-9]+\").\n    HeaderPresent(\"Accept\").\n    Reply(200).\n    BodyString(\"foo foo\")\n\n  req, err := http.NewRequest(\"GET\", s.URL, nil)\n  req.Header.Set(\"Authorization\", \"foo bar\")\n  req.Header.Set(\"API\", \"1.0\")\n  req.Header.Set(\"Accept\", \"text/plain\")\n\n  res, err := (\u0026http.Client{}).Do(req)\n  require.Equal(t, err, nil)\n  require.Equal(t, res.StatusCode, 200)\n  body, _ := ioutil.ReadAll(res.Body)\n  require.Equal(t, string(body), \"foo foo\")\n\n  // Verify that we don't have pending mocks\n  require.True(t, httpmock.IsDone(t))\n}\n```\n\n#### Request param matching\n\n```go\npackage test\n\nimport (\n  \"io/ioutil\"\n  \"net/http\"\n  \"testing\"\n\n  \"github.com/empire/go-httpmock\"\n  \"github.com/stretchr/testify/require\"\n)\n\nfunc TestMatchParams(t *testing.T) {\n  s := httpmock.Server(t)\n  httpmock.New(s.URL).\n    MatchParam(\"page\", \"1\").\n    MatchParam(\"per_page\", \"10\").\n    Reply(200).\n    BodyString(\"foo foo\")\n\n  req, err := http.NewRequest(\"GET\", s.URL+\"?page=1\u0026per_page=10\", nil)\n\n  res, err := (\u0026http.Client{}).Do(req)\n  require.Equal(t, err, nil)\n  require.Equal(t, res.StatusCode, 200)\n  body, _ := ioutil.ReadAll(res.Body)\n  require.Equal(t, string(body), \"foo foo\")\n\n  // Verify that we don't have pending mocks\n  require.True(t, httpmock.IsDone(t))\n}\n```\n\n#### JSON body matching and response\n\n```go\npackage test\n\nimport (\n  \"bytes\"\n  \"io/ioutil\"\n  \"net/http\"\n  \"testing\"\n\n  \"github.com/empire/go-httpmock\"\n  \"github.com/stretchr/testify/require\"\n)\n\nfunc TestMockSimple(t *testing.T) {\n  s := httpmock.Server(t)\n  httpmock.New(s.URL).\n    Post(\"/bar\").\n    MatchType(\"json\").\n    JSON(map[string]string{\"foo\": \"bar\"}).\n    Reply(201).\n    JSON(map[string]string{\"bar\": \"foo\"})\n\n  body := bytes.NewBuffer([]byte(`{\"foo\":\"bar\"}`))\n  res, err := http.Post(s.URL+\"/bar\", \"application/json\", body)\n  require.Equal(t, err, nil)\n  require.Equal(t, res.StatusCode, 201)\n\n  resBody, _ := ioutil.ReadAll(res.Body)\n  require.Equal(t, string(resBody)[:13], `{\"bar\":\"foo\"}`)\n\n  // Verify that we don't have pending mocks\n  require.True(t, httpmock.IsDone(t))\n}\n```\n\n#### Mocking a custom http.Client and http.RoundTripper\n\n```go\npackage test\n\nimport (\n  \"io/ioutil\"\n  \"net/http\"\n  \"testing\"\n\n  \"github.com/empire/go-httpmock\"\n  \"github.com/stretchr/testify/require\"\n)\n\nfunc TestClient(t *testing.T) {\n  s := httpmock.Server(t)\n  httpmock.New(s.URL).\n    Reply(200).\n    BodyString(\"foo foo\")\n\n  req, err := http.NewRequest(\"GET\", s.URL, nil)\n  client := \u0026http.Client{Transport: \u0026http.Transport{}}\n\n  res, err := client.Do(req)\n  require.Equal(t, err, nil)\n  require.Equal(t, res.StatusCode, 200)\n  body, _ := ioutil.ReadAll(res.Body)\n  require.Equal(t, string(body), \"foo foo\")\n\n  // Verify that we don't have pending mocks\n  require.True(t, httpmock.IsDone(t))\n}\n```\n\n#### Debug intercepted http requests\n\n```go\n// TODO check the following example code\npackage main\n\nimport (\n  \"bytes\"\n  \"github.com/empire/go-httpmock\"\n  \"net/http\"\n)\n\nfunc main() {\n  defer httpmock.Off()\n  httpmock.Observe(httpmock.DumpRequest)\n\n  httpmock.New(\"http://foo.com\").\n    Post(\"/bar\").\n    MatchType(\"json\").\n    JSON(map[string]string{\"foo\": \"bar\"}).\n    Reply(200)\n\n  body := bytes.NewBuffer([]byte(`{\"foo\":\"bar\"}`))\n  http.Post(\"http://foo.com/bar\", \"application/json\", body)\n}\n\n```\n\n## Hacking it!\n\nYou can easily hack `httpmock` defining custom matcher functions with own matching rules.\n\nSee [add matcher functions](https://github.com/empire/go-httpmock/blob/master/_examples/add_matchers/matchers.go) and [custom matching layer](https://github.com/empire/go-httpmock/blob/master/_examples/custom_matcher/matcher.go) examples for further details.\n\n## License\n\nMIT - Tomas Aparicio\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fempire%2Fgo-httpmock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fempire%2Fgo-httpmock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fempire%2Fgo-httpmock/lists"}