crossdock

README

crossdock-go

A Go client for Crossdock

Documentation

Overview

Package crossdock implements the machinery for writing behaviors in a way similar to unit tests.

func MyBehavior(s behavior.Sink, p behavior.Params) {
	if p.Param("something") != "foo" {
		behavior.Failf(s, "expected foo, got %v", p.Param("something"))
	}
	behavior.Successf(s, "success")
}

Sinks can be obtained using the Run function. Sinks are not valid outside the Run context.

entries := behavior.Run(func(s Sink) {
	MyBehavior(s, someParams)
})

Index

• Constants
• func Call(t *testing.T, clientURL string, behavior string, args url.Values)
• func Combinations(axes map[string][]string) []map[string]string
• func Handler(behaviors Behaviors, failOnUnknown bool) http.Handler
• func Start(behaviors Behaviors)
• func Wait(t *testing.T, url string, attempts int)
• type Assertions
  • func Assert(t T) Assertions
  • func Checks(t T) Assertions
  • func Fatals(t T) Assertions
  • func Require(t T) Assertions
• type BehaviorFunc
• type Behaviors
• type Entry
  • func Run(params Params, f func(T)) []Entry
  • func (e Entry) Output() string
  • func (e Entry) Status() Status
• type Params
• type Status
• type T

Constants

const BehaviorParam = "behavior"

BehaviorParam is the url param representing the test to run

Functions

func Call

func Call(t *testing.T, clientURL string, behavior string, args url.Values)

Call makes a GET request to the client

func Combinations

func Combinations(axes map[string][]string) []map[string]string

Combinations takes a map from axis name to list of values for that axis and returns a collection of entries which contain all combinations of each axis value with every other axis' values.

func Handler

func Handler(behaviors Behaviors, failOnUnknown bool) http.Handler

Handler returns an http.Handler that dispatches to functions defined in behaviors map. If failOnUnknown is true, a behavior that is not in the behaviors map will cause the handler to return an error status. Otherwise, the handler returns skipped status.

func Start

func Start(behaviors Behaviors)

Start begins a blocking Crossdock client

func Wait

func Wait(t *testing.T, url string, attempts int)

Wait sends attempts HEAD requests to url

Types

type Assertions

type Assertions interface {
	Condition(comp assert.Comparison, msgAndArgs ...interface{}) bool
	Contains(s interface{}, contains interface{}, msgAndArgs ...interface{}) bool
	Empty(object interface{}, msgAndArgs ...interface{}) bool
	Equal(expected interface{}, actual interface{}, msgAndArgs ...interface{}) bool
	EqualError(theError error, errString string, msgAndArgs ...interface{}) bool
	EqualValues(expected interface{}, actual interface{}, msgAndArgs ...interface{}) bool
	Error(err error, msgAndArgs ...interface{}) bool
	Exactly(expected interface{}, actual interface{}, msgAndArgs ...interface{}) bool
	Fail(failureMessage string, msgAndArgs ...interface{}) bool
	FailNow(failureMessage string, msgAndArgs ...interface{}) bool
	False(value bool, msgAndArgs ...interface{}) bool
	Implements(interfaceObject interface{}, object interface{}, msgAndArgs ...interface{}) bool
	InDelta(expected interface{}, actual interface{}, delta float64, msgAndArgs ...interface{}) bool
	InDeltaSlice(expected interface{}, actual interface{}, delta float64, msgAndArgs ...interface{}) bool
	InEpsilon(expected interface{}, actual interface{}, epsilon float64, msgAndArgs ...interface{}) bool
	InEpsilonSlice(expected interface{}, actual interface{}, delta float64, msgAndArgs ...interface{}) bool
	IsType(expectedType interface{}, object interface{}, msgAndArgs ...interface{}) bool
	JSONEq(expected string, actual string, msgAndArgs ...interface{}) bool
	Len(object interface{}, length int, msgAndArgs ...interface{}) bool
	Nil(object interface{}, msgAndArgs ...interface{}) bool
	NoError(err error, msgAndArgs ...interface{}) bool
	NotContains(s interface{}, contains interface{}, msgAndArgs ...interface{}) bool
	NotEmpty(object interface{}, msgAndArgs ...interface{}) bool
	NotEqual(expected interface{}, actual interface{}, msgAndArgs ...interface{}) bool
	NotNil(object interface{}, msgAndArgs ...interface{}) bool
	NotPanics(f assert.PanicTestFunc, msgAndArgs ...interface{}) bool
	NotRegexp(rx interface{}, str interface{}, msgAndArgs ...interface{}) bool
	NotZero(i interface{}, msgAndArgs ...interface{}) bool
	Panics(f assert.PanicTestFunc, msgAndArgs ...interface{}) bool
	Regexp(rx interface{}, str interface{}, msgAndArgs ...interface{}) bool
	True(value bool, msgAndArgs ...interface{}) bool
	WithinDuration(expected time.Time, actual time.Time, delta time.Duration, msgAndArgs ...interface{}) bool
	Zero(i interface{}, msgAndArgs ...interface{}) bool
}

Assertions provides helpers to assert conditions in crossdock behaviors.

All assertions can include informative error messages formatted using fmt.Sprintf style,

assert := Assert(t)
assert.Contains(foo, "bar", "expected to find 'bar' in %q", foo)

All assert operations return true if the condition was met and false otherwise. This allows gating operations that would otherwise panic behind preconditions.

if assert.Error(t, err, "expected failure") {
	assert.Contains(t, err.Error(), "something went wrong", "error message mismatch")
}

Additionally, in case of failure, all Assertions make an attempt to provide a stack trace in the error message.

Four kinds of Assertions objects are offered via the corresponding functions:

Assert(T): All asserts will result in a success or failure being logged to the crossdock.T. Execution will continue on failure.

Checks(T): Only failures will be logged to crossdock.T. Execution will continue on failure.

Require(T): All asserts will result in a success or failure being logged to the crossdock.T. Execution of the behavior will be terminated immediately on failure.

Fatals(t): Only failures will be logged to crossdock.T. Execution of the behavior will be temrinated immediately on failure.

                     +--------+--------+---------+--------+
                     | Assert | Checks | Require | Fatals |
+--------------------+--------+--------+---------+--------+
| Log on success     | Yes    | No     | Yes     | No     |
+--------------------+--------+--------+---------+--------+
| Continue execution | Yes    | Yes    | No      | No     |
| on failure         |        |        |         |        |
+--------------------+--------+--------+---------+--------+

func Assert

func Assert(t T) Assertions

Assert builds an Assertions object that logs success or failure for all operations to the given T. The behavior will continue executing in case of failure.

The following will log exactly len(tests) entries.

assert := Assert(t)
for _, tt := range tests {
	assert.Equals(tt.want, f(tt.give), "expected f(%v) == %v", tt.give, tt.want)
}

func Checks

func Checks(t T) Assertions

Checks builds an Assertions object that logs only failures to the given T. The behavior will continue executing in case of failure.

The following will log only as many entries as invalid test cases.

checks := Checks(t)
for _, tt := range tests {
	checks.Equals(tt.want, f(tt.give), "expected f(%v) == %v", tt.give, tt.want)
}

func Fatals

func Fatals(t T) Assertions

Fatals builds an Assertions object that logs only failures to the given T. Execution of the behavior will be terminated immediately on the first failing assertion.

The following will log the first failure encountered or nothing if all test cases were succesful.

fatals := Fatals(t)
for _, tt := range tests {
	fatals.Equals(tt.want, f(tt.give), "expected f(%v) == %v", tt.give, tt.want)
}

func Require

func Require(t T) Assertions

Require builds an Assertions object that logs success or failure for all operations to the given T. Execution of the behavior will be terminated immediately on the first failing assertion.

The following will log one entry for each successful test case starting at the first one and the first failure that is encountered.

require := Require(t)
for _, tt := range tests {
	require.Equals(tt.want, f(tt.give), "expected f(%v) == %v", tt.give, tt.want)
}

type BehaviorFunc

type BehaviorFunc func(t T)

BehaviorFunc executes a set of tests against T

type Behaviors

type Behaviors map[string]BehaviorFunc

Behaviors is a map of BehaviorFuncs to dispatch to

type Entry

type Entry map[string]interface{}

Entry is the most basic form of a test result.

func Run

func Run(params Params, f func(T)) []Entry

Run the given function inside a behavior context and return the entries logged by it.

Functions like Fatalf won't work if the behavior is not executed inside a Run context.

func (Entry) Output

func (e Entry) Output() string

Output returns the output attached to the entry.

func (Entry) Status

func (e Entry) Status() Status

Status returns the Status stored in the Entry.

type Params

type Params map[string]string

Params represents args to a test

type Status

type Status string

Status represents the result of running a behavior.

const (
	Passed  Status = "passed"
	Skipped Status = "skipped"
	Failed  Status = "failed"
)

Different valid Statuses.

type T

type T interface {
	Behavior() string

	// Look up a behavior parameter.
	Param(key string) string

	// Tag adds the given key-value pair to all entries emitted by this T from
	// this point onwards.
	//
	// If a key with the same name already exists, it will be overwritten.
	// If value is empty, the tag will be deleted from all entries that follow.
	//
	// key MUST NOT be "stauts" or "output".
	Tag(key, value string)

	// Log a failure and continue running the behavior.
	Errorf(format string, args ...interface{})

	// Log a skipped test and continue running the behavior.
	Skipf(format string, args ...interface{})

	// Log a success and continue running the behavior.
	Successf(format string, args ...interface{})

	// Log a failure and stop executing this behavior immediately.
	Fatalf(format string, args ...interface{})

	// Stop executing this behavior immediately.
	FailNow()

	// Put logs an entry with the given status and output. Usually, you'll want
	// to use Errorf, Skipf, Successf or Fatalf instead.
	Put(status Status, output string)
}

T records the result of calling different behaviors.