httpdump

README

httpdump

Installation

To use this package, you can import it like so:

import "github.com/alextanhongpin/testdump/httpdump"

Overview

The dump/http package provides utilities for dumping HTTP requests and responses in Go. It includes functionality for capturing, comparing, and storing HTTP request/response snapshots, which can be useful for snapshot testing.

Usage

Creating a New Handler

You can create a new handler using the NewHandler function. This function takes a testing.T instance, an http.Handler, and an optional list of transformers. Here's an example:

h := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
  w.WriteHeader(http.StatusOK)
  w.Write([]byte("Hello, World!"))
})

hd := httpdump.Handler(t, h)

Serving HTTP Requests

You can use the ServeHTTP method of the Handler struct to serve HTTP requests. Here's an example:

wr := httptest.NewRecorder()
r := httptest.NewRequest(http.MethodGet, "/", nil)

hd.ServeHTTP(wr, r)

Testing the Response

The httpdump package does not modify the original request or response payload. You can test the response of the handler using the Result method of the ResponseRecorder and the ReadAll function from the io package. Here's an example:

w := wr.Result()
if w.StatusCode != http.StatusOK {
  t.Errorf("want %d, got %d", http.StatusOK, w.StatusCode)
}
defer w.Body.Close()
b, err := io.ReadAll(w.Body)
if err != nil {
  t.Fatal(err)
}

want := "Hello, World!"
got := string(bytes.TrimSpace(b))
if want != got {
  t.Errorf("want %s, got %s", want, got)
}

Testdata Snapshot

The dump/http package also provides a convenient way to generate example snapshots for testing purposes. In the testdata directory of the package, you can find pre-generated snapshots that represent expected HTTP request/response pairs. These snapshots can be used as a reference to prevent regression in your code.

Here is an example from the testdata/TestDump.http

-- request.http --
GET / HTTP/1.1
Host: example.com

-- response.http --
HTTP/1.1 200 OK
Connection: close

Hello, World!

Transformers

Transformers allows modifying the request/response body before snapshotting. You can for example mask headers that contains random or sensitive values.

mw := []httpdump.Transformer{
  // Second middleware will overwrite the first.
  httpdump.MaskRequestHeader("[REDACTED]", "Date"),
  httpdump.MaskResponseHeader("[REDACTED]", "Date"),
  httpdump.MaskRequestBody("[REDACTED]", "password"),
  httpdump.MaskResponseBody("[REDACTED]", "accessToken"),
}
hd := httpdump.NewHandlerFunc(t, h, mw...)
hd.ServeHTTP(wr, r)

Ignoring JSON fields from comparison

If the JSON request contains dynamic values such as uuid or datetime, you can skip those fields from comparison:

hd := httpdump.HandlerFunc(t, h,
  httpdump.IgnoreRequestFields("createdAt"),
  httpdump.IgnoreResponseFields("id"),
)
hd.ServeHTTP(wr, r)

Diff

When the content of the generated dump doesn't match the snapshot, you can see the diff error.

➜  http git:(http) ✗ gotest
--- FAIL: TestDump (0.00s)
    http_test.go:30: Response Body:

          Snapshot(-)
          Received(+)


          string(
        -       "Hello, world!",
        +       "Hello, World!",
          )

FAIL
exit status 1
FAIL    github.com/alextanhongpin/testdump/http     0.449s

Documentation

Index

• func Dump(t *testing.T, w *http.Response, r *http.Request, opts ...Option)
• func Handler(t *testing.T, h http.Handler, opts ...Option) http.Handler
• func HandlerFunc(t *testing.T, h http.HandlerFunc, opts ...Option) http.Handler
• func Write(h *HTTP, pretty bool) ([]byte, error)
• type CompareMessageOption
  • func (c CompareMessageOption) Merge(o CompareMessageOption) CompareMessageOption
• type CompareOption
  • func (c CompareOption) Merge(o CompareOption) CompareOption
• type Dumper
  • func New(opts ...Option) *Dumper
  • func (d *Dumper) Dump(t *testing.T, w *http.Response, r *http.Request, opts ...Option)
  • func (d *Dumper) Handler(t *testing.T, h http.Handler, opts ...Option) http.Handler
  • func (d *Dumper) HandlerFunc(t *testing.T, h http.HandlerFunc, opts ...Option) http.Handler
• type HTTP
  • func Read(b []byte) (*HTTP, error)
  • func (h *HTTP) Clone() (*HTTP, error)
• type Message
  • func NewComparableRequest(r *http.Request) (*Message, error)
  • func NewComparableResponse(r *http.Response) (*Message, error)
• type Option
  • func Body(body bool) Option
  • func CmpOpt(opt CompareOption) Option
  • func Colors(colors bool) Option
  • func Env(env string) Option
  • func File(file string) Option
  • func IgnoreRequestFields(val ...string) Option
  • func IgnoreRequestHeaders(val ...string) Option
  • func IgnoreResponseFields(val ...string) Option
  • func IgnoreResponseHeaders(val ...string) Option
  • func IndentJSON(indent bool) Option
  • func MaskRequestFields(mask string, fields ...string) Option
  • func MaskRequestHeaders(mask string, fields ...string) Option
  • func MaskResponseFields(mask string, fields ...string) Option
  • func MaskResponseHeaders(mask string, fields ...string) Option
  • func Transformers(ts ...Transformer) Option
• type RoundTripper
  • func RoundTrip(t *testing.T, opts ...Option) *RoundTripper
  • func (rt *RoundTripper) RoundTrip(r *http.Request) (*http.Response, error)
• type Transformer

Functions

func Dump

func Dump(t *testing.T, w *http.Response, r *http.Request, opts ...Option)

Dump is a function that takes a testing object, an HTTP response writer, an HTTP request, and a variadic list of options. It calls the Dumper's Dump method with these arguments.

func Handler

func Handler(t *testing.T, h http.Handler, opts ...Option) http.Handler

Handler is a function that takes a testing object, an HTTP handler, and a variadic list of options. It returns an HTTP handler that is wrapped with the Dumper's Handler method.

func HandlerFunc

func HandlerFunc(t *testing.T, h http.HandlerFunc, opts ...Option) http.Handler

HandlerFunc is similar to Handler, but it takes an HTTP handler function instead of an HTTP handler.

func Write

func Write(h *HTTP, pretty bool) ([]byte, error)

Write writes the request/response pair to bytes.

Types

type CompareMessageOption

type CompareMessageOption struct {
	Header  []cmp.Option
	Body    []cmp.Option
	Trailer []cmp.Option
}

func (CompareMessageOption) Merge

func (c CompareMessageOption) Merge(o CompareMessageOption) CompareMessageOption

type CompareOption

type CompareOption struct {
	Request  CompareMessageOption
	Response CompareMessageOption
}

func (CompareOption) Merge

func (c CompareOption) Merge(o CompareOption) CompareOption

type Dumper

type Dumper struct {
	// contains filtered or unexported fields
}

Dumper is a struct that holds a slice of options.

func New

func New(opts ...Option) *Dumper

New is a function that takes a variadic list of options and returns a new Dumper instance with these options.

func (*Dumper) Dump

func (d *Dumper) Dump(t *testing.T, w *http.Response, r *http.Request, opts ...Option)

Dump is a method on the Dumper struct that takes a testing object, an HTTP response writer, an HTTP request, and a variadic list of options. It appends the options to the Dumper's options and then calls the Snapshot function with the testing object, a new HTTP instance, and the options.

func (*Dumper) Handler

func (d *Dumper) Handler(t *testing.T, h http.Handler, opts ...Option) http.Handler

Handler is a method on the Dumper struct that takes a testing object, an HTTP handler, and a variadic list of options. It returns a new handler instance with these values.

func (*Dumper) HandlerFunc

func (d *Dumper) HandlerFunc(t *testing.T, h http.HandlerFunc, opts ...Option) http.Handler

HandlerFunc is similar to Handler, but it takes an HTTP handler function instead of an HTTP handler.

type HTTP

type HTTP struct {
	Request  *http.Request
	Response *http.Response
}

func Read

func Read(b []byte) (*HTTP, error)

Read reads the request/response pair from bytes.

func (*HTTP) Clone

func (h *HTTP) Clone() (*HTTP, error)

type Message

type Message struct {
	Line    string      `json:"line"`
	Header  http.Header `json:"header"`
	Body    any         `json:"body"`
	Trailer http.Header `json:"trailer"`
}

Message is a comparable representation of the request/response pair.

func NewComparableRequest

func NewComparableRequest(r *http.Request) (*Message, error)

func NewComparableResponse

func NewComparableResponse(r *http.Response) (*Message, error)

type Option

type Option func(o *options)

Option is a type that defines a function that takes an options instance and modifies it.

func Body

func Body(body bool) Option

Body is a function that takes a bool and returns an options that writes the body to the file if true.

func CmpOpt

func CmpOpt(opt CompareOption) Option

CmpOpt is a function that takes a CompareOption and returns an options that merges the CompareOption with the cmpOpt field of an options instance.

func Colors

func Colors(colors bool) Option

Colors is a function that takes a boolean and returns an options that sets the colors field of an options instance to the given boolean.

func Env

func Env(env string) Option

Env is a function that takes a string and returns an options that sets the env field of an options instance to the given string.

func File

func File(file string) Option

File allows setting the file name to write the output to.

func IgnoreRequestFields

func IgnoreRequestFields(val ...string) Option

IgnoreRequestFields is similar to IgnoreRequestHeaders, but it appends the strings to the Request.Body field of the cmpOpt field of an options instance.

func IgnoreRequestHeaders

func IgnoreRequestHeaders(val ...string) Option

IgnoreRequestHeaders is a function that takes a variadic list of strings and returns an options that appends the strings to the Request.Header field of the cmpOpt field of an options instance.

func IgnoreResponseFields

func IgnoreResponseFields(val ...string) Option

IgnoreResponseFields is similar to IgnoreRequestFields, but it appends the strings to the Response.Body field of the cmpOpt field of an options instance.

func IgnoreResponseHeaders

func IgnoreResponseHeaders(val ...string) Option

IgnoreResponseHeaders is similar to IgnoreRequestHeaders, but it appends the strings to the Response.Header field of the cmpOpt field of an options instance.

func IndentJSON

func IndentJSON(indent bool) Option

IndentJSON is a function that takes a boolean and returns an options that sets the indentJSON field of an options instance to the given boolean.

func MaskRequestFields

func MaskRequestFields(mask string, fields ...string) Option

MaskRequestFields is similar to MaskRequestHeaders, but the new transformer masks the request fields.

func MaskRequestHeaders

func MaskRequestHeaders(mask string, fields ...string) Option

MaskRequestHeaders is a function that takes a mask string and a variadic list of fields and returns an options that appends a new transformer to the transformers field of an options instance. The new transformer masks the request headers specified by the fields with the mask string.

func MaskResponseFields

func MaskResponseFields(mask string, fields ...string) Option

MaskResponseFields is similar to MaskRequestFields, but the new transformer masks the response fields.

func MaskResponseHeaders

func MaskResponseHeaders(mask string, fields ...string) Option

MaskResponseHeaders is similar to MaskRequestHeaders, but the new transformer masks the response headers.

func Transformers

func Transformers(ts ...Transformer) Option

Transformers is a function that takes a variadic list of transformers and returns an options that appends the transformers to the transformers field of an options instance.

type RoundTripper

type RoundTripper struct {
	// contains filtered or unexported fields
}

RoundTripper is a struct that holds a testing object and a slice of options.

func RoundTrip

func RoundTrip(t *testing.T, opts ...Option) *RoundTripper

RoundTrip is a function that takes a testing object and a variadic list of options. It returns a new RoundTripper instance with these values.

func (*RoundTripper) RoundTrip

func (rt *RoundTripper) RoundTrip(r *http.Request) (*http.Response, error)

RoundTrip is a method on the RoundTripper struct that takes an HTTP request. It clones the request, sends the request to the default transport, dumps the response, and then returns the response and any error.

type Transformer

type Transformer func(w *http.Response, r *http.Request) error