{"id":19866083,"url":"https://github.com/steinfletcher/apitest","last_synced_at":"2025-05-14T13:06:15.006Z","repository":{"id":38859083,"uuid":"163222413","full_name":"steinfletcher/apitest","owner":"steinfletcher","description":"A simple and extensible behavioural testing library for Go. You can use api test to simplify REST API, HTTP handler and e2e tests.","archived":false,"fork":false,"pushed_at":"2025-03-12T22:22:43.000Z","size":2284,"stargazers_count":814,"open_issues_count":2,"forks_count":55,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-14T01:49:10.113Z","etag":null,"topics":["api-testing","behavioural-tests","blackbox-testing","golang","jsonpath","mocking","mocks","sequence-diagrams","testing"],"latest_commit_sha":null,"homepage":"https://apitest.dev","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/steinfletcher.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-12-26T22:27:19.000Z","updated_at":"2025-04-11T05:58:35.000Z","dependencies_parsed_at":"2024-05-08T13:28:59.602Z","dependency_job_id":"5dfe7452-4c76-4633-bd90-83df739709c3","html_url":"https://github.com/steinfletcher/apitest","commit_stats":{"total_commits":283,"total_committers":33,"mean_commits":8.575757575757576,"dds":0.4593639575971732,"last_synced_commit":"12fca278c05c5a1de6f62ece4b5478581db19b17"},"previous_names":["steinfletcher/api-test"],"tags_count":98,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steinfletcher%2Fapitest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steinfletcher%2Fapitest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steinfletcher%2Fapitest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steinfletcher%2Fapitest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/steinfletcher","download_url":"https://codeload.github.com/steinfletcher/apitest/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254149950,"owners_count":22022851,"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":["api-testing","behavioural-tests","blackbox-testing","golang","jsonpath","mocking","mocks","sequence-diagrams","testing"],"created_at":"2024-11-12T15:24:57.102Z","updated_at":"2025-05-14T13:06:14.909Z","avatar_url":"https://github.com/steinfletcher.png","language":"Go","readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://apitest.dev/static/images/dummy.svg\" width=\"150\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://godoc.org/github.com/steinfletcher/apitest\"\u003e\u003cimg src=\"https://godoc.org/github.com/steinfletcher/apitest?status.svg\" alt=\"Godoc\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://circleci.com/gh/steinfletcher/apitest\"\u003e\u003cimg src=\"https://circleci.com/gh/steinfletcher/apitest.svg?style=shield\" alt=\"Build Status\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://goreportcard.com/report/github.com/steinfletcher/apitest\"\u003e\u003cimg src=\"https://goreportcard.com/badge/github.com/steinfletcher/apitest\" alt=\"Go Report Card\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/avelino/awesome-go/#testing\"\u003e\u003cimg src=\"https://awesome.re/mentioned-badge.svg\" alt=\"Mentioned in Awesome Go\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n# apitest\n\nA simple and extensible behavioural testing library. Supports mocking external http calls and renders sequence diagrams on completion.\n\nIn behavioural tests the internal structure of the app is not known by the tests. Data is input to the system and the outputs are expected to meet certain conditions.\n\nJoin the conversation at #apitest on [https://gophers.slack.com](https://gophers.slack.com).\n\n\u003cspan\u003eLogo by \u003ca target=\"_blank\" href=\"https://twitter.com/egonelbre\"\u003e@egonelbre\u003c/a\u003e\u003cspan\u003e\n\nNote: The API for apitest is stable and complete - despite the lack of activity this repository is still actively maintained. Any new issues will be addressed. Feature requests will be considered.\n\n## Documentation\n\nPlease visit [https://apitest.dev](https://apitest.dev) for the latest documentation.\n\n## Installation\n\n```bash\ngo get -u github.com/steinfletcher/apitest\n```\n\n## Demo\n\n![animated gif](./apitest.gif)\n\n## Examples\n\n### Framework and library integration examples\n\n| Example                                                                                              | Comment                                                                                                    |\n| ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |\n| [gin](https://github.com/steinfletcher/apitest/tree/master/examples/gin)                             | popular martini-like web framework                                                                         |\n| [graphql](https://github.com/steinfletcher/apitest/tree/master/examples/graphql)                     | using gqlgen.com to generate a graphql server                                                              |\n| [gorilla](https://github.com/steinfletcher/apitest/tree/master/examples/gorilla)                     | the gorilla web toolkit                                                                                    |\n| [iris](https://github.com/steinfletcher/apitest/tree/master/examples/iris)                           | iris web framework                                                                                         |\n| [echo](https://github.com/steinfletcher/apitest/tree/master/examples/echo)                           | High performance, extensible, minimalist Go web framework                                                  |\n| [fiber](https://github.com/steinfletcher/apitest/tree/master/examples/fiber)                         | Express inspired web framework written in Go                                                               |\n| [httprouter](https://github.com/steinfletcher/apitest/tree/master/examples/httprouter)               | High performance HTTP request router that scales well                                                      |\n| [mocks](https://github.com/steinfletcher/apitest/tree/master/examples/mocks)                         | example mocking out external http calls                                                                    |\n| [sequence diagrams](https://github.com/steinfletcher/apitest/tree/master/examples/sequence-diagrams) | generate sequence diagrams from tests. See the [demo](http://demo-html.apitest.dev.s3-website-eu-west-1.amazonaws.com/)  |\n| [Ginkgo](https://github.com/steinfletcher/apitest/tree/master/examples/ginkgo) | Ginkgo BDD test framework|\n\n### Companion libraries\n\n| Library                                                                 | Comment                                        |\n| ----------------------------------------------------------------------- | -----------------------------------------------|\n| [JSONPath](https://github.com/steinfletcher/apitest-jsonpath)           | JSONPath assertion addons                      |\n| [CSS Selectors](https://github.com/steinfletcher/apitest-css-selector)  | CSS selector assertion addons                  |\n| [PlantUML](https://github.com/steinfletcher/apitest-plantuml)           | Export sequence diagrams as plantUML           |\n| [DynamoDB](https://github.com/steinfletcher/apitest-dynamodb)           | Add DynamoDB interactions to sequence diagrams |\n\n### Credits\n\nThis library was influenced by the following software packages:\n\n* [YatSpec](https://github.com/bodar/yatspec) for creating sequence diagrams from tests\n* [MockMVC](https://spring.io) and [superagent](https://github.com/visionmedia/superagent) for the concept and behavioural testing approach\n* [Gock](https://github.com/h2non/gock) for the approach to mocking HTTP services in Go\n* [Baloo](https://github.com/h2non/baloo) for API design\n\n### Code snippets\n\n#### JSON body matcher\n\n```go\nfunc TestApi(t *testing.T) {\n\tapitest.New().\n\t\tHandler(handler).\n\t\tGet(\"/user/1234\").\n\t\tExpect(t).\n\t\tBody(`{\"id\": \"1234\", \"name\": \"Tate\"}`).\n\t\tStatus(http.StatusOK).\n\t\tEnd()\n}\n```\n\n#### JSONPath\n\nFor asserting on parts of the response body JSONPath may be used. A separate module must be installed which provides these assertions - `go get -u github.com/steinfletcher/apitest-jsonpath`. This is packaged separately to keep this library dependency free.\n\nGiven the response is `{\"a\": 12345, \"b\": [{\"key\": \"c\", \"value\": \"result\"}]}`\n\n```go\nfunc TestApi(t *testing.T) {\n\tapitest.Handler(handler).\n\t\tGet(\"/hello\").\n\t\tExpect(t).\n\t\tAssert(jsonpath.Contains(`$.b[? @.key==\"c\"].value`, \"result\")).\n\t\tEnd()\n}\n```\n\nand `jsonpath.Equals` checks for value equality\n\n```go\nfunc TestApi(t *testing.T) {\n\tapitest.Handler(handler).\n\t\tGet(\"/hello\").\n\t\tExpect(t).\n\t\tAssert(jsonpath.Equal(`$.a`, float64(12345))).\n\t\tEnd()\n}\n```\n\n#### Custom assert functions\n\n```go\nfunc TestApi(t *testing.T) {\n\tapitest.Handler(handler).\n\t\tGet(\"/hello\").\n\t\tExpect(t).\n\t\tAssert(func(res *http.Response, req *http.Request) error {\n\t\t\tassert.Equal(t, http.StatusOK, res.StatusCode)\n\t\t\treturn nil\n\t\t}).\n\t\tEnd()\n}\n```\n\n#### Assert cookies\n\n```go\nfunc TestApi(t *testing.T) {\n\tapitest.Handler(handler).\n\t\tPatch(\"/hello\").\n\t\tExpect(t).\n\t\tStatus(http.StatusOK).\n\t\tCookies(apitest.Cookie(\"ABC\").Value(\"12345\")).\n\t\tCookiePresent(\"Session-Token\").\n\t\tCookieNotPresent(\"XXX\").\n\t\tCookies(\n\t\t\tapitest.Cookie(\"ABC\").Value(\"12345\"),\n\t\t\tapitest.Cookie(\"DEF\").Value(\"67890\"),\n\t\t).\n\t\tEnd()\n}\n```\n\n#### Assert headers\n\n```go\nfunc TestApi(t *testing.T) {\n\tapitest.Handler(handler).\n\t\tGet(\"/hello\").\n\t\tExpect(t).\n\t\tStatus(http.StatusOK).\n\t\tHeaders(map[string]string{\"ABC\": \"12345\"}).\n\t\tEnd()\n}\n```\n\n#### Mocking external http calls\n\n```go\nvar getUser = apitest.NewMock().\n\tGet(\"/user/12345\").\n\tRespondWith().\n\tBody(`{\"name\": \"jon\", \"id\": \"1234\"}`).\n\tStatus(http.StatusOK).\n\tEnd()\n\nvar getPreferences = apitest.NewMock().\n\tGet(\"/preferences/12345\").\n\tRespondWith().\n\tBody(`{\"is_contactable\": true}`).\n\tStatus(http.StatusOK).\n\tEnd()\n\nfunc TestApi(t *testing.T) {\n\tapitest.New().\n\t\tMocks(getUser, getPreferences).\n\t\tHandler(handler).\n\t\tGet(\"/hello\").\n\t\tExpect(t).\n\t\tStatus(http.StatusOK).\n\t\tBody(`{\"name\": \"jon\", \"id\": \"1234\"}`).\n\t\tEnd()\n}\n```\nIt is possible to configure the mock for using `AnyTimes` feature,  it allows a mock to be invoked any number of times \nwithout failing the asserts if it is not used the expected number of times. \n\nThis is very useful in scenarios where the exact number of invocations is not known or not important.\n\n```go\nvar getUser := apitest.NewMock().\n    Get(\"http://localhost:8080\").\n    RespondWith().\n    Status(http.StatusOK).\n    AnyTimes().\n    End()\n```\nNote: The `AnyTimes` method can be combined with other methods such as `Times`, but if `AnyTimes` is set, the `Times` setting will have no effect.\n\n#### Generating sequence diagrams from tests\n\n```go\n\nfunc TestApi(t *testing.T) {\n\tapitest.New().\n\t\tReport(apitest.SequenceDiagram()).\n\t\tMocks(getUser, getPreferences).\n\t\tHandler(handler).\n\t\tGet(\"/hello\").\n\t\tExpect(t).\n\t\tStatus(http.StatusOK).\n\t\tBody(`{\"name\": \"jon\", \"id\": \"1234\"}`).\n\t\tEnd()\n}\n```\n\nIt is possible to override the default storage location by passing the formatter instance `Report(apitest.NewSequenceDiagramFormatter(\".sequence-diagrams\"))`.\nYou can bring your own formatter too if you want to produce custom output. By default a sequence diagram is rendered on a html page. See the [demo](http://demo-html.apitest.dev.s3-website-eu-west-1.amazonaws.com/)\n\n#### Debugging http requests and responses generated by api test and any mocks\n\n```go\nfunc TestApi(t *testing.T) {\n\tapitest.New().\n\t\tDebug().\n\t\tHandler(handler).\n\t\tGet(\"/hello\").\n\t\tExpect(t).\n\t\tStatus(http.StatusOK).\n\t\tEnd()\n}\n```\n\n#### Provide basic auth in the request\n\n```go\nfunc TestApi(t *testing.T) {\n\tapitest.Handler(handler).\n\t\tGet(\"/hello\").\n\t\tBasicAuth(\"username\", \"password\").\n\t\tExpect(t).\n\t\tStatus(http.StatusOK).\n\t\tEnd()\n}\n```\n\n#### Pass a custom context to the request\n\n```go\nfunc TestApi(t *testing.T) {\n\tapitest.Handler(handler).\n\t\tGet(\"/hello\").\n\t\tWithContext(context.TODO()).\n\t\tExpect(t).\n\t\tStatus(http.StatusOK).\n\t\tEnd()\n}\n```\n\n#### Provide cookies in the request\n\n```go\nfunc TestApi(t *testing.T) {\n\tapitest.Handler(handler).\n\t\tGet(\"/hello\").\n\t\tCookies(apitest.Cookie(\"ABC\").Value(\"12345\")).\n\t\tExpect(t).\n\t\tStatus(http.StatusOK).\n\t\tEnd()\n}\n```\n\n#### Provide headers in the request\n\n```go\nfunc TestApi(t *testing.T) {\n\tapitest.Handler(handler).\n\t\tDelete(\"/hello\").\n\t\tHeaders(map[string]string{\"My-Header\": \"12345\"}).\n\t\tExpect(t).\n\t\tStatus(http.StatusOK).\n\t\tEnd()\n}\n```\n\n#### Provide query parameters in the request\n\n`Query`, `QueryParams` and `QueryCollection` can all be used in combination \n\n```go\nfunc TestApi(t *testing.T) {\n\tapitest.Handler(handler).\n\t\tGet(\"/hello\").\n\t\tQueryParams(map[string]string{\"a\": \"1\", \"b\": \"2\"}).\n\t\tQuery(\"c\", \"d\").\n\t\tExpect(t).\n\t\tStatus(http.StatusOK).\n\t\tEnd()\n}\n```\n\nProviding `{\"a\": {\"b\", \"c\", \"d\"}` results in parameters encoded as `a=b\u0026a=c\u0026a=d`.\n`QueryCollection` can be used in combination with `Query`\n\n```go\nfunc TestApi(t *testing.T) {\n\tapitest.Handler(handler).\n\t\tGet(\"/hello\").\n\t\tQueryCollection(map[string][]string{\"a\": {\"b\", \"c\", \"d\"}}).\n\t\tExpect(t).\n\t\tStatus(http.StatusOK).\n\t\tEnd()\n}\n```\n\n#### Provide a url encoded form body in the request\n\n```go\nfunc TestApi(t *testing.T) {\n\tapitest.Handler(handler).\n\t\tPost(\"/hello\").\n\t\tFormData(\"a\", \"1\").\n\t\tFormData(\"b\", \"2\").\n\t\tFormData(\"b\", \"3\").\n\t\tFormData(\"c\", \"4\", \"5\", \"6\").\n\t\tExpect(t).\n\t\tStatus(http.StatusOK).\n\t\tEnd()\n}\n```\n\n#### Provide a multipart/form-data\n\n```go\nfunc TestApi(t *testing.T) {\n\tapitest.Handler(handler).\n\t\tPost(\"/hello\").\n\t\tMultipartFormData(\"a\", \"1\", \"2\").\n\t\tMultipartFile(\"file\", \"path/to/some.file1\", \"path/to/some.file2\").\n\t\tExpect(t).\n\t\tStatus(http.StatusOK).\n\t\tEnd()\n}\n```\n\n#### Provide a multipart/form-data with custom filesystem\n\n```go\ninMemFS := fstest.MapFS{\n\t\"audio.wav\": \u0026fstest.MapFile{\n\t\tData:    []byte{19,2,123,12,35,1},\n\t\tMode:    fs.FileMode(0644),\n\t\tModTime: time.Now(),\n\t},\n\t\"audio.mp3\": \u0026fstest.MapFile{\n\t\tData:    []byte{21,13,88,123,9,8},\n\t\tMode:    fs.FileMode(0644),\n\t\tModTime: time.Now(),\n\t},\n}\n\nfunc TestApi(t *testing.T) {\n\tapitest.Handler(handler).\n\t\tUseFS(inMemFS).\n\t\tPost(\"/hello\").\n\t\tMultipartFormData(\"a\", \"1\", \"2\").\n\t\tMultipartFile(\"file\", \"audio.wav\", \"audio.mp3\").\n\t\tExpect(t).\n\t\tStatus(http.StatusOK).\n\t\tEnd()\n}\n```\n\n\n#### Capture the request and response data\n\n```go\nfunc TestApi(t *testing.T) {\n\tapitest.New().\n\t\tObserve(func(res *http.Response, req *http.Request, apiTest *apitest.APITest) {\n\t\t\t// do something with res and req\n\t\t}).\n\t\tHandler(handler).\n\t\tGet(\"/hello\").\n\t\tExpect(t).\n\t\tStatus(http.StatusOK).\n\t\tEnd()\n}\n```\n\n#### Intercept the request\n\nThis is useful for mutating the request before it is sent to the system under test.\n\n```go\nfunc TestApi(t *testing.T) {\n\tapitest.Handler(handler).\n\t\tIntercept(func(req *http.Request) {\n\t\t\treq.URL.RawQuery = \"a[]=xxx\u0026a[]=yyy\"\n\t\t}).\n\t\tGet(\"/hello\").\n\t\tExpect(t).\n\t\tStatus(http.StatusOK).\n\t\tEnd()\n}\n```\n\n## Contributing\n\nView the [contributing guide](CONTRIBUTING.md).\n","funding_links":[],"categories":["Go"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteinfletcher%2Fapitest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsteinfletcher%2Fapitest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteinfletcher%2Fapitest/lists"}