ht

package
v3.2.0+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 22, 2016 License: BSD-3-Clause Imports: 52 Imported by: 0

Documentation

Overview

Package ht provides functions for easy testing of HTTP based protocols.

Testing is done by constructing a request, executing the request and performing various checks on the returned response. The type Test captures this idea. Each Test may contain an arbitrary list of Checks which perform the actual validation work. Tests can be grouped into Suites which may provide a common cookie jar for their tests and may execute setup and teardown actions.

All elements like Checks, Request, Tests and Suites are organized in a way to allow easy deserialisation from a text format. This allows to load and execute whole Suites at runtime.

Checks

A typical check validates a certain property of the received response. E.g. 

StatusCode{Expect: 302}
Body{Contains: "foobar"}
Body{Contains: "foobar", Count: 2}
Body{Contains: "illegal", Count: -1}

The last three examples show how zero values of optional fields are commonly used: The zero value of Count means "any number of occurrences". Forbidding the occurenc of "foobar" thus requires a negative Count.

The following checks are provided

  • Body checks text in the response body
  • ContentType checks Content-Type header
  • DeleteCookie checks for proper deletion of cookies
  • FinalURL checks final URL after a redirect chain
  • Header checks presence and values of received HTTP header
  • HTMLContains checks text content of CSS-selected elements
  • HTMLTag checks occurrence HTML elements chosen via CSS-selectors
  • Identity checks the SHA1 hash of the HTTP body
  • Image checks image format, size and content
  • JSON checks structure and content of a JSON body
  • Links checks accesability of hrefs and srcs in HTML
  • Logfile checks data written to a logfile
  • Redirect checks for redirections
  • ResponseTime checks lower and higher bounds on the response time
  • SetCookie checks properties of received cookies
  • StatusCode checks the received HTTP status code
  • UTF8Encoded checks that the HTTP body is UTF-8 encoded
  • W3CValidHTML checks if body parses as valid HTML5
  • XML checks elements of a XML body

Requests

Requests allow to specify a HTTP request in a declarative manner. A wide variety of request can be generated from a purly textual representation of the Request.

All the ugly stuff like parameter encoding, generation of multipart bodies, etc. are hidden from the user.

Parametrisations

Hardcoding e.g. the hostname in a test has obvious drawbacks. To overcome these the Request and Checks may be parametrised. This is done by a simple variable expansion in which occurrences of variables are replaced by their values. Variables may occur in all (exported) string fields of Checks and all suitable string fields of Request in the form: 

{{VARNAME}}

The variable substitution is performed during compilation of a Test which includes compilation of the embedded Checks.

The current time with an optional offset can be substituted by a special construct: 

{{NOW}}                       -->  Wed, 01 Oct 2014 12:22:36 CEST
{{NOW + 15s}}                 -->  Wed, 01 Oct 2014 12:22:51 CEST
{{NOW + 25m | "15:04"}}       -->  12:47
{{NOW + 3d | "2006-Jan-02"}}  -->  2014-Oct-04

Formating the time is done with the usual reference time of package time and defaults to RFC1123. Offset can be negative, the known units are "s" for seconds, "m" for minutes, "h" for hours and "d" for days.

Some random values can be include by the following syntax: 

{{RANDOM NUMBER 99}}          -->  22
{{RANDOM NUMBER 32-99}}       -->  45
{{RANDOM NUMBER 99 %04x}}     -->  002d
{{RANDOM TEXT 8}}             -->  que la victoire Accoure à tes mâles
{{RANDOM TEXT 2-5}}           -->  Accoure à tes
{{RANDOM TEXT de 5}}          -->  Denn die fromme Seele
{{RANDOM EMAIL}}              -->  Leon.Schneider@gmail.com
{{RANDOM EMAIL web.de}}       -->  Meier.Anna@web.de

Tests

A Test is basically just a Request combined with a list of Checks. Running a Test is executing the request and validating the response according to the Checks. Before a test can be run the variable substitution in the Request and the Checks have to happen, a real HTTP request has to be crafted and checks have to be set up. This is done by compiling the test, a step which may fail: a) if the Request is malformed (e.g. uses a malformed URL) or b) if the checks are malformed (e.g. uses a malformed regexp). Such Tests/Checks are labeled Bogus.

There are three ways in which a Tests may fail:

  1. The test setup is malformed, such tests are called Bogus.
  2. The request itself fails. This is called an Error
  3. Any of the checks fail. This is called a Failure

Suites of tests

Normaly tests are not run individually but grouped into suites. Such suite may share a common cookie jar (and a common logger) and may contain setup and teardown actions. Any action on a Suite normaly requires its setup tests to pass, afterwards the main tests are executed and finally the teardown tests are run (but no errors or failures are reported for teardown tests).

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrBadBody is returned from checks if the request body is
	// not available (e.g. due to a failed request).
	ErrBadBody = errors.New("skipped due to bad body")

	// ErrNotFound is returned by checks if some expected value was
	// not found.
	ErrNotFound = errors.New("not found")

	// ErrFoundForbidden is returned by checks if a forbidden value
	// is found.
	ErrFoundForbidden = errors.New("found forbidden")

	// ErrFailed is returned by a checks failing unspecificly.
	ErrFailed = errors.New("failed")
)
View Source 
var (
	// DefaultUserAgent is the user agent string to send in http requests
	// if no user agent header is specified explicitly.
	DefaultUserAgent = "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/36.0.1985.143 Safari/537.36"

	// DefaultAccept is the accept header to be sent if no accept header
	// is set explicitly in the test.
	DefaultAccept = "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8"

	// DefaultClientTimeout is the timeout used by the http clients.
	DefaultClientTimeout = 10 * time.Second
)
View Source 
var (
	ShortTestTmpl *template.Template
	TestTmpl      *template.Template
)
View Source 
var CheckRegistry = make(map[string]reflect.Type)

CheckRegistry keeps track of all known Checks.

View Source 
var DefaultCheckTemplate = `{{define "CHECK"}}{{printf "%-7s %-15s %s" .Status .Name .JSON}}` +
	`{{if eq .Status 3 5}}{{range .Error}}
                {{.Error}}{{end}}{{end}}{{end}}`
View Source 
var DefaultGeometry = "1280x720+0+0*100"

DefaultGeometry is the default screen size, viewport and zoom used in browser based test if no geometry is explicitely set. Its value represents a unscrolled (+0+=), desktop browser (1280x720) at 100% zoom.

View Source 
var DefaultTestTemplate = `` /* 924-byte string literal not displayed */
View Source 
var ExtractorRegistry = make(map[string]reflect.Type)

ExtractorRegistry keeps track of all known Extractors.

View Source 
var PhantomJSExecutable = "phantomjs"

PhantomJSExecutable is command to run PhantomJS. Use an absolute path if phantomjs is not on your PATH or you whish to use a special version.

View Source 
var Random *rand.Rand

Random is the source for all randmoness used in ht.

View Source 
var ShortTestTemplate = `` /* 662-byte string literal not displayed */
View Source 
var Transport = &http.Transport{
	Proxy: http.ProxyFromEnvironment,
	Dial: (&net.Dialer{
		Timeout:   30 * time.Second,
		KeepAlive: 30 * time.Second,
	}).Dial,
	TLSClientConfig: &tls.Config{
		InsecureSkipVerify: false,
	},
	TLSHandshakeTimeout: 10 * time.Second,
}

Transport is the http Transport used while making requests. It is exposed to allow different Timeouts or laxer TLS settings.

Functions

func BoldBox 

func BoldBox(title string, prefix string) string

BoldBox around title, indented by prefix. 

#################
##             ##
##    Title    ##
##             ##
#################

func Box 

func Box(title string, prefix string) string

Box around title, indented by prefix. 

+------------+
|    Title   |
+------------+

func NameOf 

func NameOf(inst interface{}) string

NameOf returns the name of the type of inst.

func RTHistogram 

func RTHistogram(title string, data map[string][]int, dodge bool, filename string) error

RTHistogram produces a png file containing a histogram of the int values in data. Several histograms can be plotted, the keys of data are the labels. If dodge is true the histogram bars are not stacked.

func RandomIntn 

func RandomIntn(n int) int

RandomIntn returns a random int in the rnage [0,n) read from Random. It is safe for concurrent use.

func RegisterCheck 

func RegisterCheck(check Check)

RegisterCheck registers the check. Once a check is registered it may be unmarshaled from its name and marshaled data.

func RegisterExtractor added in v0.4.0 

func RegisterExtractor(ex Extractor)

RegisterExtractor registers the extratcor type. Once an extractor is registered it may be unmarshaled from its name and marshaled data.

func Summary 

func Summary(s string) string

Summary pretty-prints s and trimms it if too long. What is considered "too long" depends on the media type which is automatically detected from s. Currently only JSON is pretty printed. Media types which do not have obvious texttual representation are summariesed as the media type.

func TextContent added in v0.7.0 

func TextContent(n *html.Node, raw bool) string

TextContent returns the full text content of n. With raw processing the unprocessed content is returned. If raw==false then whitespace is normalized.

func Underline 

func Underline(title string, c string, prefix string) string

Underline title with c, indented by prefix. 

Title
~~~~~

Types

type AnyOne added in v1.0.0 

type AnyOne struct {
	// Of is the list of checks to execute.
	Of CheckList
}

AnyOne checks that at least one Of the embedded checks passes. It is the short circuiting boolean OR of the underlying checks. Check execution stops once the first passing check is found. Example (in JSON5 notation) to check status code for '202 OR 404': 

{
    Check: "AnyOne", Of: [
        {Check: "StatusCode", Expect: 202},
        {Check: "StatusCode", Expect: 404},
    ]
}

func (AnyOne) Execute added in v1.0.0 

func (a AnyOne) Execute(t *Test) error

Execute implements Check's Execute method. It executes the underlying checks until the first passes. If all underlying checks fail the whole list of failures is returned.

func (AnyOne) Prepare added in v1.0.0 

func (a AnyOne) Prepare() error

Prepare implements Checks' Prepare method by forwarding to the underlying checks.

type Body 

type Body Condition

Body provides simple condition checks on the response body.

func (Body) Execute 

func (b Body) Execute(t *Test) error

Execute implements Check's Execute method.

func (*Body) Prepare 

func (b *Body) Prepare() error

Prepare implements Check's Prepare method.

type BodyExtractor added in v0.4.0 

type BodyExtractor struct {
	// Regexp is the regular expression to look for in the body.
	Regexp string

	// SubMatch selects which submatch (capturing group) of Regexp shall
	// be returned. A 0 value indicates the whole match.
	Submatch int `json:",omitempty"`
}

BodyExtractor extracts a value from the uninterpreted response body via a regular expression.

func (BodyExtractor) Extract added in v0.4.0 

func (e BodyExtractor) Extract(t *Test) (string, error)

Extract implements Extractor's Extract method.

type Browser 

type Browser struct {
	// Geometry of the screenshot in the form
	//     <width> x <height> [ + <left> + <top> [ * <zoom> ] ]
	// which generates a screenshot (width x height) pixels located
	// at (left,top) while simulating a browser viewport of
	// again (width x height) at a zoom level of zoom %.
	//
	// It defaults to DefaultGeometry if unset.
	Geometry string `json:",omitempty"`

	// WaitUntilVisible selects elements in the DOM by theri CSS selector
	// which must be visible before rendering the screenshot.
	WaitUntilVisible []string `json:",omitempty"`

	// WaitUntilInvisible selects elements in the DOM by theri CSS selector
	// which must be invisible before rendering the screenshot.
	WaitUntilInvisible []string `json:",omitempty"`

	// Script is JavaScript code to be evaluated after page loading but
	// before rendering the page. You can use it e.g. to hide elements
	// which are non-deterministic using code like:
	//    $("#keyvisual > div.slides").css("visibility", "hidden");
	Script string `json:",omitempty"`

	// Timeout is the maximum duration to wait for the headless browser
	// to prepare the page. Defaults to 5 seconds if unset.
	Timeout time.Duration
	// contains filtered or unexported fields
}

Browser collects information needed for the checks Screenshot, RenderedHTML and RenderingTime which use PhantomJS as a headless browser.

type CantCheck 

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

CantCheck is the error type returned by checks whose preconditions are not fulfilled, e.g. malformed HTML or XML.

func (CantCheck) Error 

func (m CantCheck) Error() string

type Check 

type Check interface {
	// Prepare is called to prepare the check, e.g. to compile
	// regular expressions or that like.
	Prepare() error

	// Execute executes the check.
	Execute(*Test) error
}

Check is a single check performed on a Response.

type CheckList 

type CheckList []Check

CheckList is a slice of checks with the sole purpose of attaching JSON (un)marshaling methods.

func (CheckList) MarshalJSON 

func (cl CheckList) MarshalJSON() ([]byte, error)

MarshalJSON produces a JSON arry of the checks in cl. Each check is serialized in the form 

{ "Check": "NameOfCheckAsRegistered",
    "Field1OfCheck": "Value1", "Field2": "Value2", ... }

func (*CheckList) Populate 

func (cl *CheckList) Populate(src interface{}) error

Populate implements populate.Populator.Populate.

type CheckResult 

type CheckResult struct {
	Name     string        // Name of the check as registered.
	JSON     string        // JSON serialization of check.
	Status   Status        // Outcome of check. All status but Error
	Duration time.Duration // How long the check took.
	Error    ErrorList     // For a Status of Bogus or Fail.
}

CheckResult captures the outcom of a single check inside a test.

type Collection 

type Collection struct {
	// Test contains the actual tests to execute.
	Tests []*Test

	// Populated during execution
	Status Status
	Error  error
}

Collection is a set of Test for easy bulk execution

func (*Collection) ExecuteConcurrent 

func (s *Collection) ExecuteConcurrent(maxConcurrent int, jar *cookiejar.Jar) error

ExecuteConcurrent executes tests concurrently. But at most maxConcurrent tests of s are executed concurrently.

type Condition 

type Condition struct {
	// Equals is the exact value to be expected.
	// No other tests are performed if Equals is non-zero as these
	// other tests would be redundant.
	Equals string `json:",omitempty"`

	// Prefix is the required prefix
	Prefix string `json:",omitempty"`

	// Suffix is the required suffix.
	Suffix string `json:",omitempty"`

	// Contains must be contained in the string.
	Contains string `json:",omitempty"`

	// Regexp is a regular expression to look for.
	Regexp string `json:",omitempty"`

	// Count determines how many occurrences of Contains or Regexp
	// are required for a match:
	//     0: Any positive number of matches is okay
	//   > 0: Exactly that many matches required
	//   < 0: No match allowed (invert the condition)
	Count int `json:",omitempty"`

	// Min and Max are the minimum and maximum length the string may
	// have. Two zero values disables this test.
	Min, Max int `json:",omitempty"`

	// GreaterThan and LessThan are lower and upper bound on the numerical
	// value of the string: The string is trimmed from spaces as well as
	// from single and double quotes before parsed as a float64. If the
	// string is not float value these conditions fail.
	// Nil disables these conditions.
	GreaterThan, LessThan *float64 `json:",omitempty"`
	// contains filtered or unexported fields
}

Condition is a conjunction of tests against a string. Note that Contains and Regexp conditions both use the same Count; most likely one would use either Contains or Regexp but not both.

func (*Condition) Compile 

func (c *Condition) Compile() (err error)

Compile pre-compiles the regular expression if part of c.

func (Condition) Fulfilled added in v1.0.0 

func (c Condition) Fulfilled(s string) error

Fulfilled returns whether s matches all requirements of c. A nil return value indicates that s matches the defined conditions. A non-nil return indicates missmatch.

func (Condition) FulfilledBytes added in v1.0.0 

func (c Condition) FulfilledBytes(b []byte) error

FulfilledBytes provides a optimized version for Fullfilled(string(byteSlice)). TODO: Make this a non-lie.

type ContentType added in v0.5.0 

type ContentType struct {
	// Is is the wanted content type. It may be abrevated, e.g.
	// "json" would match "application/json"
	Is string

	// Charset is an optional charset
	Charset string `json:",omitempty"`
}

ContentType checks the Content-Type header.

func (ContentType) Execute added in v0.5.0 

func (c ContentType) Execute(t *Test) error

Execute implements Check's Execute method.

func (ContentType) Prepare added in v0.5.0 

func (ContentType) Prepare() error

Prepare implements Check's Prepare method. 

type Cookie struct {
	Name  string
	Value string `json:",omitempty"`
}

Cookie is a HTTP cookie.

type CookieExtractor added in v1.0.0 

type CookieExtractor struct {
	Name string // Name is the name of the cookie.
}

CookieExtractor extracts the value of a cookie received in a Set-Cookie header. The value of the first cookie with the given name is extracted.

func (CookieExtractor) Extract added in v1.0.0 

func (e CookieExtractor) Extract(t *Test) (string, error)

Extract implements Extractor's Extract method.

type CustomJS 

type CustomJS struct {
	// Script is JavaScript code to be evaluated.
	//
	// The script may be read from disk with the following syntax:
	//     @file:/path/to/script
	Script string `json:",omitempty"`
	// contains filtered or unexported fields
}

CustomJS executes the provided JavaScript.

The current Test is present in the JavaScript VM via binding the name "Test" at top-level to the current Test being checked.

The Script's last value indicates success or failure:

  • Success: true, 0, ""
  • Failure: false, any number != 0, any string != ""

CustomJS can be useful to log an excerpt of response (or the request) via console.log.

The JavaScript code is interpreted by otto. See the documentation at https://godoc.org/github.com/robertkrimen/otto for details.

func (*CustomJS) Execute 

func (s *CustomJS) Execute(t *Test) error

Execute implements Check's Execute method.

func (*CustomJS) Prepare 

func (s *CustomJS) Prepare() error

Prepare implements Check's Prepare method.

type DeleteCookie added in v0.5.0 

type DeleteCookie struct {
	Name   string
	Path   string `json:",omitempty"`
	Domain string `json:",omitempty"`
}

DeleteCookie checks that the HTTP response properly deletes all cookies matching Name, Path and Domain. Path and Domain are optional in which case all cookies with the given Name are checked for deletion.

func (DeleteCookie) Execute added in v0.5.0 

func (c DeleteCookie) Execute(t *Test) error

Execute implements Check's Execute method.

func (*DeleteCookie) Prepare added in v0.5.0 

func (c *DeleteCookie) Prepare() error

Prepare implements Check's Prepare method.

type ErrorList added in v0.9.0 

type ErrorList []error

ErrorList is a collection of errors.

func (ErrorList) AsStrings added in v0.9.0 

func (el ErrorList) AsStrings() []string

AsStrings returns the error list as as string slice.

func (ErrorList) Error added in v0.9.0 

func (el ErrorList) Error() string

Error implements the Error method of error.

type Execution 

type Execution struct {
	// Tries is the maximum number of tries made for this test.
	// Both 0 and 1 mean: "Just one try. No redo."
	// Negative values indicate that the test should be skipped
	// altogether.
	Tries int `json:",omitempty"`

	// Wait time between retries.
	Wait time.Duration `json:",omitempty"`

	// Pre-, Inter- and PostSleep are the sleep durations made
	// before the request, between request and the checks and
	// after the checks.
	PreSleep, InterSleep, PostSleep time.Duration `json:",omitempty"`

	// Verbosity level in logging.
	Verbosity int `json:",omitempty"`
}

Execution contains parameters controlling the test execution.

func (Execution) Skip 

func (p Execution) Skip() bool

Skip return whether the test should be skipped.

type Extraction 

type Extraction struct {
	Value string
	Error error
}

Extraction captures the result of a variable extraction.

type Extractor 

type Extractor interface {
	Extract(t *Test) (string, error)
}

Extractor allows to extract information from an executed Test.

type ExtractorMap added in v0.4.0 

type ExtractorMap map[string]Extractor

ExtractorMap is a map of Extractors with the sole purpose of attaching JSON (un)marshaling methods.

func (ExtractorMap) MarshalJSON added in v0.4.0 

func (em ExtractorMap) MarshalJSON() ([]byte, error)

MarshalJSON produces a JSON array of the Extractors in em. Each Extractor is serialized in the form 

{ Extractor: "NameOfExtractorAsRegistered", Field1OfExtratcor: Value1, Field2: Value2, ... }

func (*ExtractorMap) Populate 

func (em *ExtractorMap) Populate(src interface{}) error

Populate implements populate.Populator.Populate.

type FinalURL added in v0.5.0 

type FinalURL Condition

FinalURL checks the last URL after following all redirects. This check is useful only for tests with Request.FollowRedirects=true

func (FinalURL) Execute added in v0.5.0 

func (f FinalURL) Execute(t *Test) error

Execute implements Check's Execute method.

func (*FinalURL) Prepare added in v0.5.0 

func (f *FinalURL) Prepare() error

Prepare implements Check's Prepare method.

type HTMLContains 

type HTMLContains struct {
	// Selector is the CSS selector of the HTML elements.
	Selector string

	// Text contains the expected plain text content of the HTML elements
	// selected through the given selector.
	Text []string `json:",omitempty"`

	// Raw turns of white space normalization and will check the unprocessed
	// text content.
	Raw bool `json:",omitempty"`

	// Complete makes sure that no excess HTML elements are found:
	// If true the len(Text) must be equal to the number of HTML elements
	// selected for the check to succeed.
	Complete bool `json:",omitempty"`

	// InOrder makes the check fail if the selected HTML elements have a
	// different order than given in Text.
	InOrder bool `json:",omitempty"`
	// contains filtered or unexported fields
}

HTMLContains checks the text content (and optionally the order) of HTML elements selected by a CSS rule.

The text content found in the HTML document is normalized by roughly the following procedure:

  1. Newlines are inserted around HTML block elements (i.e. any non-inline element)
  2. Newlines and tabs are replaced by spaces.
  3. Multiple spaces are replaced by one space.
  4. Leading and trailing spaces are trimmed of.

As an example consider the following HTML: 

<html><body>
  <ul class="fancy"><li>One</li><li>S<strong>econ</strong>d</li><li> Three </li></ul>
</body></html>

The normalized text selected by a Selector of "ul.fancy" would be 

"One Second Three"

func (*HTMLContains) Execute 

func (c *HTMLContains) Execute(t *Test) error

Execute implements Check's Execute method.

func (*HTMLContains) Prepare 

func (c *HTMLContains) Prepare() (err error)

Prepare implements Check's Prepare method.

type HTMLExtractor added in v0.4.0 

type HTMLExtractor struct {
	// Selector is the CSS selector of an element, e.g.
	//     head meta[name="_csrf"]   or
	//     form#login input[name="tok"]
	//     div.token span
	Selector string

	// Attribute is the name of the attribute from which the
	// value should be extracted.  The magic value "~text~" refers to the
	// normalized text content of the element and ~rawtext~ to the raw
	// text content.
	// E.g. in the examples above the following should be sensible:
	//     content
	//     value
	//     ~text~
	Attribute string
}

HTMLExtractor allows to extract data from an executed Test. It supports extracting HTML attribute values and HTML text node values. Examples for CSRF token in the HTML: 

<meta name="_csrf" content="18f0ca3f-a50a-437f-9bd1-15c0caa28413" />
<input type="hidden" name="_csrf" value="18f0ca3f-a50a-437f-9bd1-15c0caa28413"/>

func (HTMLExtractor) Extract added in v0.4.0 

func (e HTMLExtractor) Extract(t *Test) (string, error)

Extract implements Extractor's Extract method.

type HTMLTag added in v0.3.0 

type HTMLTag struct {
	// Selector is the CSS selector of the HTML elements.
	Selector string

	// Count determines the number of occurrences to check for:
	//     < 0: no occurrence
	//    == 0: one ore more occurrences
	//     > 0: exactly that many occurrences
	Count int `json:",omitempty"`
	// contains filtered or unexported fields
}

HTMLTag checks for the existens of HTML elements selected by CSS selectors.

func (*HTMLTag) Execute added in v0.3.0 

func (c *HTMLTag) Execute(t *Test) error

Execute implements Check's Execute method.

func (*HTMLTag) Prepare added in v0.3.0 

func (c *HTMLTag) Prepare() (err error)

Prepare implements Check's Prepare method. 

type Header struct {
	// Header is the HTTP header to check.
	Header string

	// Condition is applied to the first header value. A zero value checks
	// for the existence of the given Header only.
	Condition `json:",omitempty"`

	// Absent indicates that no header Header shall be part of the response.
	Absent bool `json:",omitempty"`
}

Header provides a textual test of single-valued HTTP headers.

func (Header) Execute 

func (h Header) Execute(t *Test) error

Execute implements Check's Execute method.

func (*Header) Prepare 

func (h *Header) Prepare() error

Prepare implements Check's Prepare method.

type Identity 

type Identity struct {
	// SHA1 is the expected hash as shown by sha1sum of the whole body.
	// E.g. 2ef7bde608ce5404e97d5f042f95f89f1c232871 for a "Hello World!"
	// body (no newline).
	SHA1 string
}

Identity checks the value of the response body by comparing its SHA1 hash to the expected SHA1 value.

func (Identity) Execute 

func (i Identity) Execute(t *Test) error

Execute implements Check's Execute method.

func (Identity) Prepare 

func (Identity) Prepare() error

Prepare implements Check's Prepare method.

type Image 

type Image struct {
	// Format is the format of the image as registered in package image.
	Format string `json:",omitempty"`

	// If > 0 check width or height of image.
	Width, Height int `json:",omitempty"`

	// Fingerprint is either the 16 hex digit long Block Mean Value hash or
	// the 24 hex digit long Color Histogram hash of the image.
	Fingerprint string `json:",omitempty"`

	// Threshold is the limit up to which the received image may differ
	// from the given BMV or ColorHist fingerprint.
	Threshold float64 `json:",omitempty"`
}

Image checks image format, size and fingerprint. As usual a zero value of a field skips the check of that property. Image fingerprinting is done via github.com/vdobler/ht/fingerprint. Only one of BMV or ColorHist should be used as there is just one threshold.

func (Image) Execute 

func (i Image) Execute(t *Test) error

Execute implements Check's Execute method.

func (Image) Prepare 

func (i Image) Prepare() error

Prepare implements Check's Prepare method.

type JSExtractor 

type JSExtractor struct {
	// Script is JavaScript code to be evaluated.
	//
	// The script may be read from disk with the following syntax:
	//     @file:/path/to/script
	Script string `json:",omitempty"`
}

JSExtractor extracts arbirtary stuff via custom JavaScript code.

The current Test is present in the JavaScript VM via binding the name "Test" at top-level to the current Test being checked.

The Script is evaluated and the final expression is the value extracted with the following excpetions:

  • undefined or null is treated as an error
  • Objects and Arrays are treated as errors. The error message is reported in the field 'errmsg' of the object or the index 0 of the array.
  • Strings, Numbers and Bools are treated as properly extracted values which are returned.
  • Other types result in undefined behaviour.

The JavaScript code is interpreted by otto. See the documentation at https://godoc.org/github.com/robertkrimen/otto for details.

func (JSExtractor) Extract 

func (e JSExtractor) Extract(t *Test) (string, error)

Extract implements Extractor's Extract method.

type JSON 

type JSON struct {
	// Element in the flattened JSON map to apply the Condition to.
	// E.g.  "foo.2" in "{foo: [4,5,6,7]}" would be 6.
	// An empty value result in just a check for 'wellformedness' of
	// the JSON.
	Element string

	// Condition to apply to the value selected by Element.
	// If Condition is the zero value then only the existence of
	// a JSON element selected by Element is checked.
	// Note that Condition is checked against the actual value in the
	// flattened JSON map which will contain the quotation marks for
	// string values.
	Condition

	// Embeded is a JSON check applied to the value selected by
	// Element. Useful when JSON contains embedded, quoted JSON as
	// a string and checking via Condition is not practical.
	// (It seems this nested JSON is common nowadays. I'm getting old.)
	Embedded *JSON `json:",omitempty"`

	// Sep is the separator in Element when checking the Condition.
	// A zero value is equivalent to "."
	Sep string `json:",omitempty"`
}

JSON allow to check a single string, number, boolean or null element in a JSON document against a Condition.

Elements of the JSON document are selected by an element selector. In the JSON document 

{ "foo": 5, "bar": [ 1, "qux", 3 ], "waz": true, "nil": null }

the follwing element selector are present and have the shown values: 

foo       5
bar.0     1
bar.1     "qux"
bar.2     3
waz       true
nil       null

func (*JSON) Execute 

func (c *JSON) Execute(t *Test) error

Execute implements Check's Execute method.

func (*JSON) Prepare 

func (c *JSON) Prepare() error

Prepare implements Check's Prepare method.

type JSONExpr added in v1.0.0 

type JSONExpr struct {
	// Expression is a boolean gojee expression which must evaluate
	// to true for the check to pass.
	Expression string `json:",omitempty"`
	// contains filtered or unexported fields
}

JSONExpr allows checking JSON documents via gojee expressions. See github.com/nytlabs/gojee (or the vendored version) for details.

Consider this JSON: 

{ "foo": 5, "bar": [ 1, 2, 3 ] }

The follwing expression have these truth values: 

.foo == 5                    true
$len(.bar) > 2               true as $len(.bar)==3
.bar[1] == 2                 true
(.foo == 9) || (.bar[0]<7)   true as .bar[0]==1
$max(.bar) == 3              true
$has(.bar, 7)                false as bar has no 7

func (*JSONExpr) Execute added in v1.0.0 

func (c *JSONExpr) Execute(t *Test) error

Execute implements Check's Execute method.

func (*JSONExpr) Prepare added in v1.0.0 

func (c *JSONExpr) Prepare() (err error)

Prepare implements Check's Prepare method.

type JSONExtractor added in v0.6.0 

type JSONExtractor struct {
	// Element in the flattened JSON map to extract.
	Element string `json:",omitempty"`

	// Sep is the separator in Path.
	// A zero value is equivalent to "."
	Sep string `json:",omitempty"`
}

JSONExtractor extracts a value from a JSON response body. It uses github.com/nytlabs/gojsonexplode to flatten the JSON file for easier access. Only the lowest level of elements may be accessed: In the JSON {"c":[1,2,3]} "c" is not available, but c.2 is and equals 3. JSON null values are extracted as the empty string i.e. null and "" are indistinguashable.

Note that JSONExtractor behaves differently than the JSON check: JSONExctractor strips quotes from strings if the string is not empty.

func (JSONExtractor) Extract added in v0.6.0 

func (e JSONExtractor) Extract(t *Test) (string, error)

Extract implements Extractor's Extract method.

type Latency added in v0.7.0 

type Latency struct {
	// N is the number if request to measure. It should be much larger
	// than Concurrent. Default is 50.
	N int `json:",omitempty"`

	// Concurrent is the number of concurrent requests in flight.
	// Defaults to 2.
	Concurrent int `json:",omitempty"`

	// Limits is a string of the following form:
	//    "50% ≤ 150ms; 80% ≤ 200ms; 95% ≤ 250ms; 0.9995 ≤ 0.9s"
	// The limits above would require the median of the response
	// times to be <= 150 ms and would allow only 1 request in 2000 to
	// exced 900ms.
	// Note that it must be the ≤ sign (U+2264), a plain < or a <=
	// is not recognized.
	Limits string `json:",omitempty"`

	// IndividualSessions tries to run the concurrent requests in
	// individual sessions: A new one for each of the Concurrent many
	// requests (not N many sessions).
	// This is done by using a fresh cookiejar so it won't work if the
	// request requires prior login.
	IndividualSessions bool `json:",omitempty"`

	// If SkipChecks is true no checks are performed i.e. only the
	// requests are executed.
	SkipChecks bool `json:",omitempty"`

	// DumpTo is the filename where the latencies are reported.
	// The special values "stdout" and "stderr" are recognized.
	DumpTo string `json:",omitempty"`
	// contains filtered or unexported fields
}

Latency provides checks against percentils of the response time latency.

func (*Latency) Execute added in v0.7.0 

func (L *Latency) Execute(t *Test) error

Execute implements Check's Execute method.

func (*Latency) Prepare added in v0.7.0 

func (L *Latency) Prepare() error

Prepare implements Check's Prepare method. 

type Links struct {
	// Which links to test; a space separated list of tag tag names:
	//     'a',   'link',  'img',  'script', 'video', 'audio', 'source'
	// E.g. use "a img" to check the href attribute of all a-tags and
	// the src attribute of all img-tags.
	Which string

	// Head triggers HEAD requests instead of GET requests.
	Head bool `json:",omitempty"`

	// Concurrency determines how many of the found links are checked
	// concurrently. A zero value indicates sequential checking.
	Concurrency int `json:",omitempty"`

	// Timeout is the client timeout if different from main test.
	Timeout time.Duration `json:",omitempty"`

	// OnlyLinks and IgnoredLinks can be used to select only a subset of
	// all links.
	OnlyLinks, IgnoredLinks []Condition `json:",omitempty"`

	// FailMixedContent will report a failure for any mixed content, i.e.
	// resources retrieved via http for a https HTML page.
	FailMixedContent bool

	// MaxTime is the maximum duration allowed to retrieve all the linked
	// resources. A zero value means unlimited time allowed.
	MaxTime time.Duration
	// contains filtered or unexported fields
}

Links checks links and references in HTML pages for availability.

It can reports mixed content as a failure by setting FailMixedContent. (See https://w3c.github.io/webappsec-mixed-content/). Links will upgrade any non-anchor links if the original reqesponse contains 

Content-Security-Policy: upgrade-insecure-requests

in the HTTP header.

func (*Links) Execute 

func (c *Links) Execute(t *Test) error

Execute implements Check's Execute method.

func (*Links) Prepare 

func (c *Links) Prepare() (err error)

Prepare implements Check's Prepare method.

type Logfile added in v0.3.0 

type Logfile struct {
	// Path is the file system path to the logfile.
	Path string

	// Condition the newly written stuff must fulfill.
	Condition `json:",omitempty"`

	// Disallow states what is forbidden in the written log.
	Disallow []string `json:",omitempty"`

	// Remote contains access data for a foreign (Unix) server which
	// is contacted via ssh.
	Remote struct {
		// Host is the hostname:port. A port of :22 is optional.
		Host string

		// User contains the name of the user used to make the
		// ssh connection to Host
		User string

		// Password and/or Keyfile used to authenticate
		Password string `json:",omitempty"`
		KeyFile  string `json:",omitempty"`
	} `json:",omitempty"`
	// contains filtered or unexported fields
}

Logfile provides checks on a file (i.e. it ignores the HTTP response).

During preparation the current size of the file identified by Path is determined. When the check executes it seeks to that position and examines anything written to the file since the preparation of the check.

Logfile on remote (Unix) machines may be accessed via ssh (experimental).

func (*Logfile) Execute added in v0.3.0 

func (f *Logfile) Execute(t *Test) error

Execute implements Check's Execute method.

func (*Logfile) Prepare added in v0.3.0 

func (f *Logfile) Prepare() error

Prepare implements Check's Prepare method.

type MalformedCheck 

type MalformedCheck struct {
	Err error
}

MalformedCheck is the error type returned by checks who are badly parametrized, e.g. who try to check against a malformed regular expression.

func (MalformedCheck) Error 

func (m MalformedCheck) Error() string

type NoServerError added in v0.8.0 

type NoServerError struct{}

NoServerError checks the HTTP status code for not being a 5xx server error and that the body could be read without errors or timeouts.

func (NoServerError) Execute added in v0.8.0 

func (NoServerError) Execute(t *Test) error

Execute implements Check's Execute method.

func (NoServerError) Prepare added in v0.8.0 

func (NoServerError) Prepare() error

Prepare implements Check's Prepare method.

type None added in v1.0.0 

type None struct {
	// Of is the list of checks to execute.
	Of CheckList
}

None checks that none Of the embedded checks passes. It is the NOT of the short circuiting boolean AND of the underlying checks. Check execution stops once the first passing check is found. It Example (in JSON5 notation) to check for non-occurrence of 'foo' in body: 

{
    Check: "None", Of: [
        {Check: "Body", Contains: "foo"},
    ]
}

func (None) Execute added in v1.0.0 

func (n None) Execute(t *Test) error

Execute implements Check's Execute method. It executes the underlying checks until the first passes. If all underlying checks fail the whole list of failures is returned.

func (None) Prepare added in v1.0.0 

func (n None) Prepare() error

Prepare implements Checks' Prepare method by forwarding to the underlying checks.

type PosError added in v0.9.0 

type PosError struct {
	Err  error  // Err is the actual error.
	Line int    // Line is the line number counting from 1.
	Col  int    // Col is the column or byte position, also counting from 1!
	File string // Filename is the optional filename.
}

PosError is an error with optinaly attached position information.

func (PosError) Error added in v0.9.0 

func (e PosError) Error() string

type Redirect added in v0.5.0 

type Redirect struct {
	// To is matched against the Location header. It may begin with,
	// end with or contain three dots "..." which indicate that To should
	// match the end, the start or both ends of the Location header
	// value. (Note that only one occurrence of "..." is supported."
	To string

	// If StatusCode is greater zero it is the required HTTP status code
	// expected in this response. If zero, the valid status codes are
	// 301 (Moved Permanently), 302 (Found), 303 (See Other) and
	// 307 (Temporary Redirect)
	StatusCode int `json:",omitempty"`
}

Redirect checks for a singe HTTP redirection.

Note that this check cannot be used on tests with 

Request.FollowRedirects = true

as Redirect checks only the final response which will not be a redirection if redirections are followed automatically.

func (Redirect) Execute added in v0.5.0 

func (r Redirect) Execute(t *Test) error

Execute implements Check's Execute method.

func (Redirect) Prepare added in v0.5.0 

func (r Redirect) Prepare() error

Prepare implements Check's Prepare method.

type RedirectChain added in v1.0.0 

type RedirectChain struct {
	// Via contains the necessary URLs accessed during a redirect chain.
	//
	// Any URL may start with, end with or contain three dots "..." which
	// indicate a suffix, prefix or suffix+prefix match like in the To
	// field of Redirect.
	Via []string
}

RedirectChain checks steps in a redirect chain. The check passes if all stations in Via have been accessed in order; the actual redirect chain may hit additional stations.

Note that this check can be used on tests with 

Request.FollowRedirects = true

func (RedirectChain) Execute added in v1.0.0 

func (r RedirectChain) Execute(t *Test) error

Execute implements Check's Execute method.

func (RedirectChain) Prepare added in v1.0.0 

func (r RedirectChain) Prepare() error

Prepare implements Check's Prepare method.

type RenderedHTML 

type RenderedHTML struct {
	Browser

	// Checks to perform on the renderd HTML.
	// Sensible checks are those operating on the response body.
	Checks CheckList

	// KeepAs is the file name to store the rendered HTML to.
	// Useful for debugging purpose.
	KeepAs string `json:",omitempty"`
}

RenderedHTML applies checks to the HTML after processing through the headless browser PhantomJS. This processing will load external resources and evaluate the JavaScript. The checks are run against this 'rendered' HTML code.

func (*RenderedHTML) Execute 

func (r *RenderedHTML) Execute(t *Test) error

Execute implements Check's Execute method.

func (*RenderedHTML) Prepare 

func (r *RenderedHTML) Prepare() error

Prepare implements Check's Prepare method.

type RenderingTime 

type RenderingTime struct {
	Browser

	Max time.Duration
}

RenderingTime limits the maximal allowed time to render a whole HTML page.

The "rendering time" is how long it takes PhantomJS to load all referenced assets and render the page. For obvious reason this cannot be determined with absolute accuracy.

func (*RenderingTime) Execute 

func (d *RenderingTime) Execute(t *Test) error

Execute implements Check's Execute method.

func (*RenderingTime) Prepare 

func (d *RenderingTime) Prepare() error

Prepare implements Check's Prepare method.

type Request 

type Request struct {
	// Method is the HTTP method to use.
	// A empty method is equivalent to "GET"
	Method string `json:",omitempty"`

	// URL ist the URL of the request.
	URL string

	// Params contains the parameters and their values to send in
	// the request.
	//
	// If the parameters are sent as multipart it is possible to include
	// files by special formated values.
	// The following formats are recognized:
	//    @file:/path/to/thefile
	//         read in /path/to/thefile and use its content as the
	//         parameter value. The path may be relative.
	//    @vfile:/path/to/thefile
	//         read in /path/to/thefile and perform variable substitution
	//         in its content to yield the parameter value.
	//    @file:@name-of-file:direct-data
	//    @vfile:@name-of-file:direct-data
	//         use direct-data as the parameter value and name-of-file
	//         as the filename. (There is no difference between the
	//         @file and @vfile variants; variable substitution has
	//         been performed already and is not done twice on direct-data.
	Params url.Values

	// ParamsAs determines how the parameters in the Param field are sent:
	//   "URL" or "": append properly encoded to URL
	//   "body"     : send as application/x-www-form-urlencoded in body.
	//   "multipart": send as multipart/form-data in body.
	// The two values "body" and "multipart" must not be used
	// on a GET or HEAD request.
	ParamsAs string `json:",omitempty"`

	// Header contains the specific http headers to be sent in this request.
	// User-Agent and Accept headers are set automaticaly to the global
	// default values if not set explicitly.
	Header http.Header `json:",omitempty"`

	// Cookies contains the cookies to send in the request.
	Cookies []Cookie `json:",omitempty"`

	// Body is the full body to send in the request. Body must be
	// empty if Params are sent as multipart or form-urlencoded.
	Body string `json:",omitempty"`

	// FollowRedirects determines if automatic following of
	// redirects should be done.
	FollowRedirects bool `json:",omitempty"`

	// BasicAuthUser and BasicAuthPass contain optional username and
	// password which will be sent in a Basic Authentication header.
	// If following redirects the authentication header is also sent
	// on subsequent requests to the same host.
	BasicAuthUser string `json:",omitempty"`
	BasicAuthPass string `json:",omitempty"`

	// Chunked turns of setting of the Content-Length header resulting
	// in chunked transfer encoding of POST bodies.
	Chunked bool `json:",omitempty"`

	// Timeout of this request. If zero use DefaultClientTimeout.
	Timeout time.Duration `json:",omitempty"`

	Request    *http.Request `json:"-"` // the 'real' request
	SentBody   string        `json:"-"` // the 'real' body
	SentParams url.Values    `json:"-"` // the 'real' parameters
}

Request is a HTTP request.

type Resilience added in v0.8.0 

type Resilience struct {
	// Methods is the space separated list of HTTP methods to check,
	// e.g. "GET POST HEAD". The empty value will test the original
	// method of the test only.
	Methods string `json:",omitempty"`

	// ModParam and ModHeader control which modifications of parameter values
	// and header values are checked.
	// It is a space separated string of the modifications explained above
	// e.g. "drop nonsense empty".
	// An empty value turns off resilience testing.
	ModParam, ModHeader string `json:",omitempty"`

	// ParamsAs controls how parameter values are transmitted, it
	// is a space separated list of all transmission types like in
	// the Request.ParamsAs field, e.g. "URL body multipart" to check
	// URL query parameters, x-www-form-urlencoded and multipart/formdata.
	// The empty value will just check the type used in the original
	// test.
	ParamsAs string `json:",omitempty"`

	// SaveFailuresTo is the filename to which all failed checks shall
	// be logged. The data is appended to the file.
	SaveFailuresTo string `json:",omitempty"`

	// Checks is the list of checks to perform on the received responses.
	// In most cases the -- correct -- behaviour of the server will differ
	// from the response to a valid, unscrambled request; typically by
	// returning one of the 4xx status codes.
	// If Checks is empty, only a simple NoServerError will be executed.
	Checks CheckList `json:",omitempty"`

	// Values contains a list of values to use as header and parameter values.
	// Note that header and parameter checking uses the same list of Values,
	// you might want to do two Resilience checks, one for the headers and one
	// for the parameters.
	// If values is empty, then only the builtin modifications selected by
	// Mod{Param,Header} are used.
	Values []string
}

Resilience checks the resilience of an URL against unexpected requests like different HTTP methods, changed or garbled parameters, different parameter transmission types and changed or garbled HTTP headers.

Parameters and Header values can undergo several different types of modifications

  • all: all the individual modifications below (excluding 'space' for HTTP headers)
  • drop: don't send at all
  • none: don't modify the individual parameters or header but don't send any parameters or headers
  • double: send same value two times
  • twice: send two different values (original and "extraValue")
  • change: change a single character (first, middle and last one)
  • delete: drop single character (first, middle and last one)
  • nonsense: the values "p,f1u;p5c:h*", "hubba%12bubba(!" and " "
  • space: the values " ", " ", "\t", "\n", "\r", "\v", "\u00A0", "\u2003", "\u200B", "\x00\x00", and "\t \v \r \n "
  • malicious: the values "\uFEFF\u200B\u2029", "ʇunpᴉpᴉɔuᴉ", "http://a/%%30%30" and "' OR 1=1 -- 1"
  • user use user defined values from Values
  • empty: ""
  • type: change the type (if obvious)
  • "1234" --> "wwww"
  • "3.1415" --> "wwwwww"
  • "i@you.me" --> "iXyouYme"
  • "foobar " --> "123"
  • large: produce much larger values
  • "1234" --> "9999999" (just large), "2147483648" (MaxInt32 + 1) "9223372036854775808" (MaxInt64 + 1) "18446744073709551616" (MaxUInt64 + 1)
  • "56.78" --> "888888888.9999", "123.456e12", "3.5e38" (larger than MaxFloat32) "1.9e308" (larger than MaxFloat64)
  • "foo" --> 50 * "X", 160 * "Y" and 270 * "Z"
  • tiny: produce 0 or short values
  • "1234" --> "0" and "1"
  • "12.3" --> "0", "0.02", "0.0003", "1e-12" and "4.7e-324"
  • "foobar" --> "f"
  • negative produce negative values
  • "1234" --> "-2"
  • "56.78" --> "-3.3"

This check will make a wast amount of request to the given URL including the modifying and non-idempotent methods POST, PUT, and DELETE. Some care using this check is advisable.

func (Resilience) Execute added in v0.8.0 

func (r Resilience) Execute(t *Test) error

Execute implements Check's Execute method.

func (Resilience) Prepare added in v0.8.0 

func (r Resilience) Prepare() error

Prepare implements Check's Prepare method.

type Response 

type Response struct {
	// Response is the received HTTP response. Its body has bean read and
	// closed already.
	Response *http.Response `json:",omitempty"`

	// Duration to receive response and read the whole body.
	Duration time.Duration `json:",omitempty"`

	// The received body and the error got while reading it.
	BodyStr string `json:",omitempty"`
	BodyErr error  `json:",omitempty"`

	// Redirections records the URLs of automatic GET requests due to redirects.
	Redirections []string `json:",omitempty"`
}

Response captures information about a http response.

func (*Response) Body 

func (resp *Response) Body() io.Reader

Body returns a reader of the response body.

type ResponseTime 

type ResponseTime struct {
	Lower  time.Duration `json:",omitempty"`
	Higher time.Duration `json:",omitempty"`
}

ResponseTime checks the response time.

func (ResponseTime) Execute 

func (c ResponseTime) Execute(t *Test) error

Execute implements Check's Execute method.

func (ResponseTime) Prepare 

func (ResponseTime) Prepare() error

Prepare implements Check's Prepare method.

type Screenshot 

type Screenshot struct {
	Browser

	// Expected is the file path of the 'golden record' image to test
	// the actual screenshot against.
	Expected string `json:",omitempty"`

	// Actual is the name of the file the actual rendered screenshot is
	// saved to.
	// An empty value disables storing the generated screenshot.
	Actual string `json:",omitempty"`

	// AllowedDifference is the total number of pixels which may
	// differ between the two screenshots while still passing this check.
	AllowedDifference int `json:",omitempty"`

	// IgnoreRegion is a list of regions which are ignored during
	// comparing the actual screenshot to the golden record.
	// The entries are specify rectangles in the form of the Geometry
	// (with ignored zoom factor).
	IgnoreRegion []string `json:",omitempty"`
	// contains filtered or unexported fields
}

Screenshot checks actual screenshots rendered via the headless browser PhantomJS against a golden record of the expected screenshot.

Note that PhantomJS will make additional request to fetch all linked resources in the HTML page. If the original request has BasicAuthUser (and BasicAuthPass) set this credentials will be sent to all linked resources of the page. Depending on where these resources are located this might be a security issue.

func (*Screenshot) Execute 

func (s *Screenshot) Execute(t *Test) error

Execute implements Check's Execute method.

func (*Screenshot) Prepare 

func (s *Screenshot) Prepare() error

Prepare implements Check's Prepare method.

type SetCookie 

type SetCookie struct {
	Name   string    `json:",omitempty"` // Name is the cookie name.
	Value  Condition `json:",omitempty"` // Value is applied to the cookie value
	Path   Condition `json:",omitempty"` // Path is applied to the path value
	Domain Condition `json:",omitempty"` // Domain is applied to the domain value

	// MinLifetime is the expectetd minimum lifetime of the cookie.
	// A positive value enforces a persistent cookie.
	// Negative values are illegal (use DelteCookie instead).
	MinLifetime time.Duration `json:",omitempty"`

	// Absent indicates that the cookie with the given Name must not be received.
	Absent bool `json:",omitempty"`

	// Type is the type of the cookie. It is a space separated string of
	// the following (case-insensitive) keywords:
	//   - "session": a session cookie
	//   - "persistent": a persistent cookie
	//   - "secure": a secure cookie, to be sont over https only
	//   - "unsafe", aka insecure; to be sent also over http
	//   - "httpOnly": not accesible from JavaScript
	//   - "exposed": accesible from JavaScript, Flash, etc.
	Type string `json:",omitempty"`
}

SetCookie checks for cookies being properly set. Note that the Path and Domain conditions are checked on the received Path and/or Domain and not on the interpreted values according to RFC 6265.

func (SetCookie) Execute 

func (c SetCookie) Execute(t *Test) error

Execute implements Check's Execute method.

func (*SetCookie) Prepare 

func (c *SetCookie) Prepare() error

Prepare implements Check's Prepare method.

type SetVariable 

type SetVariable struct {
	// To is the value to extract.
	To string
}

SetVariable allows to pragmatically "extract" a fixed value.

func (SetVariable) Extract 

func (e SetVariable) Extract(t *Test) (string, error)

Extract implements Extractor's Extract method.

type Sorted added in v0.7.0 

type Sorted struct {
	// Text is the list of text fragments to look for in the
	// response body or the normalized text content of the
	// HTML page.
	Text []string

	// AllowedMisses is the number of elements of Text which may
	// not be present in the response body. The default of 0 means
	// all elements of Text must be present.
	AllowedMisses int `json:",omitempty"`
}

Sorted checks for an ordered occurrence of items. The check Sorted could be replaced by a Regexp based Body test without loss of functionality; Sorted just makes the idea of "looking for a sorted occurrence" clearer.

If the response has a Content-Type header indicating a HTML response the HTML will be parsed and the text content normalized as described in the HTMLContains check.

func (*Sorted) Execute added in v0.7.0 

func (s *Sorted) Execute(t *Test) error

Execute implements Check's Execute method.

func (*Sorted) Prepare added in v0.7.0 

func (s *Sorted) Prepare() error

Prepare implements Check's Prepare method.

type Status 

type Status int

Status describes the status of a Test or a Check. 

const (
	NotRun  Status = iota // Not jet executed
	Skipped               // Omitted deliberately
	Pass                  // That's what we want
	Fail                  // One ore more checks failed
	Error                 // Request or body reading failed (not for checks).
	Bogus                 // Bogus test or check (malformd URL, bad regexp, etc.)
)

Possible status of Checks, Tests and Suites.

func (Status) MarshalText 

func (s Status) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (Status) String 

func (s Status) String() string

type StatusCode 

type StatusCode struct {
	// Expect is the value to expect, e.g. 302.
	//
	// If Expect <= 9 it matches a whole range of status codes, e.g.
	// with Expect==4 any of the 4xx status codes would fulfill this check.
	Expect int
}

StatusCode checks the HTTP statuscode.

func (StatusCode) Execute 

func (c StatusCode) Execute(t *Test) error

Execute implements Check's Execute method.

func (StatusCode) Prepare 

func (StatusCode) Prepare() error

Prepare implements Check's Prepare method.

type Test 

type Test struct {
	Name        string
	Description string `json:",omitempty"`

	// Request is the HTTP request.
	Request Request

	// Checks contains all checks to perform on the response to the HTTP request.
	Checks CheckList

	// Execution controls the test execution
	Execution Execution `json:",omitempty"`

	// Jar is the cookie jar to use
	Jar *cookiejar.Jar `json:"-"`

	// Variables contains name/value-pairs used for variable substitution
	// in files read in, e.g. for Request.Body = "@vfile:/path/to/file".
	Variables map[string]string `json:",omitempty"`

	// The following results are filled during Run.
	// This should be collected into something like struct TestResult{...}.
	Response     Response      `json:",omitempty"`
	Status       Status        `json:"-"`
	Started      time.Time     `json:"-"`
	Error        error         `json:"-"`
	Duration     time.Duration `json:"-"`
	FullDuration time.Duration `json:"-"`
	Tries        int           `json:"-"`
	CheckResults []CheckResult `json:"-"` // The individual checks.
	Reporting    struct {
		SeqNo     string
		Filename  string
		Extension string
	} `json:"-"`

	// VarEx may be used to popultate variables from the response. TODO: Rename.
	VarEx ExtractorMap // map[string]Extractor `json:",omitempty"`

	// ExValues contains the result of the extractions.
	ExValues map[string]Extraction `json:",omitempty"`

	// Log is the logger to use
	Log *log.Logger
	// contains filtered or unexported fields
}

Test is a single logical test which does one HTTP request and checks a number of Checks on the received Response.

func Merge 

func Merge(tests ...*Test) (*Test, error)

Merge merges all tests into one. The individual fields are merged in the following way. 

Name         Join all names
Description  Join all descriptions
Request
  Method     All nonempty must be the same
  URL        Only one may be nonempty
  Params     Merge by key
  ParamsAs   All nonempty must be the same
  Header     Merge by key
  Cookies    Merge by cookie name
  Body       Only one may be nonempty
  FollowRdr  Last wins
  Chunked    Last wins
Checks       Append all checks
VarEx        Merge, same keys must have same value
TestVars     Use values from first only.
Poll
  Max        Use largest
  Sleep      Use largest
Timeout      Use largets
Verbosity    Use largets
PreSleep     Summ of all;  same for InterSleep and PostSleep
ClientPool   ignore

func (*Test) AsJSON 

func (t *Test) AsJSON() ([]byte, error)

AsJSON returns a JSON representation of the test. Executed tests can be serialised and will contain basically all information required to debug or re-run the test but note that several fields in the actual *http.Request and *http.Response structs are cleared during this serialisation.

func (*Test) CurlCall 

func (t *Test) CurlCall() string

func (*Test) Disable 

func (t *Test) Disable()

Disable disables t by setting the maximum number of tries to -1.

func (*Test) Extract 

func (t *Test) Extract() map[string]string

Extract all values defined by VarEx from the successfully executed Test t.

func (*Test) PopulateCookies added in v0.8.0 

func (t *Test) PopulateCookies(jar *cookiejar.Jar, u *url.URL)

PopulateCookies populates t.Request.Cookies with the those cookies from jar which would be sent to u.

func (*Test) PrintReport 

func (t *Test) PrintReport(w io.Writer) error

PrintReport of t to w.

func (*Test) PrintShortReport 

func (t *Test) PrintShortReport(w io.Writer) error

PrintShortReport of t to w.

func (*Test) Run 

func (t *Test) Run() error

Run runs the test t. The actual HTTP request is crafted and executed and the checks are performed on the received response. This whole process is repeated on failure or skipped entirely according to t.Execution.

The given variables are subsituted into the relevant parts of the request and the checks.

Normally all checks in t.Checks are executed. If the first check in t.Checks is a StatusCode check against 200 and it fails, then the rest of the tests are skipped.

Run returns a non-nil error only if the test is bogus; a failing http request, problems reading the body or any failing checks do not trigger a non-nil return value.

type UTF8Encoded 

type UTF8Encoded struct{}

UTF8Encoded checks that the response body is valid UTF-8 without BOMs.

func (UTF8Encoded) Execute 

func (c UTF8Encoded) Execute(t *Test) error

Execute implements Check's Execute method.

func (UTF8Encoded) Prepare 

func (UTF8Encoded) Prepare() error

Prepare implements Check's Prepare method.

type ValidHTML 

type ValidHTML struct {
	// Ignore is a space separated list of issues to ignore.
	// You normaly won't skip detection of these issues as all issues
	// are fundamental flaws which are easy to fix.
	Ignore string `json:",omitempty"`
}

ValidHTML checks for valid HTML 5; well kinda: It make sure that some common but easy to detect fuckups are not present. The following issues are detected:

  • 'doctype': not exactly one DOCTYPE
  • 'structure': ill-formed tag nesting / tag closing
  • 'uniqueids': uniqness of id attribute values
  • 'lang': ill-formed lang attributes
  • 'attr': dupplicate attributes
  • 'escaping': unescaped &, < and > characters or unknown entities
  • 'label': reference to nonexisting id in label tags
  • 'url': malformed URLs

Notes:

  • HTML5 allows unescaped & in several circumstances but ValidHTML reports all stray & as an error.
  • The lang attributes are parse very lax, e.g. the non-canonical form 'de_CH' is considered valid (and equivalent to 'de-CH'). I don't know how browser handle this.

func (ValidHTML) Execute 

func (v ValidHTML) Execute(t *Test) error

Execute implements Check's Execute method.

func (ValidHTML) Prepare 

func (v ValidHTML) Prepare() error

Prepare implements Check's Prepare method.

type ValidationIssue 

type ValidationIssue struct {
	Position string
	Message  string
	Input    string
}

ValidationIssue contains extracted information from the output of a W3C validator run.

type W3CValidHTML 

type W3CValidHTML struct {
	// AllowedErrors is the number of allowed errors (after ignoring errors).
	AllowedErrors int `json:",omitempty"`

	// IgnoredErrros is a list of error messages to be ignored completely.
	IgnoredErrors []Condition `json:",omitempty"`
}

W3CValidHTML checks for valid HTML but checking the response body via the online checker from W3C which is very strict.

func (W3CValidHTML) Execute 

func (w W3CValidHTML) Execute(t *Test) error

Execute implements Check's Execute method.

func (W3CValidHTML) Prepare 

func (W3CValidHTML) Prepare() error

Prepare implements Check's Prepare method.

type WrongCount 

type WrongCount struct {
	Got, Want int
}

WrongCount is the error type returned by checks which require a certain number of matches.

func (WrongCount) Error 

func (m WrongCount) Error() string

type XML 

type XML struct {
	// Path is a XPath expression understood by gopkg.in/xmlpath.v2.
	Path string

	// Condition the first element addressed by Path must fulfill.
	Condition
	// contains filtered or unexported fields
}

XML allows to check XML request bodies.

func (*XML) Execute 

func (x *XML) Execute(t *Test) error

Execute implements Check's Execute method.

func (*XML) Prepare 

func (x *XML) Prepare() error

Prepare implements Check's Prepare method.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.