bacom

README

Bacom

Pronounced like bacon, but for compatibility.

Bacom will help you test JSON apis for backward-compatibility breaking changes.

Installing bacom

Downloading the compiled binary

• Download the latest version of the binary: releases
• extract the archive and place the bacom binary in your $PATH

From source

• Have go 1.8 or greater installed: golang.org
• run go get -u github.com/yazgazan/bacom/cmd/bacom

Usage

Bacom works by comparing a live (locale or testing) version against one or more "known" versions of a service. These known versions are stored in a bacom-tests folder as request/responses pairs.

bacom-tests/
├── config.json
├── v0.0.1
│   ├── api-call_req.txt
│   ├── api-call_resp.txt
│   ├── api-call2_req.txt
│   ├── api-call2_resp.txt
│   ├── api-call3_req.txt
│   └── api-call3_resp.txt
└── v1.0.0
│   ├── api-call_req.txt
│   ├── api-call_resp.txt
│   ├── api-call2_req.txt
│   ├── api-call2_resp.txt
│   ├── api-call3_req.txt
│   ├── api-call3_resp.txt
│   ├── api-call4_req.txt
│   └── api-call4_resp.txt

Importing requests and responses

Requests and responses can be imported from two formats: har and curl.

The HAR format can be used to import requests from google-chrome and firefox, by exporting one or all requests/responses from the network tab. Important to note is that the response bodies won't be present when exporting all requests from google-chrome (these can be generated later via the bacom test command).

Importing from HAR files:

bacom import har -out=bacom-tests/v0.0.1 har_files/*.har

The curl import format allows you to import a request using the same command-line options as curl:

bacom import curl -X POST -H "Content-Type: application/json" -d '{"foo": ["bar"]}' "http://localhost:8080/api/endpoint" -dir=bacom-tests/v0.0.1 -name="post-api-endpoint"

The curl import can be used to import requests from many sources: google-chrome, firefox, postman, etc.

Testing a new version

When testing a new version, bacom will replay the requests from older versions against a live endpoint. A diff will be generated for the request's status code, headers and JSON body.

When comparing the bodies, two kind of errors will be reported:

• Invalid type: the type of a JSON key changed in the new version.
• Missing key: a key is absent in the new version.

Differences in content are not reported.

Testing against versions up (but excluding) v2.0.0:

bacom test -version="<=v1.x" -target-host=localhost:8080

A configuration file can be used to specify headers and JSON paths to ignore in the diff:

bacom test -conf=bacom-ignore.json -version="<=v1.x" -target-host=localhost:8080

Saving responses for a new version

Once a new version is fixed (considered correct), requests and responses can be generated based on the old versions requests:

bacom test -version="<=v1.x" -target-host=localhost:8080 -save=v2.0.0

Planned features

• Supporting HTTP trailers
• Supporting more import formats (Postman and Insomnia)
• Supporting custom validators

Documentation

Index

• Variables
• func Compare(ignore, ignoreMissing []string, ignoreNull bool, lhs, rhs interface{}) ([]string, error)
• func CompareHeaders(ignore, ignoreContent []string, lhs, rhs http.Header) ([]string, error)
• func FindVersions(dir string, verbose bool, constraints Constraints) (files []string, err error)
• func GetRequestsFiles(dirname string) (files []string, err error)
• func GetResponseFilename(reqFname string) (string, error)
• func IsRequestFilename(fname string) bool
• func MatchPath(pattern, fpath string) (bool, error)
• func NameFromReqFileName(fname string) (string, error)
• func Prune(d diff.Differ, ignoreNull bool) diff.Differ
• func ReadResponse(req *http.Request, reqFname string) (resp *http.Response, err error)
• func ReqFileName(name, dir string) string
• func VersionMatch(verbose bool, constraints Constraints, s string) (bool, error)
• type Constraints
• type IgnoreMissingPrunner
  • func (p IgnoreMissingPrunner) Prune(d diff.Differ) diff.Differ
• type IgnorePrunner
  • func (p IgnorePrunner) Prune(d diff.Differ) diff.Differ
• type Saver
  • func NewSaver(dir, fname string) *Saver
  • func (s *Saver) SaveRequest() error
  • func (s *Saver) SaveResponse(resp *http.Response) error

Variables

var (
	// ErrReqInvalidName is returned when a request filename
	// does not follow the _req[0-9]*.txt pattern
	ErrReqInvalidName = errors.New("invalid filename for request")
)

Functions

func Compare

func Compare(ignore, ignoreMissing []string, ignoreNull bool, lhs, rhs interface{}) ([]string, error)

Compare returns a list of differences between two json objects. The ignore and ignoreMissing parameters are a list of JSON paths that should be ignored. If ignoreNull is true, nil values in the lhs won't be tested.

func CompareHeaders

func CompareHeaders(ignore, ignoreContent []string, lhs, rhs http.Header) ([]string, error)

CompareHeaders returns a list of differences between two http.Header. ignore and ignoreContent are expected to be normalized http headers names.

func FindVersions

func FindVersions(dir string, verbose bool, constraints Constraints) (files []string, err error)

FindVersions returns the versions (folders) found that match the provided constraints

func GetRequestsFiles

func GetRequestsFiles(dirname string) (files []string, err error)

GetRequestsFiles returns a list of request files matching the _req[0-9]*.txt pattern

func GetResponseFilename

func GetResponseFilename(reqFname string) (string, error)

GetResponseFilename transform a _req[0-9]*.txt filename into a _resp[0-9]*.txt

func IsRequestFilename

func IsRequestFilename(fname string) bool

IsRequestFilename returns true if fname matches the request filename pattern (_req[0-9]*.txt)

func MatchPath

func MatchPath(pattern, fpath string) (bool, error)

MatchPath uses path.Match to match a full path against a pattern. In addition to the path.Match pattern syntax, \** can be used to match any number of folder names.

func NameFromReqFileName

func NameFromReqFileName(fname string) (string, error)

NameFromReqFileName extracts the request name from the filename (removing the _req[0-9]*.txt suffix)

func Prune

func Prune(d diff.Differ, ignoreNull bool) diff.Differ

Prune returns a diff.Differ, stripping the diff tree of the following differences:

- Excess keys in the right hand side - Excess and Missing values in slices - Values of the same type with different content (excluding slices and maps) - Type difference where null is involved

func ReadResponse

func ReadResponse(req *http.Request, reqFname string) (resp *http.Response, err error)

ReadResponse reads the response in reqFname given the provided request

func ReqFileName

func ReqFileName(name, dir string) string

ReqFileName finds the first appropriate request filename that doesn't translate to an existing file on disk

func VersionMatch

func VersionMatch(verbose bool, constraints Constraints, s string) (bool, error)

VersionMatch parses and check the version s against the provided constraints

Types

type Constraints

type Constraints interface {
	Validate(*semver.Version) (bool, []error)
}

Constraints is an interface for semver.Constraints

type IgnoreMissingPrunner

type IgnoreMissingPrunner []string

IgnoreMissingPrunner can be used to ignore missing json paths (from the right hand side) in a diff tree

func (IgnoreMissingPrunner) Prune

func (p IgnoreMissingPrunner) Prune(d diff.Differ) diff.Differ

Prune Removes ignored diff branches from the diff tree

type IgnorePrunner

type IgnorePrunner []string

IgnorePrunner can be used to ignore json paths in a diff tree

func (IgnorePrunner) Prune

func (p IgnorePrunner) Prune(d diff.Differ) diff.Differ

Prune Removes ignored diff branches from the diff tree

type Saver

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

Saver is used to handle saving or requests and responses to a new version

func NewSaver

func NewSaver(dir, fname string) *Saver

NewSaver returns a *Saver. `dir` is the output folder and `fname` is the name of the original request file

func (*Saver) SaveRequest

func (s *Saver) SaveRequest() error

SaveRequest moves the request file to the new folder (as specified in NewSaver). The file name is adjusted if file with the same name already exists at that location and if the files are not identical.

func (*Saver) SaveResponse

func (s *Saver) SaveResponse(resp *http.Response) error

SaveResponse saves the response to the appropriate file in the output directory. The name generated by SaveRequest is used to ensure the response has a matching file name.