chaperon v0.1.0 Chaperon.Session View Source

Defines a Session struct and corresponding helper functions that are used within Chaperon.Scenario definitions. Most of Chaperon’s logic is centered around these sessions.

Link to this section Summary

Functions

Awaits a given async task within session

Wraps a function call with session as an arg in a call to Chaperon.Session.call_traced and captures function call duration metrics in session

Adds a given Task to session under a given name

Stores a Chaperon.Session.Error in session for a given action for later inspection

Stores a given metric val under a given name in session

Adds a given HTTP request result to session for the given action

Adds a given WebSocket action result to session for a given action

Assigns a given list of key-value pairs (as a Keyword list) in session for further usage later

Assigns a given list of key-value pairs (as a Keyword list) under a given namespace in session for further usage later

Runs a given function with args asynchronously from session

Returns a single task or a list of tasks associated with a given task_name in session

Await all async tasks for the given task_names in session

Await all async tasks with a given task_name in session

Await a given signal in the current session and returns session afterwards

Await an expected signal with a given timeout

Await any incoming signal for current session within given timeout. If callback is provided, it will be called with the session and the received signal value

Calls a function inside the session’s scenario module with the given name and args, returning the resulting session

Calls a callback with session and an additional argument

Calls a given function or a function with the given name and args, then captures duration metrics in session

Concurrently spreads a given action with a given rate over a given time interval within session

Concurrently spreads a given action with a given rate over a given time interval within session

Get a (possibly nested) config value

Delays further execution of session by a given duration. duration can also be {:random, integer_val} in which case random_delay is called with integer_val

Performs a HTTP DELETE request on session’s base_url and path. Takes an optional list of options to be passed to HTTPotion

Deletes all cookies from session’s cookie store

Returns a Chaperon.Session.Error for the given session and with a given reason

Performs a HTTP GET request on session’s base_url and path. Takes an optional list of options to be passed to HTTPotion

Loops a given action for a given duration, returning the resulting session at the end

Merges two session’s results & metrics and returns the resulting session

Merges errors of two sessions

Merges metrics of two sessions

Merges results of two sessions

Returns the sessions configured name or scenario’s module name

Returns {:ok, reason}

Performs a HTTP PATCH request on session’s base_url and path. Takes an optional list of options to be passed to HTTPotion

Performs a HTTP POST request on session’s base_url and path. Takes an optional list of options to be passed to HTTPotion

Performs a HTTP PUT request on session’s base_url and path. Takes an optional list of options to be passed to HTTPotion

Delays further execution of session by a random value up to the given duration

Removes a Task with a given task_name from session

Repeats calling a given function with session a given amount of times, returning the resulting session at the end

Repeats calling a given function with session and additional args a given amount of times, returning the resulting session at the end

Repeats calling a given function with session a given amount of times, returning the resulting session at the end. Also traces durations for all calls to the given function

Repeats calling a given function with session and additional args a given amount of times, returning the resulting session at the end

Call a given function (with arguments). If any exception is raised, retry the call a given amount of times (defaults to 1 retry). The retry can be delayed by a fixed or random duration (defaults to 1s)

Runs a given action within session and returns the resulting session

Runs a potentially configured callback for a given action in case of success. In case of failure, runs the configured error callback with an {:error, reason} tuple

Runs & captures metrics of running another Chaperon.Scenario from session using sessions config

Runs & captures metrics of running another Chaperon.Scenario from session with a given config

Runs & captures metrics of running another Chaperon.Scenario from session with a given config on a random node in the Chaperon cluster

Runs & captures metrics of running another Chaperon.Scenario from session with a given config

Returns session’s errors wrapped with session’s name

Returns session’s metrics wrapped with session’s name

Returns session’s results wrapped with session’s name

Updates a session’s config based on a given Keyword list of new values to be used for config in session

Send a signal to the current session’s async task with the given name

Sends a signal to the current session’s parent session (that spawned it via a call to Session.async)

Stores HTTP response cookies in session cookie store for further outgoing requests

Returns the session’s configured timeout or the default timeout, if none specified

Updates assignments based on a given Keyword list of functions to be used for updating assigned in session

Updates assignments based on a given Keyword list of functions to be used for updating assigned within namespace in session

Updates a session’s config based on a given Keyword list of functions to be used for updating config in session

Performs a WebSocket message receive on sessions WebSocket connection. Takes an optional list of options to be passed along to Socket.Web.recv/2

Closes the session’s websocket connection. Takes an optional list of options to be passed along to Socket.Web.close/2

Performs a WebSocket connection attempt on session’s base_url and path

Performs a WebSocket message receive on sessions WebSocket connection. Takes an optional list of options to be passed along to Socket.Web.recv/2

Performs a WebSocket message send on sessions WebSocket connection. Takes an optional list of options to be passed along to Socket.Web.send/3

Makes a given function call async for session

Link to this section Types

Link to this type retry_options() View Source
retry_options() :: [retries: non_neg_integer, delay: non_neg_integer, random_delay: non_neg_integer]
Link to this type t() View Source
t() :: %Chaperon.Session{assigned: map, async_tasks: map, config: map, cookies: [String.t], errors: map, id: String.t, metrics: map, name: String.t, parent_pid: pid | nil, results: map, scenario: Chaperon.Scenario.t}

Link to this section Functions

Link to this macro session <~ arg View Source (macro)

Awaits a given async task within session.

Example

session
<~ foo
<~ bar

Is the same as:

session
|> await(:foo)
|> await(:bar)
Link to this macro session >>> arg View Source (macro)

Wraps a function call with session as an arg in a call to Chaperon.Session.call_traced and captures function call duration metrics in session.

Example

session
>>> foo
>>> bar(1,2,3)

Is the same as:

session
|> call_traced(:foo)
|> call_traced(:bar, [1,2,3])
Link to this function add_async_task(session, name, task) View Source
add_async_task(Chaperon.Session.t, atom, Task.t) :: Chaperon.Session.t

Adds a given Task to session under a given name.

Stores a Chaperon.Session.Error in session for a given action for later inspection.

Link to this function add_metric(session, name, val) View Source
add_metric(Chaperon.Session.t, [any], any) :: Chaperon.Session.t

Stores a given metric val under a given name in session.

Adds a given HTTP request result to session for the given action.

Link to this function add_ws_result(session, action, result) View Source

Adds a given WebSocket action result to session for a given action.

Assigns a given list of key-value pairs (as a Keyword list) in session for further usage later.

Example

iex> alias Chaperon.Session; import Session
iex> session = %Session{} |> assign(foo: 1, bar: "hello")
iex> session.assigned.foo
1
iex> session.assigned.bar
"hello"
iex> session.assigned
%{foo: 1, bar: "hello"}
Link to this function assign(session, namespace, assignments) View Source

Assigns a given list of key-value pairs (as a Keyword list) under a given namespace in session for further usage later.

Example

iex> alias Chaperon.Session; import Session
iex> session = %Session{} |> assign(:api, auth_token: "auth123", login: "foo@bar.com")
iex> session.assigned.api
%{auth_token: "auth123", login: "foo@bar.com"}
iex> session.assigned.api.auth_token
"auth123"
iex> session.assigned.api.login
"foo@bar.com"
iex> session.assigned
%{api: %{auth_token: "auth123", login: "foo@bar.com"}}
Link to this function async(session, func_name, args \\ [], task_name \\ nil) View Source
async(Chaperon.Session.t, atom, [any], atom | nil) :: Chaperon.Session.t

Runs a given function with args asynchronously from session.

Link to this function async_task(session, task_name) View Source
async_task(Chaperon.Session.t, atom) :: Task.t | [Task.t]

Returns a single task or a list of tasks associated with a given task_name in session.

Await all async tasks for the given task_names in session.

Link to this function await_all(session, task_name) View Source

Await all async tasks with a given task_name in session.

Await a given signal in the current session and returns session afterwards.

Example:

session
|> await_signal(:continue_search)
|> get("/search", params: [query: "Got load test?"])
Link to this function await_signal(session, expected_signal, timeout) View Source
await_signal(Chaperon.Session.t, any, non_neg_integer) :: Chaperon.Session.t

Await an expected signal with a given timeout.

Example:

session
|> await_signal(:continue_search, 5 |> seconds)
|> get("/search", params: [query: "Got load test?"])
Link to this function await_signal_or_timeout(session, timeout, callback \\ nil) View Source
await_signal_or_timeout(Chaperon.Session.t, non_neg_integer, nil | (Chaperon.Session.t, any -> Chaperon.Session.t)) :: Chaperon.Session.t

Await any incoming signal for current session within given timeout. If callback is provided, it will be called with the session and the received signal value.

Example:

session
|> await_signal_or_timeout(5 |> seconds, fn(session, signal) ->
  session
  |> log_info("Got signal")
  |> assign(signal: signal)
end)

# or using an atom as the callback:

def run(session) do
  session
  |> await_signal_or_timeout(5 |> seconds, :got_signal)
end

def got_signal(session, signal) do
  session
  |> log_info("Got signal")
  |> assign(signal: signal)
end
Link to this function call(session, func, args \\ []) View Source
call(Chaperon.Session.t, atom, [any]) :: Chaperon.Session.t

Calls a function inside the session’s scenario module with the given name and args, returning the resulting session.

Link to this function call_callback(session, func_name, arg) View Source

Calls a callback with session and an additional argument.

If the given callback is nil, simply returns session. If the callback is a function, call it with session and the extra argument. If it’s an atom, call the function with that name in session’s currently running scenario module.

Calls a given function or a function with the given name and args, then captures duration metrics in session.

Link to this function cc_spread(session, func_name, opts \\ []) View Source

Concurrently spreads a given action with a given rate over a given time interval within session.

Link to this function cc_spread(session, func_name, rate, interval, task_name \\ nil) View Source

Concurrently spreads a given action with a given rate over a given time interval within session.

Link to this function config(session, key, default_val \\ :no_default_given) View Source

Get a (possibly nested) config value.

Example

iex> alias Chaperon.Session; import Session
iex> session = %Session{config: %{foo: 1, bar: %{val1: "V1", val2: "V2"}}}
iex> session.config
%{foo: 1, bar: %{val1: "V1", val2: "V2"}}
iex> session |> config(:foo)
1
iex> try do
iex>   session |> config(:invalid) # no default value given
iex> rescue
iex>   _ in RuntimeError -> :failed
iex> end
:failed
iex> session |> config(:invalid, "default")
"default"
iex> session |> config([:bar, :val1])
"V1"
iex> session |> config([:bar, :val2])
"V2"

Delays further execution of session by a given duration. duration can also be {:random, integer_val} in which case random_delay is called with integer_val.

Example:

session
|> delay(3 |> seconds)
|> get("/")

# or with random delay up to 3 seconds:
session
|> delay({:random, 3 |> seconds})
|> get("/")

Performs a HTTP DELETE request on session’s base_url and path. Takes an optional list of options to be passed to HTTPotion.

Link to this function delete_assign(session, key) View Source
Link to this function delete_assign(session, namespace, key) View Source

Deletes all cookies from session’s cookie store.

iex> session = %Chaperon.Session{cookies: ["cookie_val1", "cookie_val2"]}
iex> session = session |> Chaperon.Session.delete_cookies
iex> session.cookies
[]

Returns a Chaperon.Session.Error for the given session and with a given reason.

Performs a HTTP GET request on session’s base_url and path. Takes an optional list of options to be passed to HTTPotion.

Loops a given action for a given duration, returning the resulting session at the end.

Merges two session’s results & metrics and returns the resulting session.

Link to this function merge_errors(session, errors) View Source

Merges errors of two sessions.

Link to this function merge_metrics(session, metrics) View Source
merge_metrics(Chaperon.Session.t, map) :: Chaperon.Session.t

Merges metrics of two sessions.

Link to this function merge_results(session, results) View Source
merge_results(Chaperon.Session.t, map) :: Chaperon.Session.t

Merges results of two sessions.

Returns the sessions configured name or scenario’s module name.

Returns {:ok, reason}.

Performs a HTTP PATCH request on session’s base_url and path. Takes an optional list of options to be passed to HTTPotion.

Performs a HTTP POST request on session’s base_url and path. Takes an optional list of options to be passed to HTTPotion.

Performs a HTTP PUT request on session’s base_url and path. Takes an optional list of options to be passed to HTTPotion.

Delays further execution of session by a random value up to the given duration.

Link to this function remove_async_task(session, task_name, task) View Source
remove_async_task(Chaperon.Session.t, atom, Task.t) :: Chaperon.Session.t

Removes a Task with a given task_name from session.

Link to this function repeat(session, func, amount) View Source
repeat(Chaperon.Session.t, atom, non_neg_integer) :: Chaperon.Session.t

Repeats calling a given function with session a given amount of times, returning the resulting session at the end.

Example

session
|> repeat(:foo, 2)

# same as:
session
|> foo
|> foo
Link to this function repeat(session, func, args, amount) View Source
repeat(Chaperon.Session.t, atom, [any], non_neg_integer) :: Chaperon.Session.t

Repeats calling a given function with session and additional args a given amount of times, returning the resulting session at the end.

Example

session
|> repeat(:foo, ["bar", "baz"], 2)

# same as:
session
|> foo("bar", "baz") |> foo("bar", "baz")
Link to this function repeat_traced(session, func, amount) View Source
repeat_traced(Chaperon.Session.t, atom, non_neg_integer) :: Chaperon.Session.t

Repeats calling a given function with session a given amount of times, returning the resulting session at the end. Also traces durations for all calls to the given function.

Example

session
|> repeat_traced(:foo, 2)

# same as:
session
|> call_traced(:foo)
|> call_traced(:foo)
Link to this function repeat_traced(session, func, args, amount) View Source
repeat_traced(Chaperon.Session.t, atom, [any], non_neg_integer) :: Chaperon.Session.t

Repeats calling a given function with session and additional args a given amount of times, returning the resulting session at the end.

Example

session
|> repeat_traced(:foo, ["bar", "baz"], 2)

# same as:
session
|> call_traced(:foo, ["bar", "baz"])
|> call_traced(:foo, ["bar", "baz"])
Link to this function reset_action_metadata(session) View Source
Link to this function retry_on_error(session, func, args \\ [], opts \\ [retries: 1, random_delay: 1000]) View Source
retry_on_error(Chaperon.Session.t, atom, [any], retry_options) :: Chaperon.Session.t

Call a given function (with arguments). If any exception is raised, retry the call a given amount of times (defaults to 1 retry). The retry can be delayed by a fixed or random duration (defaults to 1s).

Example:

session
|> retry_on_error(:publish, ["post title"], retries: 10, delay: 0.5 |> seconds)
# call function without args
|> retry_on_error(:cleanup, [], retries: 10, delay: 0.5 |> seconds)

# retry once by default
session
|> retry_on_error(:publish, ["post title"], random_delay: 5 |> seconds)

# retry once with default delay of 1s
session
|> retry_on_error(:publish, ["post title"])

# retry function without args and default options
session
|> retry_on_error(:publish_default)

Runs a given action within session and returns the resulting session.

Link to this function run_callback(session, action, response) View Source

Runs a potentially configured callback for a given action in case of success. In case of failure, runs the configured error callback with an {:error, reason} tuple.

For more info have a look at Chaperon.Action.callback/1 and Chaperon.Action.error_callback/1.

Link to this function run_error_callback(session, action, response) View Source

Runs & captures metrics of running another Chaperon.Scenario from session using sessions config.

Link to this function run_scenario(session, scenario, config, merge_config \\ true) View Source

Runs & captures metrics of running another Chaperon.Scenario from session with a given config.

Link to this function schedule_scenario(session, scenario) View Source

Runs & captures metrics of running another Chaperon.Scenario from session with a given config on a random node in the Chaperon cluster.

Link to this function schedule_scenario(session, scenario, config, merge_config \\ true) View Source

Runs & captures metrics of running another Chaperon.Scenario from session with a given config.

Returns session’s errors wrapped with session’s name.

Link to this function session_metrics(session) View Source

Returns session’s metrics wrapped with session’s name.

Link to this function session_results(session) View Source

Returns session’s results wrapped with session’s name.

Link to this function set_config(session, assignments) View Source

Updates a session’s config based on a given Keyword list of new values to be used for config in session.

Example

iex> alias Chaperon.Session; import Session
iex> session = %Session{config: %{foo: 1, bar: "hello"}}
iex> session.config
%{foo: 1, bar: "hello"}
iex> session = session |> set_config(foo: 10, baz: "wat")
iex> session.config.foo
10
iex> session.config.bar
"hello"
iex> session.config.baz
"wat"
iex> session.config
%{foo: 10, bar: "hello", baz: "wat"}
Link to this function signal(session, name, signal) View Source
signal(Chaperon.Session.t, atom, any) :: Chaperon.Session.t

Send a signal to the current session’s async task with the given name.

Example:

# scenario run function
def run(session) do
  session
  |> async(:search_entries, ["chaperon", "load testing"])
  |> async(:do_other_stuff)
  |> signal(:search_entries, :continue_search)
end

def search_entries(session, tag1, tag2) do
  session
  |> get("/search", json: [tag: tag1])
  |> await_signal(:continue_search)
  |> get("/search", json: [tag: tag2])
end
Link to this function signal_parent(session, signal) View Source
signal_parent(Chaperon.Session.t, any) :: Chaperon.Session.t

Sends a signal to the current session’s parent session (that spawned it via a call to Session.async).

Example:

# scenario run function
def run(session) do
  stream_path = "/secret/live/stream.json"
  session
  |> async(:connect_to_stream, [stream_path])
  |> await_signal({:connected_to_stream, stream_path})
  # ...
end

def connect_to_stream(session, stream_path) do
  session
  |> ws_connect(stream_path)
  |> signal_parent({:connected_to_stream, stream_path})
  |> stream_data
end

# ...
Link to this function skip_query_params_in_metrics(session) View Source
skip_query_params_in_metrics(Chaperon.Session.t) :: Chaperon.Session.t

Stores HTTP response cookies in session cookie store for further outgoing requests.

Link to this function timeout(session) View Source
timeout(Chaperon.Session.t) :: non_neg_integer

Returns the session’s configured timeout or the default timeout, if none specified.

Example

iex> session = %Chaperon.Session{config: %{timeout: 10}}
iex> session |> Chaperon.Session.timeout
10
Link to this function update_assign(session, assignments) View Source
update_assign(Chaperon.Session.t, Keyword.t((any -> any))) :: Chaperon.Session.t

Updates assignments based on a given Keyword list of functions to be used for updating assigned in session.

Example

iex> alias Chaperon.Session; import Session
iex> session = %Session{} |> assign(foo: 1, bar: "hello")
iex> session.assigned
%{foo: 1, bar: "hello"}
iex> session = session |> update_assign(foo: &(&1 + 2))
iex> session.assigned.foo
3
iex> session.assigned.bar
"hello"
iex> session.assigned
%{foo: 3, bar: "hello"}
Link to this function update_assign(session, namespace, assignments) View Source
update_assign(Chaperon.Session.t, atom, Keyword.t((any -> any))) :: Chaperon.Session.t

Updates assignments based on a given Keyword list of functions to be used for updating assigned within namespace in session.

Example

iex> alias Chaperon.Session; import Session
iex> session = %Session{} |> assign(:api, auth_token: "auth123", login: "foo@bar.com")
iex> session.assigned.api
%{auth_token: "auth123", login: "foo@bar.com"}
iex> session = session |> update_assign(:api, login: &("test" <> &1))
iex> session.assigned.api.login
"testfoo@bar.com"
iex> session.assigned.api
%{auth_token: "auth123", login: "testfoo@bar.com"}
Link to this function update_config(session, assignments) View Source
update_config(Chaperon.Session.t, Keyword.t((any -> any))) :: Chaperon.Session.t

Updates a session’s config based on a given Keyword list of functions to be used for updating config in session.

Example

iex> alias Chaperon.Session; import Session
iex> session = %Session{config: %{foo: 1, bar: "hello"}}
iex> session.config
%{foo: 1, bar: "hello"}
iex> session = session |> update_config(foo: &(&1 + 2))
iex> session.config.foo
3
iex> session.config.bar
"hello"
iex> session.config
%{foo: 3, bar: "hello"}
Link to this function ws_await_recv(session, expected_message, options \\ []) View Source

Performs a WebSocket message receive on sessions WebSocket connection. Takes an optional list of options to be passed along to Socket.Web.recv/2.

Closes the session’s websocket connection. Takes an optional list of options to be passed along to Socket.Web.close/2.

Link to this function ws_connect(session, path, options \\ []) View Source

Performs a WebSocket connection attempt on session’s base_url and path.

Performs a WebSocket message receive on sessions WebSocket connection. Takes an optional list of options to be passed along to Socket.Web.recv/2.

Link to this function ws_send(session, msg, options \\ []) View Source

Performs a WebSocket message send on sessions WebSocket connection. Takes an optional list of options to be passed along to Socket.Web.send/3.

Link to this macro session ~> arg View Source (macro)

Makes a given function call async for session.

Example

session
~> foo
~> bar(1,2,3)

Is the same as:

session
|> async(:foo)
|> async(:bar, [1,2,3])