# Documentation


- **Getting started**
- [Introduction](/docs): apitest is a simple, extensible library for writing behavioural tests against Go HTTP services.
- [Getting started](/docs/getting-started): Install apitest, write a first test, and read what a failure looks like.
- [Anatomy of a test](/docs/anatomy): Every apitest test has three parts, configuration, request and expectations, built in one chain.

- **Writing tests**
- Requests
  - [Building requests](/docs/requests): Choose the handler under test, then set the method and URL of the request.
  - [Headers](/docs/requests/headers): Set request headers one at a time, from a map, or with the Content-Type shortcut.
  - [Query parameters](/docs/requests/query-parameters): Add query parameters individually, from a map, or as repeated values.
  - [Cookies](/docs/requests/cookies): Send cookies by name and value, or build them with apitest.NewCookie.
  - [Body and JSON](/docs/requests/body): Send a raw body, a formatted body, JSON from a value, or a body read from a file.
  - [Forms and file uploads](/docs/requests/forms): Send URL encoded forms, multipart forms and file uploads.
  - [GraphQL](/docs/requests/graphql): Build GraphQL requests from a query and variables.
  - [Authentication](/docs/requests/authentication): Send basic auth credentials, bearer tokens and API keys.
  - [Context](/docs/requests/context): Pass deadlines, cancellation and context values to the handler.
  - [Intercept](/docs/requests/intercept): Change the built http.Request just before it is sent.
- Assertions
  - [Asserting on responses](/docs/assertions): How expectations are checked, and how to assert on the status code.
  - [Body](/docs/assertions/body): Compare the response body as JSON or as an exact string.
  - [Headers](/docs/assertions/headers): Assert on header values, and on whether a header is present.
  - [Cookies](/docs/assertions/cookies): Assert on cookie values and attributes, and on whether a cookie was set.
  - [JSONPath](/docs/assertions/jsonpath): Assert on parts of a JSON response body with the apitest-jsonpath module.
  - [Custom assertions](/docs/assertions/custom): Write your own checks with Assert, and package them for reuse.
  - [The result](/docs/assertions/result): Use the response after the test has run, and check which mocks were not called.
- Mocks
  - [Mocking HTTP calls](/docs/mocks): Answer the outbound HTTP calls your handler makes, so tests are fast and repeatable.
  - [Defining mocks](/docs/mocks/defining-mocks): Build a mock in two halves, the request to match and the response to return.
  - [How matching works](/docs/mocks/matching): The order mocks are tried in, the rules for each part of the request, and how to debug a mismatch.
  - [Request matchers](/docs/mocks/request-matchers): Match outbound requests on headers, query parameters, the body, form data, cookies and basic auth.
  - [Custom matchers](/docs/mocks/custom-matchers): Add your own matching logic, or match JSON bodies with JSONPath.
  - [Responses](/docs/mocks/responses): Set the status, headers, cookies and body a mock returns.
  - [Call counts](/docs/mocks/call-counts): Control how many calls a mock answers, and find mocks that were never called.
  - [Failures and latency](/docs/mocks/failures-and-latency): Simulate dependencies that time out or respond slowly.
  - [HTTP clients](/docs/mocks/http-clients): Mock calls made with your own http.Client, and run mocked tests in parallel.
  - [Observing mocks](/docs/mocks/observing): Receive the request and response of every mocked call.
  - [Standalone mocks](/docs/mocks/standalone): Use apitest mocks in any test, such as a unit test of an HTTP client.
- Reports
  - [Sequence diagrams](/docs/reports/sequence-diagrams): Render each test as a sequence diagram of the request, every mocked call and the response.
  - [Database interactions](/docs/reports/database): Show the SQL queries a handler makes in its sequence diagram, with the x/db package.
  - [Custom reports](/docs/reports/custom-reports): Write your own report formatter, and add your own events to diagrams.

- **Guides**
- [Web frameworks](/docs/guides/frameworks): Test handlers built with chi, gin, echo, gorilla, fiber and other Go web frameworks.
- [Table-driven tests](/docs/guides/table-driven-tests): Cover many scenarios with one test, and share configuration between tests.
- [End-to-end tests](/docs/guides/end-to-end): Send requests over the network to a running server with EnableNetworking.
- [Debugging](/docs/guides/debugging): Print every request and response on the wire, and inspect them programmatically.
- [Handler timeouts](/docs/guides/timeouts): Test what clients see when a handler is too slow, and that handlers respect deadlines.
- [Test frameworks](/docs/guides/test-frameworks): Use apitest with Ginkgo and other frameworks, and replace how assertions are made.
- [AI coding agents](/docs/guides/ai-agents): Give Claude Code and other coding agents the apitest skill, and read these docs as Markdown.

- **Reference**
- [API overview](/docs/reference/api): Every exported type and method in apitest, grouped by where it is used.
- [Companion libraries](/docs/reference/companion-libraries): Modules that add assertions and report formats to apitest.
- [Examples](/docs/reference/examples): Complete example projects in the apitest repository, and the tested examples behind these docs.
- [Troubleshooting](/docs/reference/troubleshooting): Answers to the problems people run into most often.