api

Documentation

Overview

Package api provides wrappers around net/http types that support stubbing.

Index

• func MatchAny(*http.Request) bool
• type Client
  • func NewClient() *Client
  • func NewClientWith(opts *ClientOptions) *Client
  • func (c *Client) IsStubbed() bool
  • func (c *Client) RegisterStub(matcher Matcher, responder Responder) *Client
  • func (c *Client) VerifyStubs(t testable)
  • func (c *Client) WithStubbing() *Client
• type ClientOptions
• type Matcher
  • func MatchDelete(path string) Matcher
  • func MatchGet(path string) Matcher
  • func MatchPatch(path string) Matcher
  • func MatchPost(path string) Matcher
  • func MatchPut(path string) Matcher
  • func MatchRequest(method string, path string) Matcher
  • func MatchRequestQuery(method string, path string, query url.Values) Matcher
• type RESTClient
  • func NewRESTClient(opts *ClientOptions) *RESTClient
  • func (c *RESTClient) Delete(path string, resp any) error
  • func (c *RESTClient) Do(method string, path string, body any, response any) error
  • func (c *RESTClient) DoWithContext(ctx context.Context, method string, url string, payload any, response any) error
  • func (c *RESTClient) Get(path string, resp any) error
  • func (c *RESTClient) Patch(path string, body any, resp any) error
  • func (c *RESTClient) Post(path string, body any, resp any) error
  • func (c *RESTClient) Put(path string, body any, resp any) error
  • func (c *RESTClient) RegisterStub(matcher Matcher, responder Responder) *RESTClient
  • func (c *RESTClient) WithStubbing() *RESTClient
• type RESTClientError
  • func (e *RESTClientError) Error() string
• type Responder
  • func ErrorResponse(err error) Responder
  • func FileResponse(filename string) Responder
  • func JSONResponse(data interface{}) Responder
  • func StringResponse(body string) Responder
  • func WithHeader(header string, value string, responder Responder) Responder
  • func WithRequestHeaders(responder Responder) Responder
  • func WithStatus(status int, responder Responder) Responder
• type Stub
• type StubbedTransport
  • func NewStubbedTransport() *StubbedTransport
  • func (t *StubbedTransport) RegisterStub(matcher Matcher, responder Responder) *StubbedTransport
  • func (t *StubbedTransport) RoundTrip(req *http.Request) (*http.Response, error)
  • func (t *StubbedTransport) VerifyStubs(test testable)

Functions

func MatchAny

func MatchAny(*http.Request) bool

MatchAny is a matcher that matches any request.

Types

type Client

type Client struct {
	*http.Client
}

Client is a wrapper around net/http.Client that supports stubbing.

func NewClient

func NewClient() *Client

NewClient returns a new client configured with default options.

func NewClientWith

func NewClientWith(opts *ClientOptions) *Client

NewClientWith returns a new Client configured with opts.

func (*Client) IsStubbed

func (c *Client) IsStubbed() bool

IsStubbed returns true if the transport is configured for stubbing.

func (*Client) RegisterStub

func (c *Client) RegisterStub(matcher Matcher, responder Responder) *Client

RegisterStub registers a new stub for the given matcher/responder pair.

func (*Client) VerifyStubs

func (c *Client) VerifyStubs(t testable)

VerifyStubs fails the test if there are unmatched stubs.

func (*Client) WithStubbing

func (c *Client) WithStubbing() *Client

WithStubbing configures stubbing and returns the receiver.

type ClientOptions

type ClientOptions struct {
	// AuthToken is the authorization token included on requests made to BaseURL.
	AuthToken string

	// BaseURL is the base URL for relative API requests.
	BaseURL string

	// Headers are the HTTP headers that will be sent with every API request.
	Headers map[string]string

	// Timeout specifies a time limit for each API request.
	// Default is no timeout.
	Timeout time.Duration

	// Transport specifies the mechanism by which individual API requests are made.
	// Default is http.DefaultTransport.
	Transport http.RoundTripper
}

ClientOptions allow for configuring new clients.

type Matcher

type Matcher func(req *http.Request) bool

func MatchDelete

func MatchDelete(path string) Matcher

func MatchGet

func MatchGet(path string) Matcher

func MatchPatch

func MatchPatch(path string) Matcher

func MatchPost

func MatchPost(path string) Matcher

func MatchPut

func MatchPut(path string) Matcher

func MatchRequest

func MatchRequest(method string, path string) Matcher

MatchRequest creates a matcher that matches on method and path.

func MatchRequestQuery

func MatchRequestQuery(method string, path string, query url.Values) Matcher

MatchRequestQuery creates a matcher that matches on method, path, and query params.

type RESTClient

type RESTClient struct {
	*Client
	BaseURL string
}

RESTClient is a client wrapper for HTTP requests that return JSON.

func NewRESTClient

func NewRESTClient(opts *ClientOptions) *RESTClient

func (*RESTClient) Delete

func (c *RESTClient) Delete(path string, resp any) error

Delete performs a HTTP Delete and parses the response JSON into resp.

func (*RESTClient) Do

func (c *RESTClient) Do(method string, path string, body any, response any) error

Do performs a HTTP request from the given args and parses the response as JSON.

func (*RESTClient) DoWithContext

func (c *RESTClient) DoWithContext(ctx context.Context, method string, url string, payload any, response any) error

DoWithContext performs a HTTP request from the given args and parses the returned text as JSON into the response struct.

• url may be a path (relative to BaseURL), or an absolute URL.
• body may be either a JSON encodable struct, or an io.Reader.
• response may be a JSON encodable struct (or nil if unused).

Note: Absolute URLs will only include the auth token if they share the same root domain.

func (*RESTClient) Get

func (c *RESTClient) Get(path string, resp any) error

Get performs a HTTP Get and parses the response JSON into resp.

func (*RESTClient) Patch

func (c *RESTClient) Patch(path string, body any, resp any) error

Patch performs a HTTP Patch and parses the response JSON into resp.

func (*RESTClient) Post

func (c *RESTClient) Post(path string, body any, resp any) error

Post performs a HTTP Post and parses the response JSON into resp.

func (*RESTClient) Put

func (c *RESTClient) Put(path string, body any, resp any) error

Put performs a HTTP Put and parses the response JSON into resp.

func (*RESTClient) RegisterStub

func (c *RESTClient) RegisterStub(matcher Matcher, responder Responder) *RESTClient

RegisterStub registers a new stub for the given matcher/responder pair.

func (*RESTClient) WithStubbing

func (c *RESTClient) WithStubbing() *RESTClient

WithStubbing configures stubbing and returns the receiver.

type RESTClientError

type RESTClientError struct {
	HTTPResponse *http.Response
	Message      string
}

func (*RESTClientError) Error

func (e *RESTClientError) Error() string

type Responder

type Responder func(req *http.Request) (*http.Response, error)

func ErrorResponse

func ErrorResponse(err error) Responder

ErrorResponse creates a responder that returns err.

func FileResponse

func FileResponse(filename string) Responder

FileResponse creates a responder that returns the content located at filename.

func JSONResponse

func JSONResponse(data interface{}) Responder

JSONResponse creates a responder that serializes and returns data.

func StringResponse

func StringResponse(body string) Responder

StringResponse creates a responder that returns body.

func WithHeader

func WithHeader(header string, value string, responder Responder) Responder

WithHeader wraps a responder so that it responds with the provided HTTP header.

func WithRequestHeaders

func WithRequestHeaders(responder Responder) Responder

WithRequestHeaders wraps a responder so that it responds with all HTTP headers from the request.

func WithStatus

func WithStatus(status int, responder Responder) Responder

WithStatus wraps a responder so that it responds with the provided HTTP status code.

type Stub

type Stub struct {
	Matched   bool
	Matcher   Matcher
	Responder Responder
}

Stub is a stubbed HTTP response for a specific match pattern.

type StubbedTransport

type StubbedTransport struct {
	Requests []*http.Request
	// contains filtered or unexported fields
}

StubbedTransport is a net/http.RoundTripper that serves stubbed responses.

func NewStubbedTransport

func NewStubbedTransport() *StubbedTransport

func (*StubbedTransport) RegisterStub

func (t *StubbedTransport) RegisterStub(matcher Matcher, responder Responder) *StubbedTransport

RegisterStub registers a new stub for the given matcher/responder pair.

func (*StubbedTransport) RoundTrip

func (t *StubbedTransport) RoundTrip(req *http.Request) (*http.Response, error)

RoundTrip implements the RoundTripper interface. Will attempt to match a registered stub or return an error if none found.

func (*StubbedTransport) VerifyStubs

func (t *StubbedTransport) VerifyStubs(test testable)

VerifyStubs fails the test if there are unmatched stubs.