Awaits a given async task within session.

example

Example

session
<~ foo
<~ bar

Is the same as:

session
|> await(:foo)
|> await(:bar)

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

Example

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

Is the same as:

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

@spec add_async_task(t(), atom(), Task.t()) :: t()

Adds a given Task to session under a given name.

@spec add_error(
  t(),
  Chaperon.Actionable.t(),
  {:error, Chaperon.Session.Error.t()}
) :: t()

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

@spec add_metric(t(), metric(), any()) :: t()

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

@spec add_result(t(), Chaperon.Actionable.t(), any()) :: t()

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

@spec add_ws_result(t(), Chaperon.Actionable.t(), any()) :: t()

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

@spec assign(t(), Keyword.t()) :: t()

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

example

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"}

@spec assign(t(), atom(), Keyword.t()) :: t()

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

example

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"}}

@spec async(t(), atom() | {atom(), atom()}, [any()], atom() | nil) :: t()

Runs a given function with args asynchronously from session.

@spec async_task(t(), atom()) :: Task.t() | [Task.t()]

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

@spec await(t(), atom()) :: t()

@spec await(t(), [atom()]) :: t()

Await an async task with a given task_name in session.

@spec await_all(t(), atom()) :: t()

Await all async tasks with a given task_name in session.

@spec await_signal(
  t(),
  any() | (t(), any() -> t())
) :: t()

Await any signal and call a given callback with the session and the received signal.

Example:

session
|> await_signal(fn(session, signal) ->
  session
  |> assign(signal: signal)
end)

@spec await_signal(t(), any(), non_neg_integer()) :: t()

Await an expected signal with a given timeout.

Example:

session
|> await_signal(:continue_search, 5 |> seconds)
|> get("/search", params: [query: "Got load test?"])

@spec await_signal_or_timeout(
  t(),
  non_neg_integer(),
  nil | (t(), any() -> t())
) :: 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

@spec call(t(), func(), [any()]) :: t()

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

@spec call_callback(t(), result_callback(), any()) :: t()

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.

@spec call_traced(t(), func(), [any()]) :: t()

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

@spec cc_spread(t(), atom(), cc_spread_options()) :: t()

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.

@spec config(t(), config_key()) :: any()

Get a (possibly nested) config value.

example

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) # does not exist
iex> rescue
iex>   _ in Chaperon.Session.RequiredConfigMissingError -> :failed
iex> end
:failed
iex> session |> config([:bar, :val1])
"V1"
iex> session |> config([:bar, :val2])
"V2"
iex> session |> config("bar.val1")
"V1"
iex> session |> config("bar.val2")
"V2"

@spec config(t(), config_key(), any()) :: any()

Get a (possibly nested) config value and return the given default value, if config value does not exist.

example

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 Chaperon.Session.RequiredConfigMissingError -> :failed
iex> end
:failed
iex> session |> config(:invalid, "default")
"default"
iex> session |> config([:bar, :val1])
"V1"
iex> session |> config([:bar, :val2])
"V2"
iex> session |> config("bar.val1")
"V1"
iex> session |> config("bar.val2")
"V2"

@spec delay(t(), Chaperon.Timing.duration()) :: t()

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("/")

@spec delete(t(), String.t(), Chaperon.Action.HTTP.options()) :: t()

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

@spec delete_cookies(t()) :: t()

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
[]

@spec error(t(), any()) :: {:error, Chaperon.Session.Error.t()}

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

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

@spec get(t(), String.t(), Chaperon.Action.HTTP.options()) :: t()

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

@spec loop(t(), atom(), Chaperon.Timing.duration()) :: t()

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

@spec merge(t(), t()) :: t()

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

Merges errors of two sessions.

@spec merge_metrics(t(), map()) :: t()

Merges metrics of two sessions.

@spec merge_results(t(), map()) :: t()

Merges results of two sessions.

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

@spec ok(t()) :: {:ok, t()}

Returns {:ok, reason}.

@spec patch(t(), String.t(), Chaperon.Action.HTTP.options()) :: t()

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

@spec post(t(), String.t(), Chaperon.Action.HTTP.options()) :: t()

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

@spec put(t(), String.t(), Chaperon.Action.HTTP.options()) :: t()

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

@spec random_delay(t(), Chaperon.Timing.duration()) :: t()

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

@spec remove_async_task(t(), atom(), Task.t()) :: t()

Removes a Task with a given task_name from session.

@spec repeat(t(), func(), non_neg_integer()) :: t()

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

example

Example

session
|> repeat(:foo, 2)

# same as:
session
|> foo
|> foo

@spec repeat(t(), func(), [any()], non_neg_integer()) :: t()

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

example

Example

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

# same as:
session
|> foo("bar", "baz") |> foo("bar", "baz")

@spec repeat_traced(t(), func(), non_neg_integer()) :: 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

Example

session
|> repeat_traced(:foo, 2)

# same as:
session
|> call_traced(:foo)
|> call_traced(:foo)

@spec repeat_traced(t(), func(), [any()], non_neg_integer()) :: t()

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

example

Example

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

# same as:
session
|> call_traced(:foo, ["bar", "baz"])
|> call_traced(:foo, ["bar", "baz"])

@spec retry_on_error(t(), func(), [any()], retry_options()) :: 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)

@spec run_action(t(), Chaperon.Actionable.t()) :: t()

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.

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

@spec run_scenario(t(), Chaperon.Action.RunScenario.scenario()) :: t()

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

@spec run_scenario(
  t(),
  Chaperon.Action.RunScenario.scenario(),
  map(),
  boolean()
) :: t()

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.

@spec schedule_scenario(
  t(),
  Chaperon.Action.RunScenario.scenario(),
  map(),
  boolean()
) :: t()

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.

@spec set_config(t(), Keyword.t(any())) :: t()

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

example

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"}

@spec set_config(t(), atom(), Keyword.t(any())) :: t()

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

example

Example

iex> alias Chaperon.Session; import Session
iex> session = %Session{config: %{foo: 1, bar: %{baz: "hello",  quux: 0}}}
iex> session.config
%{foo: 1, bar: %{baz: "hello", quux: 0}}
iex> session = session |> set_config(:bar, quux: 10)
iex> session.config.bar.quux
10
iex> session.config.bar
%{baz: "hello", quux: 10}
iex> session.config
%{foo: 1, bar: %{baz: "hello", quux: 10}}

@spec signal(t(), atom(), any()) :: 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

@spec signal_parent(t(), any()) :: 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

# ...

@spec store_response_cookies(t(), HTTPoison.Response.t()) :: t()

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

@spec time(t(), metric(), (t() -> t())) :: t()

Records a custom metric for the duration of calling a given function with the current Chaperon.Session.

Example:

# records a metric named :my_metric with the duration of calling
# the given function
session
|> time(:my_action, fn session ->
  # do stuff with session
  # and at the end return session from inside this function
end)

@spec time(t(), metric(), atom(), atom(), [any()]) :: t()

Records a custom metric for the duration of calling a given function with the current Chaperon.Session.

Example:

# records a metric named :my_metric with the duration of calling
# the given function in the module with the given args.
session
|> time(:my_action, MyModule, :my_func, [arg1, arg2])

# this would record the duration of calling:
# MyModule.my_func(session, arg1, arg2)

@spec timeout(t()) :: non_neg_integer()

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

example

Example

iex> session = %Chaperon.Session{config: %{timeout: 10}}
iex> session |> Chaperon.Session.timeout
10

@spec update_assign(t(), Keyword.t((any() -> any()))) :: t()

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

example

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"}

@spec update_assign(t(), atom(), Keyword.t((any() -> any()))) :: t()

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

example

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"}

@spec update_config(t(), Keyword.t((any() -> any()))) :: t()

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

example

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"}

@spec update_config(t(), atom(), Keyword.t((any() -> any()))) :: t()

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

example

Example

iex> alias Chaperon.Session; import Session
iex> session = %Session{config: %{foo: 1, bar: %{baz: "hello", quux: 0}}}
iex> session.config
%{foo: 1, bar: %{baz: "hello", quux: 0}}
iex> session = session |> update_config(:bar, quux: &(&1 + 2))
iex> session.config
%{foo: 1, bar: %{baz: "hello", quux: 2}}

@spec ws_await_recv(t(), any(), Keyword.t()) :: t()

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

@spec ws_close(t(), Keyword.t()) :: t()

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

@spec ws_connect(t(), String.t(), Keyword.t()) :: t()

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

@spec ws_recv(t(), Keyword.t()) :: t()

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

@spec ws_send(t(), any(), Keyword.t()) :: t()

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.

example

Example

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

Is the same as:

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