Phoenix API Toolkit v0.3.0 PhoenixApiToolkit.TestHelpers View Source

Various helper functions for writing tests.

Link to this section Summary

Types

Options for use by gen_jwt/1

Functions

Put request header "content-type: application/json" on the conn.

Remove volatile fields from maps in the data. Volatile fields like "id" mess up test comparisons. Recursively cleans maps and lists.

Returns the default JWT payload generated by gen_jwt/1. The "exp" claim is set to NOW + 5 minutes.

Generate a JSON Web Key for testing purposes. See gen_jwt/1 for details.

Generate a JSON Web Signature for testing purposes. See gen_jwt/1 for details.

Generate a JSON Web Token for testing purposes. It is possible to override parts of the signing key, payload and signature to test with different scopes, expiration times, issuers, key ID's etc, override the entire signing key, payload or signature. The defaults generate a valid JWT, so overrides are not necessary unless you wish to test the JWT verification itself. For use with endpoints secured with PhoenixApiToolkit.Security.Oauth2Plug.

Generate a JSON Web Token payload for testing purposes. See gen_jwt/1 for details.

Adds a HMAC-SHA256 signature to the connection's authorization header for the request body. Use create_hmac_plug_body/4 to generate a valid body. For use with endpoints secured with PhoenixApiToolkit.Security.HmacPlug.

Add JWT to the conn. By default a token that is valid in testing is added, generated by gen_jwt/1.

Put a whole map (or keyword list) of query params on a %Conn{}.

Put a raw request body in conn.assigns.raw_body for testing purposes.

Returns the secret used to sign request body's with HMACs by put_hmac/3.

Returns the jwks used to sign JWT's in tests by gen_jwt/1, as base64-encoded JSON.

Converts a map with atom or mixed keys to a map with only string keys.

Link to this section Types

Link to this type

gen_jwt_opts()

View Source
gen_jwt_opts() :: [jwk: map(), payload: map(), jws: map()]

Options for use by gen_jwt/1

Link to this section Functions

Link to this function

application_json(conn)

View Source
application_json(Plug.Conn.t()) :: Plug.Conn.t()

Put request header "content-type: application/json" on the conn.

Examples

use Plug.Test

iex> conn(:post, "/") |> application_json() |> get_req_header("content-type")
["application/json"]
Link to this function

clean_volatile_fields(data)

View Source
clean_volatile_fields(any()) :: any()

Remove volatile fields from maps in the data. Volatile fields like "id" mess up test comparisons. Recursively cleans maps and lists.

Examples

iex> my_data = [
...>   %{
...>     "updated_at" => 12345
...>   },
...>   %{
...>     "some_thing" => [
...>       %{
...>         "id" => 1
...>       },
...>       12345
...>     ]
...>   }
...> ]
iex> clean_volatile_fields(my_data)
[%{}, %{"some_thing" => [%{}, 12345]}]
Link to this function

create_hmac_plug_body(path, method, contents \\ %{}, timestamp \\ DateTime.utc_now() |> DateTime.to_unix(:second))

View Source
create_hmac_plug_body(binary(), binary(), any(), integer()) :: binary()

Generate a request body for an endpoint secured with PhoenixApiToolkit.Security.HmacPlug. Use put_hmac/3 to generate a valid signature.

It is possible to override the timestamp set in the request body. The default generates a valid request body, so overrides are not necessary unless you wish to test the HMAC verification itself.

Examples

iex> create_hmac_plug_body("/hello", "GET", %{hello: "world"}, 12345) |> Jason.decode!()
%{
  "contents" => %{"hello" => "world"},
  "method" => "GET",
  "path" => "/hello",
  "timestamp" => 12345
}
Link to this function

default_payload()

View Source
default_payload() :: %{
  exp: integer(),
  iss: binary(),
  scope: binary(),
  username: binary(),
  aud: binary()
}

Returns the default JWT payload generated by gen_jwt/1. The "exp" claim is set to NOW + 5 minutes.

Examples

iex> default_payload() |> Map.drop([:exp])
%{
  iss: "https://some_oauth2_provider/my_account_id",
  scope: "admin",
  username: "integration-test-user",
  aud: "my resource server"
}
Link to this function

gen_jwk(overrides \\ %{})

View Source
gen_jwk(map()) :: map()

Generate a JSON Web Key for testing purposes. See gen_jwt/1 for details.

Link to this function

gen_jws(overrides \\ %{})

View Source
gen_jws(map()) :: map()

Generate a JSON Web Signature for testing purposes. See gen_jwt/1 for details.

Link to this function

gen_jwt(overrides \\ [])

View Source
gen_jwt(gen_jwt_opts()) :: binary()

Generate a JSON Web Token for testing purposes. It is possible to override parts of the signing key, payload and signature to test with different scopes, expiration times, issuers, key ID's etc, override the entire signing key, payload or signature. The defaults generate a valid JWT, so overrides are not necessary unless you wish to test the JWT verification itself. For use with endpoints secured with PhoenixApiToolkit.Security.Oauth2Plug.

Examples

# by default, a valid JWT is generated using defaults for jwk, payload and jws
# the header, payload and signature can be inspected using JOSE.JWS.peek* functions
iex> jwt = gen_jwt()
iex> jwt |> JOSE.JWS.peek_protected() |> Jason.decode!()
%{"alg" => "RS256", "kid" => "my_test_key", "typ" => "JWT"}
iex> expected_pl = default_payload() |> Map.drop([:exp]) |> to_string_map()
iex> expected_pl == jwt |> JOSE.JWS.peek_payload() |> Jason.decode!() |> Map.drop(["exp"])
true

# the jwk, payload and jws can be overriden for testing purposes
iex> gen_jwt(payload: %{}) |> JOSE.JWS.peek_payload() |> Jason.decode!()
%{}

# this is most useful when combined with gen_jwk/gen_payload/gen_jws functions
# to override parts of the jwk/payload/jws
iex> gen_jwt(jws: gen_jws(%{"kid" => "other key"})) |> JOSE.JWS.peek_protected() |> Jason.decode!()
%{"alg" => "RS256", "kid" => "other key", "typ" => "JWT"}
iex> gen_jwt(payload: gen_payload(%{exp: 12345})) |> JOSE.JWS.peek_payload() |> Jason.decode!() |> Map.get("exp")
12345
Link to this function

gen_payload(overrides \\ %{})

View Source
gen_payload(map()) :: map()

Generate a JSON Web Token payload for testing purposes. See gen_jwt/1 for details.

Link to this function

put_hmac(conn, body, secret \\ test_hmac_secret())

View Source
put_hmac(Plug.Conn.t(), binary(), binary()) :: Plug.Conn.t()

Adds a HMAC-SHA256 signature to the connection's authorization header for the request body. Use create_hmac_plug_body/4 to generate a valid body. For use with endpoints secured with PhoenixApiToolkit.Security.HmacPlug.

It is possible to override the HMAC secret. The default generates a valid signature, so overrides are not necessary unless you wish to test the HMAC verification itself.

Examples

use Plug.Test

iex> body = %{greeting: "world"} |> Jason.encode!()
iex> conn = conn(:post, "/hello", body)
iex> put_hmac(conn, body) |> get_req_header("authorization")
["oseq9TrQc/cyOBU7ujrkKM07tFewcVoaLRK0MgslSos="]
Link to this function

put_jwt(conn, jwt \\ gen_jwt())

View Source
put_jwt(Plug.Conn.t(), binary()) :: Plug.Conn.t()

Add JWT to the conn. By default a token that is valid in testing is added, generated by gen_jwt/1.

Examples

use Plug.Test

iex> conn(:get, "/") |> put_jwt("my_jwt") |> get_req_header("authorization")
["Bearer: my_jwt"]
Link to this function

put_query_params(conn, params)

View Source
put_query_params(Plug.Conn.t(), map() | keyword()) :: Plug.Conn.t()

Put a whole map (or keyword list) of query params on a %Conn{}.

Examples

use Plug.Test

iex> conn(:get, "/") |> put_query_params(user: "Peter") |> Map.get(:query_params)
%{user: "Peter"}
Link to this function

put_raw_body(conn, raw_body)

View Source
put_raw_body(Plug.Conn.t(), binary()) :: Plug.Conn.t()

Put a raw request body in conn.assigns.raw_body for testing purposes.

Examples

use Plug.Test

iex> body = %{hello: "world"}
iex> raw_body = body |> Jason.encode!()
iex> conn = conn(:post, "/") |> put_raw_body(raw_body)
iex> conn.adapter |> elem(1) |> Map.get(:req_body) |> Jason.decode!()
%{"hello" => "world"}
Link to this function

test_hmac_secret()

View Source
test_hmac_secret() :: binary()

Returns the secret used to sign request body's with HMACs by put_hmac/3.

Link to this function

test_jwks()

View Source
test_jwks() :: binary()

Returns the jwks used to sign JWT's in tests by gen_jwt/1, as base64-encoded JSON.

Examples

# the keyset is returned as base64-encoded JSON string with a list of keys
iex> test_jwks() |> Base.decode64!() |> Jason.decode!() |> List.first() |> Map.get("kid")
"my_test_key"
Link to this function

to_string_map(map)

View Source
to_string_map(map()) :: map()

Converts a map with atom or mixed keys to a map with only string keys.

Examples

iex> %{:first_name => "Peter", "last_name" => "Pan"} |> to_string_map()
%{"first_name" => "Peter", "last_name" => "Pan"}