Awaits a given async task within session.

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

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

Is the same as:

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

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.

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

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

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.

Example:

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

Await an expected signal with a given timeout.

Example:

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

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

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.

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.

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.

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"

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

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"

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.

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.

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

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.

Example

session
|> repeat(:foo, 2)

# same as:
session
|> foo
|> foo

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

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)

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"])

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.

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.

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.

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

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

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

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

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

# ...

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

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)

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)

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

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

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

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

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

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

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.

Example

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

Is the same as:

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