Golang轻松模拟外部HTTP响应插件库httpmock的使用

httpmock是一个用于轻松模拟外部HTTP响应的Golang库，特别适合在单元测试中模拟HTTP请求。

安装

支持Go 1.16到1.24版本，使用v1分支而非master分支。

在代码中导入：

import "github.com/jarcoal/httpmock"

执行go mod tidy或go test会自动将最新版本的httpmock添加到你的go.mod文件中。

使用示例

简单示例

func TestFetchArticles(t *testing.T) {
  httpmock.Activate(t)

  // 精确URL匹配
  httpmock.RegisterResponder("GET", "https://api.mybiz.com/articles",
    httpmock.NewStringResponder(200, `[{"id": 1, "name": "My Great Article"}]`))

  // 正则表达式匹配(也可以使用httpmock.RegisterRegexpResponder)
  httpmock.RegisterResponder("GET", `=~^https://api\.mybiz\.com/articles/id/\d+\z`,
    httpmock.NewStringResponder(200, `{"id": 1, "name": "My Great Article"}`))

  // 执行会发起请求到articles的代码
  ...

  // 获取总调用次数
  httpmock.GetTotalCallCount()

  // 获取已注册响应器的调用次数
  info := httpmock.GetCallCountInfo()
  info["GET https://api.mybiz.com/articles"] // 对https://api.mybiz.com/articles的GET调用次数
  info["GET https://api.mybiz.com/articles/id/12"] // 对https://api.mybiz.com/articles/id/12的GET调用次数
  info[`GET =~^https://api\.mybiz\.com/articles/id/\d+\z`] // 对https://api.mybiz.com/articles/id/<任意数字>的GET调用次数
}

高级示例

func TestFetchArticles(t *testing.T) {
  httpmock.Activate(t)

  // 我们的文章数据库
  articles := make([]map[string]interface{}, 0)

  // 模拟列出文章
  httpmock.RegisterResponder("GET", "https://api.mybiz.com/articles",
    func(req *http.Request) (*http.Response, error) {
      resp, err := httpmock.NewJsonResponse(200, articles)
      if err != nil {
        return httpmock.NewStringResponse(500, ""), nil
      }
      return resp, nil
    })

  // 通过正则表达式子匹配(\d+)返回与请求相关的文章
  httpmock.RegisterResponder("GET", `=~^https://api\.mybiz\.com/articles/id/(\d+)\z`,
    func(req *http.Request) (*http.Response, error) {
      // 从请求中获取ID
      id := httpmock.MustGetSubmatchAsUint(req, 1) // 1=第一个正则子匹配
      return httpmock.NewJsonResponse(200, map[string]interface{}{
        "id":   id,
        "name": "My Great Article",
      })
    })

  // 模拟添加新文章
  httpmock.RegisterResponder("POST", "https://api.mybiz.com/articles",
    func(req *http.Request) (*http.Response, error) {
      article := make(map[string]interface{})
      if err := json.NewDecoder(req.Body).Decode(&article); err != nil {
        return httpmock.NewStringResponse(400, ""), nil
      }

      articles = append(articles, article)

      resp, err := httpmock.NewJsonResponse(200, article)
      if err != nil {
        return httpmock.NewStringResponse(500, ""), nil
      }
      return resp, nil
    })

  // 模拟添加特定文章，当请求体包含`"type":"toy"`时返回Bad Request响应
  httpmock.RegisterMatcherResponder("POST", "https://api.mybiz.com/articles",
    httpmock.BodyContainsString(`"type":"toy"`),
    httpmock.NewStringResponder(400, `{"reason":"Invalid article type"}`))

  // 执行添加和检查文章的代码
}

匹配算法

当捕获到GET http://example.tld/some/path?b=12&a=foo&a=bar请求时，所有标准响应器会按以下顺序检查URL或路径，第一个匹配停止搜索：

1. http://example.tld/some/path?b=12&a=foo&a=bar (原始URL)
2. http://example.tld/some/path?a=bar&a=foo&b=12 (排序后的查询参数)
3. http://example.tld/some/path (不带查询参数)
4. /some/path?b=12&a=foo&a=bar (不带协议和主机的原始URL)
5. /some/path?a=bar&a=foo&b=12 (同上，但查询参数排序)
6. /some/path (仅路径)

如果没有标准响应器匹配，则检查正则表达式响应器，顺序相同，第一个匹配停止搜索。

测试框架集成示例

与go-testdeep和tdsuite集成

// article_test.go

import (
  "testing"

  "github.com/jarcoal/httpmock"
  "github.com/maxatome/go-testdeep/helpers/tdsuite"
  "github.com/maxatome/go-testdeep/td"
)

type MySuite struct{}

func (s *MySuite) Setup(t *td.T) error {
  // 拦截所有HTTP请求
  httpmock.Activate(t)
  return nil
}

func (s *MySuite) PostTest(t *td.T, testName string) error {
  // 每次测试后移除所有mock
  httpmock.Reset()
  return nil
}

func TestMySuite(t *testing.T) {
  tdsuite.Run(t, &MySuite{})
}

func (s *MySuite) TestArticles(assert, require *td.T) {
  httpmock.RegisterResponder("GET", "https://api.mybiz.com/articles.json",
    httpmock.NewStringResponder(200, `[{"id": 1, "name": "My Great Article"}]`))

  // 执行会发起请求到articles.json的代码
}

与Ginkgo集成

// article_suite_test.go

import (
  // ...
  "github.com/jarcoal/httpmock"
)
// ...
var _ = BeforeSuite(func() {
  // 拦截所有HTTP请求
  httpmock.Activate()
})

var _ = BeforeEach(func() {
  // 移除所有mock
  httpmock.Reset()
})

var _ = AfterSuite(func() {
  httpmock.DeactivateAndReset()
})


// article_test.go

import (
  // ...
  "github.com/jarcoal/httpmock"
)

var _ = Describe("Articles", func() {
  It("returns a list of articles", func() {
    httpmock.RegisterResponder("GET", "https://api.mybiz.com/articles.json",
      httpmock.NewStringResponder(200, `[{"id": 1, "name": "My Great Article"}]`))

    // 执行会发起请求到articles.json的代码
  })
})

与Ginkgo和Resty集成

// article_suite_test.go

import (
  // ...
  "github.com/jarcoal/httpmock"
  "github.com/go-resty/resty/v2"
)
// ...

// 全局client(使用resty.New()每次会创建新的transport，
// 所以需要在这里和发起请求时使用同一个)
var client = resty.New()

var _ = BeforeSuite(func() {
  // 拦截所有HTTP请求
  httpmock.ActivateNonDefault(client.GetClient())
})

var _ = BeforeEach(func() {
  // 移除所有mock
  httpmock.Reset()
})

var _ = AfterSuite(func() {
  httpmock.DeactivateAndReset()
})


// article_test.go

import (
  // ...
  "github.com/jarcoal/httpmock"
)

type Article struct {
	Status struct {
		Message string `json:"message"`
		Code    int    `json:"code"`
	} `json:"status"`
}

var _ = Describe("Articles", func() {
  It("returns a list of articles", func() {
    fixture := `{"status":{"message": "Your message", "code": 200}}`
    // 必须使用NewJsonResponder来获取application/json content-type
    // 或者创建一个go对象而不是使用json.RawMessage
    responder, _ := httpmock.NewJsonResponder(200, json.RawMessage(`{"status":{"message": "Your message", "code": 200}}`)
    fakeUrl := "https://api.mybiz.com/articles.json"
    httpmock.RegisterResponder("GET", fakeUrl, responder)

    // 将文章获取到结构体中
    articleObject := &Article{}
    _, err := resty.R().SetResult(articleObject).Get(fakeUrl)

    // 对articleObject执行操作...
  })
})