README
¶
Copper
Copper keeps REST APIs honest
Introduction
Copper is a test library intended to verify that API contracts are upheld when exercising a REST API from a test. This is very useful for verifying that all paths and functionality that is declared in an API spec is in fact tested.
Why?
Implementing these checks in tests will allow your application to check API correctness and backwards compatibility before the code ever hits production. As long as the specification and application is not edited in the same change set, breaking changes will also be prevented. Since the verification runs during builds only, there is no overhead during production use, nor does Copper impose any sort of requirements on the implementation other than that it needs to conform to its own specification.
Usage
Copper is used from integration style tests. Wrap the HTTP client being used in copper and then use that client for performing the API calls in your test case. This works best from a single main test for a single spec, and then subtest for the specific endpoints/use cases.
func TestVersion1(t *testing.T) {
f, err := os.Open("spec.yaml")
if err != nil {
t.Fatal(err)
}
defer f.Close()
client, err := copper.WrapClient(http.DefaultClient, f)
if err != nil {
t.Fatal(err)
}
t.Run("ping", func(t *testing.T) {
testPingEndpoints(t, client)
}
t.Run("other use case that I have", func(t *testing.T) {
testMyOtherThing(t, client)
}
// Verifying at the end checks that all paths, methods and responses are covered and that no extra paths have been hit.
client.Verify(t)
}
See the examples for complete examples.
Documentation
¶
Index ¶
- Variables
- type Option
- type SentinelError
- type ValidatingClient
- func (v *ValidatingClient) Delete(url string) (resp *http.Response, err error)
- func (v *ValidatingClient) Do(r *http.Request) (*http.Response, error)
- func (v *ValidatingClient) Get(url string) (resp *http.Response, err error)
- func (v *ValidatingClient) Head(url string) (resp *http.Response, err error)
- func (v *ValidatingClient) Post(url string, contentType string, body io.Reader) (resp *http.Response, err error)
- func (v *ValidatingClient) Put(url string, contentType string, body io.Reader) (resp *http.Response, err error)
- func (v *ValidatingClient) WithClient(c *http.Client) (*ValidatingClient, error)
- type VerificationError
- type Verifier
Constants ¶
This section is empty.
Variables ¶
var ( ErrNotChecked = SentinelError{"not checked"} ErrNotPartOfSpec = SentinelError{"not part of spec"} ErrResponseInvalid = SentinelError{"response invalid"} ErrRequestInvalid = SentinelError{"request invalid"} )
Functions ¶
This section is empty.
Types ¶
type Option ¶
type Option func(c *config)
func WithBasePath ¶
WithBasePath is a functional Option for setting the base path of the validator.
func WithInternalServerErrors ¶ added in v0.3.0
func WithInternalServerErrors() Option
WithInternalServerErrors is a functional Option for also validating server responses. These are skipped by default since a server should not ideally have internal server errors, and even if they are not part of a specification, they considered a possible response from an API.
type SentinelError ¶ added in v0.3.0
type SentinelError struct {
// contains filtered or unexported fields
}
func (SentinelError) Error ¶ added in v0.3.0
func (s SentinelError) Error() string
type ValidatingClient ¶
type ValidatingClient struct {
*Verifier
// contains filtered or unexported fields
}
ValidatingClient provides an HTTP client, and wraps the main methods, recording any and all paths that are being called.
func WrapClient ¶
WrapClient takes an HTTP client and io.Reader for the OpenAPI spec. The spec is parsed, and wraps the client so that the outbound calls are now recorded when made.
func (*ValidatingClient) Delete ¶
func (v *ValidatingClient) Delete(url string) (resp *http.Response, err error)
Delete records response for HTTP DELETE requests
func (*ValidatingClient) Do ¶
Do takes any http.Request, sends it to the server it and then records the result.
func (*ValidatingClient) Get ¶
func (v *ValidatingClient) Get(url string) (resp *http.Response, err error)
Get is a convenience method for recording responses for HTTP GET requests
func (*ValidatingClient) Head ¶
func (v *ValidatingClient) Head(url string) (resp *http.Response, err error)
Head is a convenience method for recording responses for HTTP HEAD requests
func (*ValidatingClient) Post ¶
func (v *ValidatingClient) Post(url string, contentType string, body io.Reader) (resp *http.Response, err error)
Post is a convenience method for recording responses for HTTP POST requests
func (*ValidatingClient) Put ¶
func (v *ValidatingClient) Put(url string, contentType string, body io.Reader) (resp *http.Response, err error)
Put is a convenience method for recording responses for HTTP PUT requests
func (*ValidatingClient) WithClient ¶
func (v *ValidatingClient) WithClient(c *http.Client) (*ValidatingClient, error)
WithClient returns a new client using the same validator, but a new client. This can be useful to change transport or authorization settings, while still contributing to the same spec validation.
type VerificationError ¶ added in v0.3.0
type VerificationError struct {
// contains filtered or unexported fields
}
func (*VerificationError) Error ¶ added in v0.3.0
func (v *VerificationError) Error() string
func (*VerificationError) Sentinel ¶ added in v0.3.0
func (v *VerificationError) Sentinel() error
func (*VerificationError) Unwrap ¶ added in v0.3.0
func (v *VerificationError) Unwrap() []error
type Verifier ¶
type Verifier struct {
// contains filtered or unexported fields
}
func NewExactVerifier ¶ added in v0.3.0
NewExactVerifier does not skip any part of the spec, for example internal server errors, and will require them to be checked if defined in the spec.
func NewVerifier ¶
NewVerifier takes bytes for an OpenAPI spec and a base path, and then returns a new Verifier that contains the declared paths. NewVerifier will not check internal server errors even if they are included in the spec.
func (*Verifier) CurrentError ¶ added in v0.3.0
CurrentError is a convenience method for CurrentErrors, where the errors are joined into a single error, making it easier to check.
func (*Verifier) CurrentErrors ¶ added in v0.3.0
CurrentErrors return the current collection of errors in the verifier.
Source Files
Directories