schreder

README

schreder - write tests and generate docs!

Simple test framework for testing RESTful API. Should be used against running dev instance of the API.

It allows to write tests in declarative way, then declaration can be used to generate documentation in various formats.

Installation

go get -u github.com/testmeifyoucan/schreder

Usage

Please check the test: https://github.com/testmeifyoucan/schreder/blob/master/schreder_test.go

And example: https://github.com/testmeifyoucan/schreder/tree/master/example

Advantages of such framework

• API tests and documentation with examples from the same box.
• Tests prove that documentation is correct. You can run tests first in order to ensure that you can publish your documentation.
• General purpose tool, works with already existing RESTful API. No need to add or change any line of code in your project, just use schreder as external tool.

Drawbacks

• Documentation covers tests, not actual code unfortunately. If tests don't follow the actual code, then documentation may miss something. You need to control test coverage yourself and manually ensure that tests cover all required cases. Or you can think something out and send us a Pull requests :).
• Swagger supports one declaration of request for each HTTP return code (1 declaration for code 200, one for 404 and so on). But what if you have different test cases and all of them produce the same 200 response code? Currently, only first test is used in such situation.
• It's difficult to define all properties of the swagger (like validators, formats) and make the code of the tests readable at the same time. Currently many things provided by swagger are ignored for sake of simplicity of the tests

Supported documentation formats

• Swagger 2.0
• RAML 0.8

Documentation

Index

• func AssertResponse(t *testing.T, expected interface{}, responseBody []byte) bool
• func NewRunner(baseUrl string, config RunnerConfig) *httpRunner
• type AssertResponseFunc
• type IDocGenerator
  • func NewRamlGenerator(seed raml.APIDefinition) IDocGenerator
  • func NewSwaggerGenerator(seed spec.Swagger, marshaller MarshallerFunc) IDocGenerator
  • func NewSwaggerGeneratorJSON(seed spec.Swagger) IDocGenerator
  • func NewSwaggerGeneratorJSONIndent(seed spec.Swagger) IDocGenerator
  • func NewSwaggerGeneratorYAML(seed spec.Swagger) IDocGenerator
• type IHttpClient
• type IHttpClientFunc
  • func (f IHttpClientFunc) Do(req *http.Request) (resp *http.Response, err error)
• type INameable
• type ITaggable
• type ITestRunner
• type MarshallerFunc
• type Param
• type ParamMap
• type RunnerConfig
• type Setuppable
• type Teardownable
• type Test
• type TestCase
  • func (testCase *TestCase) Url(urlpath string) (string, error)

Functions

func AssertResponse

func AssertResponse(t *testing.T, expected interface{}, responseBody []byte) bool

AssertResponse checks that given expected object contains the same data as provided responseBody.

func NewRunner

func NewRunner(baseUrl string, config RunnerConfig) *httpRunner

NewRunner creates new instance of HTTP runner

Types

type AssertResponseFunc

type AssertResponseFunc func(t *testing.T, expected interface{}, responseBody []byte) bool

AssertResponseFunc defines function that asserts that expected object equals to given response body

type IDocGenerator

type IDocGenerator interface {
	Generate(tests []Test) ([]byte, error)
}

IDocGenerator describes a generator of documentation uses test suite as a source of information about API endpoints

func NewRamlGenerator

func NewRamlGenerator(seed raml.APIDefinition) IDocGenerator

NewRamlGenerator creates an instance of RAML generator seed as used as a source of initial data for resulting doc

func NewSwaggerGenerator

func NewSwaggerGenerator(seed spec.Swagger, marshaller MarshallerFunc) IDocGenerator

NewSwaggerGenerator creates a new instance of Swagger generator with given marshaller (may be JSON marshaller or YAML marshaller or whatever)

func NewSwaggerGeneratorJSON

func NewSwaggerGeneratorJSON(seed spec.Swagger) IDocGenerator

NewSwaggerGeneratorJSON initializes new generator with initial swagger spec as a seed. The generator produces JSON output with no indentation

func NewSwaggerGeneratorJSONIndent

func NewSwaggerGeneratorJSONIndent(seed spec.Swagger) IDocGenerator

NewSwaggerGeneratorJSONIndent initializes new generator with initial swagger spec as a seed. The generator produces indented JSON output

func NewSwaggerGeneratorYAML

func NewSwaggerGeneratorYAML(seed spec.Swagger) IDocGenerator

NewSwaggerGeneratorYAML initializes new generator with initial swagger spec as a seed. The generator produces YAML output

type IHttpClient

type IHttpClient interface {
	Do(req *http.Request) (resp *http.Response, err error)
}

IHttpClient defines an interface of HTTP client that can fire HTTP requests and return responses.

type IHttpClientFunc

type IHttpClientFunc func(req *http.Request) (resp *http.Response, err error)

IHttpClientFunc implements IHttpClient in a functional way

func (IHttpClientFunc) Do

func (f IHttpClientFunc) Do(req *http.Request) (resp *http.Response, err error)

type INameable

type INameable interface {
	Name() string
}

INameable is an interface that defines that entity can provide its name. Used by test runner to define name of the test.

type ITaggable

type ITaggable interface {
	Tag() string
}

ITaggable is an interface that can tell doc generator that some test provides a tag. Usable for swagger documentation where tags help to group API endpoints

type ITestRunner

type ITestRunner interface {
	Run(tests []Test, t *testing.T)
}

ITestRunner is responsible for - receive a suite or suites - prepare some conditions to run suites (like setup frisby or whatsoever) - run tests of the suite

type MarshallerFunc

type MarshallerFunc func(obj interface{}) ([]byte, error)

type Param

type Param struct {
	Value       interface{}
	Required    bool
	Description string
}

Param defines a parameter that is used in headers or URL query of the API request

type ParamMap

type ParamMap map[string]Param

type RunnerConfig

type RunnerConfig struct {
	DefaultHeaders map[string]string
	HttpClient     IHttpClient
}

RunnerConfig contains list of possible options that can be used to initialize the Runner

type Setuppable

type Setuppable interface {
	SetUp() error
}

ISetuppable defines interface for tests that have setup logic

If you need to run some preparation logic - this is the right place to do

type Teardownable

type Teardownable interface {
	TearDown() error
}

ITeardownable defines interface for tests that have teardown logic

Good place to put some cleanup logic if you need to

type Test

type Test interface {
	Method() string
	Description() string
	Path() string
	TestCases() []TestCase
}

Test defines an interface of API test definition.

Responsibility of api test is to provide some meta data about API endpoint and collection of test cases that describe concrete usage of that endpoint.

type TestCase

type TestCase struct {
	Description string

	Headers     ParamMap
	QueryParams ParamMap
	PathParams  ParamMap
	RequestBody interface{}

	ExpectedHttpCode int
	ExpectedHeaders  map[string]string
	ExpectedData     interface{}

	// AssertResponse is a custom assertion logic that can be used
	// instead of ExpectedData. If provided, it is fully responsible
	// for processing of API response payload and assertion with
	// expected data.
	AssertResponse AssertResponseFunc
}

TestCase provides use case of some API endpoint: input and expected output.

Test case knows nothing about API endpoint itself. Path of an API endpoint and its description must be provided by Test.

Ideally each different error that API endpoint can return should be described by a test case.

func (*TestCase) Url

func (testCase *TestCase) Url(urlpath string) (string, error)

Url generates full URL to API endpoint for given test case. urlpath must provide full URL to the endpoint with no query parameters.