Corresponds to hspec's Spec.

Since 1.2.0

Same as yesodSpec, but instead of taking already built site it takes an action which produces site for each test.

Same as yesodSpecWithSiteGenerator, but also takes an argument to build the site and makes that argument available to the tests.

Since: 1.6.4

Same as yesodSpec, but instead of taking a site it takes an action which produces the Application for each test. This lets you use your middleware from makeApplication

A single test case, to be run with yit.

Since 1.2.0

The state used in a single test case defined using yit

Since 1.2.4

Internal data structure, corresponding to hspec's SpecTree.

Since 1.2.0

Start describing a Tests suite keeping cookies and a reference to the tested Application and ConnectionPool

Describe a single test that keeps cookies, and a reference to the last response.

Modifies the site (yedSite) of the test, and creates a new WAI app (yedApp) for it.

yesod-test allows sending requests to your application to test that it handles them correctly. In rare cases, you may wish to modify that application in the middle of a test. This may be useful if you wish to, for example, test your application under a certain configuration, then change that configuration to see if your app responds differently.

Examples

post SendEmailR
-- Assert email not created in database
testModifySite (\site -> pure (site { siteSettingsStoreEmail = True }, id))
post SendEmailR
-- Assert email created in database

testModifySite (\site -> do
  middleware <- makeLogware site
  pure (site { appRedisConnection = Nothing }, middleware)
)

Since: 1.6.8

Sets a cookie

Examples

import qualified Web.Cookie as Cookie
:set -XOverloadedStrings
testSetCookie Cookie.defaultSetCookie { Cookie.setCookieName = "name" }

Since: 1.6.6

Deletes the cookie of the given name

Examples

:set -XOverloadedStrings
testDeleteCookie "name"

Since: 1.6.6

Modify the current cookies with the given mapping function

Since: 1.6.6

Clears the current cookies

Since: 1.6.6

Perform a GET request to url.

Examples

get HomeR

get ("http://google.com" :: Text)

Perform a POST request to url.

Examples

post HomeR

Perform a POST request to url with the given body.

Examples

postBody HomeR "foobar"

import Data.Aeson
postBody HomeR (encode $ object ["age" .= (1 :: Integer)])

Perform a request using a given method to url.

Examples

performMethod "DELETE" HomeR

Since: 1.6.3

Follow a redirect, if the last response was a redirect. (We consider a request a redirect if the status is 301, 302, 303, 307 or 308, and the Location header is set.)

Examples

get HomeR
followRedirect

Parse the Location header of the last response.

Examples

post ResourcesR
(Right (ResourceR resourceId)) <- getLocation

Since: 1.5.4

The general interface for performing requests. request takes a RequestBuilder, constructs a request, and executes it.

The RequestBuilder allows you to build up attributes of the request, like the headers, parameters, and URL of the request.

Examples

request $ do
  addToken
  byLabel "First Name" "Felipe"
  setMethod "PUT"
  setUrl NameR

Adds the given header to the request; see Network.HTTP.Types.Header for creating Headers.

Examples

import Network.HTTP.Types.Header
request $ do
  addRequestHeader (hUserAgent, "Chrome/41.0.2228.0")

Adds a header for HTTP Basic Authentication to the request

Examples

request $ do
  addBasicAuthHeader "Aladdin" "OpenSesame"

Since: 1.6.7

Sets the HTTP method used by the request.

Examples

request $ do
  setMethod "POST"

import Network.HTTP.Types.Method
request $ do
  setMethod methodPut

Add a parameter with the given name and value to the request body. This function can be called multiple times to add multiple parameters, and be mixed with calls to addFile.

"Post parameter" is an informal description of what is submitted by making an HTTP POST with an HTML <form>. Like HTML <form>s, yesod-test will default to a Content-Type of application/x-www-form-urlencoded if no files are added, and switch to multipart/form-data if files are added.

Calling this function after using setRequestBody will raise an error.

Examples

{-# LANGUAGE OverloadedStrings #-}
post $ do
  addPostParam "key" "value"

Add a parameter with the given name and value to the query string.

Examples

{-# LANGUAGE OverloadedStrings #-}
request $ do
  addGetParam "key" "value" -- Adds ?key=value to the URL

Add a bare parameter with the given name and no value to the query string. The parameter is added without an = sign.

You can specify the entire query string literally by adding a single bare parameter and no other parameters.

Examples

{-# LANGUAGE OverloadedStrings #-}
request $ do
  addBareGetParam "key" -- Adds ?key to the URL

Since: 1.6.16

Add a file to be posted with the current request.

Adding a file will automatically change your request content-type to be multipart/form-data.

Examples

request $ do
  addFile "profile_picture" "static/img/picture.png" "img/png"

Simple way to set HTTP request body

Examples

request $ do
  setRequestBody "foobar"

import Data.Aeson
request $ do
  setRequestBody $ encode $ object ["age" .= (1 :: Integer)]

The RequestBuilder state monad constructs a URL encoded string of arguments to send with your requests. Some of the functions that run on it use the current response to analyze the forms that the server is expecting to receive.

State + IO

Since: 1.6.0

Sets the URL used by the request.

Examples

request $ do
  setUrl HomeR

request $ do
  setUrl ("http://google.com/" :: Text)

Click on a link defined by a CSS query

Examples

get "/foobar"
clickOn "a#idofthelink"

Since: 1.5.7

Finds the <label> with the given value, finds its corresponding <input>, then adds a parameter for that input to the request body.

Examples

<form method="POST">
  <label for="user">Username</label>
  <input id="user" name="f1" />
</form>

request $ do
  byLabel "Username" "Michael"

<form method="POST">
  <label>Username <input name="f1"> </label>
</form>

<form method="POST">
  <label for="nickname">Nickname</label>
  <input id="nickname" name="f1" />

  <label for="nickname2">Nickname2</label>
  <input id="nickname2" name="f2" />
</form>

request $ do
  byLabel "Nickname" "Snoyberger"

Finds the <label> with the given value, finds its corresponding <input>, then adds a parameter for that input to the request body.

Examples

<form method="POST">
  <label for="user">Username</label>
  <input id="user" name="f1" />
</form>

request $ do
  byLabel "Username" "Michael"

<form method="POST">
  <label>Username <input name="f1"> </label>
</form>

Since: 1.5.9

Contain version of byLabelExact

Note: Just like byLabel, this function throws an error if it finds multiple labels

Since: 1.6.2

Prefix version of byLabelExact

Note: Just like byLabel, this function throws an error if it finds multiple labels

Since: 1.6.2

Suffix version of byLabelExact

Note: Just like byLabel, this function throws an error if it finds multiple labels

Since: 1.6.2

Note: This function throws an error if it finds multiple labels or if the CSS selector fails to parse, doesn't match any fragment, or matches multiple fragments.

Since: 1.6.15

Finds the <label> with the given value, finds its corresponding <input>, then adds a file for that input to the request body.

Examples

<form method="POST">
  <label for="imageInput">Please submit an image</label>
  <input id="imageInput" type="file" name="f1" accept="image/*">
</form>

request $ do
  fileByLabel "Please submit an image" "static/img/picture.png" "img/png"

<form method="POST">
  <label>Please submit an image <input type="file" name="f1"> </label>
</form>

Finds the <label> with the given value, finds its corresponding <input>, then adds a file for that input to the request body.

Examples

<form method="POST">
  <label for="imageInput">Please submit an image</label>
  <input id="imageInput" type="file" name="f1" accept="image/*">
</form>

request $ do
  fileByLabel "Please submit an image" "static/img/picture.png" "img/png"

<form method="POST">
  <label>Please submit an image <input type="file" name="f1"> </label>
</form>

Since: 1.5.9

Contain version of fileByLabelExact

Note: Just like fileByLabel, this function throws an error if it finds multiple labels

Since: 1.6.2

Prefix version of fileByLabelExact

Note: Just like fileByLabel, this function throws an error if it finds multiple labels

Since: 1.6.2

Suffix version of fileByLabelExact

Note: Just like fileByLabel, this function throws an error if it finds multiple labels

Since: 1.6.2

For responses that display a single form, just lookup the only CSRF token available.

Examples

request $ do
  addToken

Lookups the hidden input named "_token" and adds its value to the params. Receives a CSS selector that should resolve to the form element containing the token.

Examples

request $ do
  addToken_ "#formID"

Calls addTokenFromCookieNamedToHeaderNamed with the defaultCsrfCookieName and defaultCsrfHeaderName.

Use this function if you're using the CSRF middleware from Yesod.Core and haven't customized the cookie or header name.

Examples

request $ do
  addTokenFromCookie

Looks up the CSRF token stored in the cookie with the given name and adds it to the request headers. An error is thrown if the cookie can't be found.

Use this function if you're using the CSRF middleware from Yesod.Core and have customized the cookie or header name.

See Yesod.Core.Handler for details on this approach to CSRF protection.

Examples

import Data.CaseInsensitive (CI)
request $ do
  addTokenFromCookieNamedToHeaderNamed "cookieName" (CI "headerName")

Asserts that the two given values are not equal.

In case they are equal, the error message includes the values.

Since: 1.5.6

Asserts that the two given values are equal.

Since: 1.5.2

Asserts that the two given values are equal.

In case they are not equal, the error message includes the two values.

Since: 1.5.2

Assert the given header key/value pair was returned.

Examples

{-# LANGUAGE OverloadedStrings #-}
get HomeR
assertHeader "key" "value"

import qualified Data.CaseInsensitive as CI
import qualified Data.ByteString.Char8 as BS8
getHomeR
assertHeader (CI.mk (BS8.pack "key")) (BS8.pack "value")

Assert the given header was not included in the response.

Examples

{-# LANGUAGE OverloadedStrings #-}
get HomeR
assertNoHeader "key"

import qualified Data.CaseInsensitive as CI
import qualified Data.ByteString.Char8 as BS8
getHomeR
assertNoHeader (CI.mk (BS8.pack "key"))

Assert the last response status is as expected. If the status code doesn't match, a portion of the body is also printed to aid in debugging.

Examples

get HomeR
statusIs 200

Assert the last response is exactly equal to the given text. This is useful for testing API responses.

Examples

get HomeR
bodyEquals "<html><body><h1>Hello, World</h1></body></html>"

Assert the last response has the given text. The check is performed using the response body in full text form.

Examples

get HomeR
bodyContains "<h1>Foo</h1>"

Assert the last response doesn't have the given text. The check is performed using the response body in full text form.

Examples

get HomeR
bodyNotContains "<h1>Foo</h1>

Since: 1.5.3

Queries the HTML using a CSS selector, and all matched elements must contain the given string.

Examples

{-# LANGUAGE OverloadedStrings #-}
get HomeR
htmlAllContain "p" "Hello" -- Every <p> tag contains the string "Hello"

import qualified Data.Text as T
get HomeR
htmlAllContain (T.pack "h1#mainTitle") "Sign Up Now!" -- All <h1> tags with the ID mainTitle contain the string "Sign Up Now!"

Queries the HTML using a CSS selector, and passes if any matched element contains the given string.

Examples

{-# LANGUAGE OverloadedStrings #-}
get HomeR
htmlAnyContain "p" "Hello" -- At least one <p> tag contains the string "Hello"

Queries the HTML using a CSS selector, and fails if any matched element contains the given string (in other words, it is the logical inverse of htmlAnyContain).

Examples

{-# LANGUAGE OverloadedStrings #-}
get HomeR
htmlNoneContain ".my-class" "Hello" -- No tags with the class "my-class" contain the string "Hello"

Performs a CSS query on the last response and asserts the matched elements are as many as expected.

Examples

{-# LANGUAGE OverloadedStrings #-}
get HomeR
htmlCount "p" 3 -- There are exactly 3 <p> tags in the response

Parses the response body from JSON into a Haskell value, throwing an error if parsing fails.

This function also checks that the Content-Type of the response is application/json.

Examples

get CommentR
(comment :: Comment) <- requireJSONResponse

post UserR
(json :: Value) <- requireJSONResponse

Since: 1.6.9

Get the foundation value used for the current test.

Since 1.2.0

Get the most recently provided response value, if available.

Since 1.2.0

Returns the Cookies from the most recent request. If a request hasn't been made, an error is raised.

Examples

request $ do
  cookies <- getRequestCookies
  liftIO $ putStrLn $ "Cookies are: " ++ show cookies

Outputs the last response body to stderr (So it doesn't get captured by HSpec). Useful for debugging.

Examples

get HomeR
printBody

Performs a CSS query and print the matches to stderr.

Examples

{-# LANGUAGE OverloadedStrings #-}
get HomeR
printMatches "h1" -- Prints all h1 tags

Query the last response using CSS selectors, returns a list of matched fragments

Use HXT to parse a value from an HTML tag. Check for usage examples in this module's source.

Performs a given action using the last response. Use this to create response-level assertions