Plug

v1.8.1

Plug v1.8.1 Plug.Test View Source

Conveniences for testing plugs.

This module can be used in your test cases, like this:

use ExUnit.Case, async: true
use Plug.Test

Using this module will:

  • import all the functions from this module
  • import all the functions from the Plug.Conn module

By default, Plug tests checks for invalid header keys, e.g. header keys which include uppercase letters, and raises a Plug.Conn.InvalidHeaderError when it finds one. To disable it, set :validate_header_keys_during_test to false on the app config.

config :plug, :validate_header_keys_during_test, true

Link to this section Summary

Functions

conn(method, path, params_or_body \\ nil)

Creates a test connection

delete_req_cookie(conn, key)

Deletes a request cookie

init_test_session(conn, session)

Initializes the session with the given contents

put_http_protocol(conn, http_protocol)

Puts the http protocol

put_peer_data(conn, peer_data)

Puts the peer data

put_req_cookie(conn, key, value)

Puts a request cookie

recycle_cookies(new_conn, old_conn)

Moves cookies from a connection into a new connection for subsequent requests

sent_informs(conn)

Return the informational requests that have been sent

sent_pushes(conn)

Return the assets that have been pushed

sent_resp(conn)

Returns the sent response

Link to this section Functions

Link to this function

conn(method, path, params_or_body \\ nil) View Source 
conn(String.Chars.t(), binary(), params()) :: Plug.Conn.t()

Creates a test connection.

The request method and path are required arguments. method may be any value that implements to_string/1 and it will properly converted and normalized (e.g., :get or "post").

The path is commonly the request path with optional query string but it may also be a complete URI. When a URI is given, the host and schema will be used as part of the request too.

The params_or_body field must be one of:

  • nil - meaning there is no body;
  • a binary - containing a request body. For such cases, :headers must be given as option with a content-type;
  • a map or list - containing the parameters which will automatically set the content-type to multipart. The map or list may contain other lists or maps and all entries will be normalized to string keys;

Examples 

conn(:get, "/foo?bar=10")
conn(:get, "/foo", %{bar: 10})
conn(:post, "/")
conn("patch", "/", "") |> put_req_header("content-type", "application/json")
Link to this function

delete_req_cookie(conn, key) View Source 
delete_req_cookie(Plug.Conn.t(), binary()) :: Plug.Conn.t()

Deletes a request cookie.

Link to this function

init_test_session(conn, session) View Source 
init_test_session(Plug.Conn.t(), %{required(String.t() | atom()) => any()}) ::
  Plug.Conn.t()

Initializes the session with the given contents.

If the session has already been initialized, the new contents will be merged with the previous ones.

Link to this function

put_http_protocol(conn, http_protocol) View Source

Puts the http protocol.

Link to this function

put_peer_data(conn, peer_data) View Source

Puts the peer data.

Link to this function

put_req_cookie(conn, key, value) View Source 
put_req_cookie(Plug.Conn.t(), binary(), binary()) :: Plug.Conn.t()

Puts a request cookie.

Link to this function

recycle_cookies(new_conn, old_conn) View Source 
recycle_cookies(Plug.Conn.t(), Plug.Conn.t()) :: Plug.Conn.t()

Moves cookies from a connection into a new connection for subsequent requests.

This function copies the cookie information in old_conn into new_conn, emulating multiple requests done by clients where cookies are always passed forward, and returns the new version of new_conn.

Link to this function

sent_informs(conn) View Source

Return the informational requests that have been sent.

This function depends on gathering the messages sent by the test adapter when informational messages, such as an early hint, are sent. Calling this function will clear the informational request messages from the inbox for the process. To assert on multiple informs, the result of the function should be stored in a variable.

Examples 

conn = conn(:get, "/foo", "bar=10")
informs = Plug.Test.sent_informs(conn)
assert {"/static/application.css", [{"accept", "text/css"}]} in informs
assert {"/static/application.js", [{"accept", "application/javascript"}]} in informs
Link to this function

sent_pushes(conn) View Source

Return the assets that have been pushed.

This function depends on gathering the messages sent by the test adapter when assets are pushed. Calling this function will clear the pushed message from the inbox for the process. To assert on multiple pushes, the result of the function should be stored in a variable.

Examples 

conn = conn(:get, "/foo?bar=10")
pushes = Plug.Test.sent_pushes(conn)
assert {"/static/application.css", [{"accept", "text/css"}]} in pushes
assert {"/static/application.js", [{"accept", "application/javascript"}]} in pushes
Link to this function

sent_resp(conn) View Source

Returns the sent response.

This function is useful when the code being invoked crashes and there is a need to verify a particular response was sent even with the crash. It returns a tuple with {status, headers, body}.