Snap.Test

The Snap.Test module contains primitives and combinators for testing Snap applications.

Combinators and types for testing Snap handlers.

Types

data RequestBuilder m a

RequestBuilder is a monad transformer that allows you to conveniently build a snap Request for testing.

Instances

MonadTrans RequestBuilder

Monad m => MonadState Request (RequestBuilder m)

Monad m => Monad (RequestBuilder m)

MonadIO m => MonadIO (RequestBuilder m)

type MultipartParams = [(ByteString, MultipartParam)]

A request body of type "multipart/form-data" consists of a set of named form parameters, each of which can by either a list of regular form values or a set of file uploads.

data MultipartParam

Constructors

FormData [ByteString]

a form variable consisting of the given ByteString values.

Files [FileData]

a file upload consisting of the given FileData values.

Instances

Show MultipartParam

data FileData

Constructors

FileData

Fields

fdFileName :: ByteString

the file's name

fdContentType :: ByteString

the file's content-type

fdContents :: ByteString

the file contents

Instances

Show FileData

data RequestType

The RequestType datatype enumerates the different kinds of HTTP requests you can generate using the testing interface. Most users will prefer to use the get, postUrlEncoded, postMultipart, put, and delete convenience functions.

Constructors

GetRequest

RequestWithRawBody Method ByteString

MultipartPostRequest MultipartParams

UrlEncodedPostRequest Params

DeleteRequest

Instances

Show RequestType

Building Requests and testing handlers

buildRequest :: MonadIO m => RequestBuilder m () -> m Request

Runs a RequestBuilder, producing the desired Request.

N.B. please don't use the request you get here in a real Snap application; things will probably break. Don't say you weren't warned :-)

runHandler

Arguments

:: MonadIO m

=> RequestBuilder m ()

a request builder

-> Snap a

a web handler

-> m Response

Given a web handler in the Snap monad, and a RequestBuilder defining a test request, runs the handler, producing an HTTP Response.

This function will produce almost exactly the same output as running the handler in a real server, except that chunked transfer encoding is not applied, and the "Transfer-Encoding" header is not set (this makes it easier to test response output).

runHandlerM

Arguments

:: (MonadIO m, MonadSnap n)

=> (forall a. Request -> n a -> m Response)

a function defining how the MonadSnap monad should be run

-> RequestBuilder m ()

a request builder

-> n b

a web handler

-> m Response

Given a web handler in some arbitrary MonadSnap monad, a function specifying how to evaluate it within the context of the test monad, and a RequestBuilder defining a test request, runs the handler, producing an HTTP Response.

evalHandler :: MonadIO m => RequestBuilder m () -> Snap a -> m a

Given a web handler in the Snap monad, and a RequestBuilder defining a test request, runs the handler and returns the monadic value it produces.

Throws an exception if the Snap handler early-terminates with finishWith or mzero.

evalHandlerM

Arguments

:: (MonadIO m, MonadSnap n)

=> (forall a. Request -> n a -> m a)

a function defining how the MonadSnap monad should be run

-> RequestBuilder m ()

a request builder

-> n b

a web handler

-> m b

Given a web handler in some arbitrary MonadSnap monad, a function specifying how to evaluate it within the context of the test monad, and a RequestBuilder defining a test request, runs the handler, returning the monadic value it produces.

Throws an exception if the Snap handler early-terminates with finishWith or mzero.

Convenience functions for generating common types of HTTP requests

get

Arguments

:: MonadIO m

=> ByteString

request path

-> Params

request's form parameters

-> RequestBuilder m ()

Builds an HTTP "GET" request with the given query parameters.

postUrlEncoded

Arguments

:: MonadIO m

=> ByteString

request path

-> Params

request's form parameters

-> RequestBuilder m ()

Builds an HTTP "POST" request with the given form parameters, using the "application/x-www-form-urlencoded" MIME type.

postMultipart

Arguments

:: MonadIO m

=> ByteString

request path

-> MultipartParams

multipart form parameters

-> RequestBuilder m ()

Builds an HTTP "POST" request with the given form parameters, using the "form-data/multipart" MIME type.

put

Arguments

:: MonadIO m

=> ByteString

request path

-> ByteString

request body MIME content-type

-> ByteString

request body contents

-> RequestBuilder m ()

Builds an HTTP "PUT" request.

postRaw

Arguments

:: MonadIO m

=> ByteString

request path

-> ByteString

request body MIME content-type

-> ByteString

request body contents

-> RequestBuilder m ()

Builds a "raw" HTTP "POST" request, with the given MIME type and body contents.

delete

Arguments

:: MonadIO m

=> ByteString

request path

-> Params

request's form parameters

-> RequestBuilder m ()

Builds an HTTP "DELETE" request with the given query parameters.

Precise control over building Requests

addHeader :: Monad m => CI ByteString -> ByteString -> RequestBuilder m ()

Adds the given header to the request being built.

setContentType :: Monad m => ByteString -> RequestBuilder m ()

Sets the request's content-type to the given MIME type.

setHeader :: Monad m => CI ByteString -> ByteString -> RequestBuilder m ()

Sets the given header in the request being built, overwriting any header with the same name already present.

setHttpVersion :: Monad m => (Int, Int) -> RequestBuilder m ()

Sets the test request's http version

setQueryString :: Monad m => Params -> RequestBuilder m ()

Escapes the given parameter mapping and sets it as the request's query string.

setQueryStringRaw :: Monad m => ByteString -> RequestBuilder m ()

Sets the request's query string to be the raw bytestring provided, without any escaping or other interpretation. Most users should instead choose the setQueryString function, which takes a parameter mapping.

setRequestPath :: Monad m => ByteString -> RequestBuilder m ()

Sets the request's path. The path provided must begin with a "/" and must not contain a query string; if you want to provide a query string in your test request, you must use setQueryString or setQueryStringRaw. Note that rqContextPath is never set by any RequestBuilder function.

setRequestType :: MonadIO m => RequestType -> RequestBuilder m ()

Sets the type of the Request being built.

setSecure :: Monad m => Bool -> RequestBuilder m ()

Controls whether the test request being generated appears to be an https request or not.

HUnit Assertions

assertSuccess :: Response -> Assertion

Given a Response, asserts that its HTTP status code is 200 (success).

assert404 :: Response -> Assertion

Given a Response, asserts that its HTTP status code is 404 (Not Found).

assertRedirectTo

Arguments

:: ByteString

The Response should redirect to this URI

-> Response

-> Assertion

Given a Response, asserts that its HTTP status code is between 300 and 399 (a redirect), and that the Location header of the Response points to the specified URI.

assertRedirect :: Response -> Assertion

Given a Response, asserts that its HTTP status code is between 300 and 399 (a redirect).

assertBodyContains

Arguments

:: ByteString

Regexp that will match the body content

-> Response

-> Assertion

Given a Response, asserts that its body matches the given regular expression.

Getting response bodies

getResponseBody :: Response -> IO ByteString

Dumping HTTP Responses

dumpResponse :: Response -> IO ()

Dumps the given response to stdout.

responseToString :: Response -> IO ByteString

Converts the given response to a bytestring.