truth

README

truth

Truth establishes a single source of truth for your API documentation, unit tests, integration tests, and full-stack HTTP tests for Golang Web applications.

This project was started while I was on vacation April 2016 and is under heavy development. Version 1.0 is right around the corner. Come back soon.

Links

Exported API via GoDocs

Documentation

Index

• Constants
• func JSON(v interface{}) []byte
• func MessageMimeType(key string) string
• func ResourceMIMEType(class string) string
• func RunIntegrationTests(t *testing.T, def Definition, cases TestCases, c *Client) error
• func SetMux(mux http.Handler)
• func TogglePrintAsTestsRun()
• func ToggleVerbose()
• func UsingCredentials(d *Definition)
• func UsingNoAuth(d *Definition)
• type BodyDefinition
• type Client
  • func NewClient(hostname string) *Client
  • func (c Client) BuildRequest(def Definition, tc TestCase) (*http.Request, error)
  • func (c Client) MakeRequest(md Definition, tc TestCase, result interface{}) (*http.Response, []byte, error)
  • func (c Client) ParseResponse(r *http.Response, result interface{}) ([]byte, error)
• type Definition
  • func Configure(d Definition, options ...func(*Definition)) Definition
  • func (def *Definition) Init() error
• type Integration
• type Runner
  • func NewRunner(c *Client) Runner
• type TestCase
• type TestCases
• type Unit

Constants

const (
	// POST HTTP POST Request Method
	POST = "POST"
	// GET HTTP GET Request Method
	GET = "GET"
	// HEAD HTTP HEAD Request Method
	HEAD = "HEAD"
	// PUT HTTP PUT Request Method
	PUT = "PUT"
	// PATCH HTTP PATCH Request Method
	PATCH = "PATCH"
	// DELETE HTTP DELETE Request Method
	DELETE = "DELETE"
	// CONNECT HTTP CONNECT Request Method
	CONNECT = "CONNECT"
	// OPTIONS HTTP OPTIONS Request Method
	OPTIONS = "OPTIONS"
	// TRACE HTTP TRACE Request Method
	TRACE = "TRACE"

	// AuthorizationCredentials marks a resource as requiring credentials
	// be supplied.
	AuthorizationCredentials = "credentials"
	// AuthenticationChecksum marks a resource as requiring a checksum
	// be supplied.
	AuthenticationChecksum = "checksum"
	// AuthorizationOpenID marks a resource as requiring OpenID credentials.
	AuthorizationOpenID = "openID"
	// AuthorizationNone marks a resource as not requiring credentials.
	AuthorizationNone = "insecure"
)

const (
	MIMETypeJSON = "application/json"
	MIMETypeXML  = "application/xml"
	MIMETypeGOB  = "application/gob"
)

Functions

func JSON

func JSON(v interface{}) []byte

JSON is a simple convenience function to serialize a result into JSON which helps test authors create JSON values without checking for errors.

A common use-case is to set an 'ExpectBody' value into a test case:

testcase := truth.TestCase {
	Name:   "Expect Error",
	Status: 400,
	Payload: RegisterPayload{
		Name:     "John Conner",
		Email:    "jconner@cyberdyne-systems.com",
		Password: "Th3Futur3IsN0tS3T",
	},
	ExpectBody: truth.JSON(map[string]string{
		"error": "Unknown username or password",
	},
}

func MessageMimeType

func MessageMimeType(key string) string

MessageMimeType returns a traditional mimetype to communicate the encoding of a message. Example:

application/json

Preference is to pass one of the known mimetype constants. Example:

json

If the provided key is unknown it will simply be returned prefixed as follows:

application/{key}

func ResourceMIMEType

func ResourceMIMEType(class string) string

ResourceMIMEType builds a custom mimetype such as

application/vnd.{your-namespace}.user

using the provided class. The formula is:

application/vnd.{your-namespace}.{class}.

If an endpoint is working with messages and not domain specific resources use the `MessageMimeType` which focuses only on the encoding.

func RunIntegrationTests

func RunIntegrationTests(t *testing.T, def Definition, cases TestCases, c *Client) error

RunIntegrationTests runs integration or full-stack tests using the provided metadata and test cases. Provide a client to perform full-stack. If nil is provided the server's Mux will be called directly.

func SetMux

func SetMux(mux http.Handler)

SetMux allows the mux under test to be access by the truth test harness.

func TogglePrintAsTestsRun

func TogglePrintAsTestsRun()

func ToggleVerbose

func ToggleVerbose()

func UsingCredentials

func UsingCredentials(d *Definition)

UsingCredentials specifies that the provided definition requires authentication to be accessed.

func UsingNoAuth

func UsingNoAuth(d *Definition)

UsingNoAuth specifies that the provided definition does not require authentication to be accessed.

Types

type BodyDefinition

type BodyDefinition struct {
	// PackageName holds a representation of the package holding the response.
	// Typically if the response is not a custom type, this will be blank.
	PackageName string

	// Data holds a reference to the data structure that defines the body.
	Data interface{}
}

type Client

type Client struct {
	Hostname string
}

func NewClient

func NewClient(hostname string) *Client

func (Client) BuildRequest

func (c Client) BuildRequest(def Definition, tc TestCase) (*http.Request, error)

NewRequest builds an HTTP Request for tests using the provided metadata. If non-empty string is provided for the path it will be used instead of the metadata's path which is useful for route params embedded within the path such as:

/users/:name

Optionally, a payload and headers may be provided.

func (Client) MakeRequest

func (c Client) MakeRequest(md Definition, tc TestCase, result interface{}) (*http.Response, []byte, error)

MakeRequest dispatches an HTTP request. If a payload is provided the response body will be read. If the returned status code is 2XX the response will be unmarshalled into the result. Provide a `nil` result to manage unmarshalling manually.

func (Client) ParseResponse

func (c Client) ParseResponse(r *http.Response, result interface{}) ([]byte, error)

type Definition

type Definition struct {
	// Properties that drive behavior.
	Method           string
	Path             string
	MIMETypeRequest  string
	MIMETypeResponse string

	RequestHeaders  map[string]string
	ResponseHeaders map[string]string
	// InputParams URL Path variables /users/{ID}
	InputParams interface{}
	// QueryParams Query string parameters
	QueryParams  interface{}
	RequestBody  BodyDefinition
	ResponseBody BodyDefinition

	Authenticated  bool
	Authentication string

	Package     string // Unique name or path to the package. Useful for generated documentation.
	Description string // Description of the endpoint to be used in generated documentation.
	Name        string // Name of the endpoint to be used in generated documentation.
	StatsKey    string // Key for instrumentation metrics.
	// contains filtered or unexported fields
}

Definition defines an API endpoint.

func Configure

func Configure(d Definition, options ...func(*Definition)) Definition

Configure returns a new Metadata struct initialized to default values unless customized by passing optional functions.

func (*Definition) Init

func (def *Definition) Init() error

Init bootstraps a new Definition unless the given Definition is already marked as initialized.

type Integration

type Integration struct {
	*testing.T
	TC     TestCase
	Body   []byte
	RR     *httptest.ResponseRecorder
	Client *Client
	Runner Runner
}

type Runner

type Runner func(t *testing.T, md Definition, tc TestCase) error

func NewRunner

func NewRunner(c *Client) Runner

NewRunner builds a function to test an API endpoint. Provide a client to perform a full-stack call to a webserver. Without a client the server MUX will be called directly to perform the test in-process.

type TestCase

type TestCase struct {
	Name       string
	Path       string
	Headers    map[string]string
	Payload    interface{}
	Status     int
	ExpectBody []byte
	Contains   []string

	Result interface{}

	Verbose     bool
	Integration func(Integration)
	Unit        func(Unit)
	// contains filtered or unexported fields
}

TestCase structures a specific test which can be applied unit, integration, full-stack, or load testing.

type TestCases

type TestCases []*TestCase

type Unit

type Unit struct {
	*testing.T
	TC     TestCase
	Result interface{}
	Err    error
}