new/1 creates a new instance of the module’s struct and, if the optional opts were given, calls update/2 with the instance and the opts, returning {:ok, instance}, else {:error, error}.

new!/1 calls new/1 and, if the result is {:ok, instance} returns the instance.

test/1 takes a prova and runs each test call (cridar)

Examples

A simple example of a Map.get/2 call where the result is expected to be 42:

iex> {:ok, {answer, %PROVA{}}} = [
...>    module: Map, value: %{a: 42},
...>    args: [:a], call: [:get], result: 42,
...> ] |> PROVA.new! |> PROVA.test
...> answer
42

The :test_result here is 99 so an error is returned:

iex> {:error, error} = [
...>    module: Map, value: %{a: 42},
...>    args: [:a], call: [:get], result: 99,
...> ] |> PROVA.new! |> PROVA.test
...> error |> Exception.message
"result mismatch; expect 99; actual 42"

Here the :test_result is a fun/1 that always returns false causing an error to be returned.

iex> {:error, error} = [
...>    module: Map, value: %{a: 42},
...>    args: [:a], call: [:get], result: fn _ -> false end,
...> ] |> PROVA.new! |> PROVA.test
...> error |> Exception.message
"result invalid, got: 42"

Precreated cridars can be used in the :test_call:

iex> {:ok, %CRIDAR{} = cridar} = [
...>    mod: Map, fun: :get, args: [%{a: 42}, :a]
...> ] |> CRIDAR.new
...> {:ok, {answer, %PROVA{}}} = [
...>    module: List, value: %{b: 99},
...>    args: [:a], call: cridar, result: 42,
...> ] |> PROVA.new! |> PROVA.test
...> answer
42

In this example two precreated cridars are chained together: the result of the first is used as the :test_value for the second. Note the cridars have :rest_args (not :args) as they will be applied together with the :test_value:

iex> call1 = [f: :delete, rest_args: :a] |> CRIDAR.new!
...> call2 = [f: :get, rest_args: [:a, :no_a_found]] |> CRIDAR.new!
...> {:ok, {answer, %PROVA{}}} = [
...>    mod: Map, call: [call1, call2],
...>    value: %{a: 1}, result: :no_a_found,
...> ] |> PROVA.new! |> PROVA.test
...> answer
:no_a_found

Test call specifications can be mixed: A variation of the example above where a value is put for :a using an explicit fun:

iex> call1 = [f: :delete, rest_args: :a] |> CRIDAR.new!
...> call2 = [f: :get, rest_args: [:a, :no_a_found]] |> CRIDAR.new!
...> call3 = fn test_value -> Map.put(test_value, :a, 42) end
...> {:ok, {answer, %PROVA{}}} = [
...>    mod: Map, call: [call1, call3, call2],
...>    value: %{a: 1}, result: 42,
...> ] |> PROVA.new! |> PROVA.test
...> answer
42

Same example but the put for :a is Keyword format call specification:

iex> call1 = [f: :delete, rest_args: :a] |> CRIDAR.new!
...> call2 = [f: :get, rest_args: [:a, :no_a_found]] |> CRIDAR.new!
...> call3 = [f: :put, rest_args: [:a, 99]]
...> {:ok, {answer, %PROVA{}}} = [
...>    mod: Map, call: [call1, call3, call2],
...>    value: %{a: 1}, result: 99,
...> ] |> PROVA.new! |> PROVA.test
...> answer
99

These two examples show the use of the :test_namer. Note it is applied to precreated cridars as well.

iex> {:ok, {answer, %PROVA{}}} = [
...>    test_namer: fn :g -> :get end,
...>    module: Map, value: %{a: 42},
...>    args: [:a], call: [:g], result: 42,
...> ] |> PROVA.new! |> PROVA.test
...> answer
42

iex> call1 = [f: :d, rest_args: :a] |> CRIDAR.new!
...> call3 = [f: :p, rest_args: [:a, 99]]
...> call2 = [f: :g, rest_args: [:a, :no_a_found]] |> CRIDAR.new!
...> test_namer = fn
...>   :g -> :get
...>   :p -> :put
...>   :d -> :delete
...> end
...> {:ok, {answer, %PROVA{}}} = [
...>    namer: test_namer,
...>    mod: Map, call: [call1, call3, call2],
...>    value: %{a: 1}, result: 99,
...> ] |> PROVA.new! |> PROVA.test
...> answer
99

The new few examples demonstrate the use of :test_comp. First, if the :test_comp is a function, it is treated as a :test_result function. Here is always returns true.

iex> {:ok, {answer, %PROVA{}}} = [
...>    compare: fn _ -> true end,
...>    module: Map, value: %{a: 42},
...>    args: [:a], call: [:get],
...> ] |> PROVA.new! |> PROVA.test
...> answer
42

Otherwise the :test_comp is used to create a compare prova. which is then, in turn, used to create a :test_result arity 2 function for the test prova.

When the test prova’s :test_result fun/2 function is called, the first argument (the test answer) is used to set the compare prova’s :test_result value (but only if not already set).

Similarly the :test_value from the second argument (the test prova) is used to set the compare prova’s :test_value (but again only if not already set).

The compare prova is then tested and if it returns true according to the extended truthy definition, {:ok, {test_answer, test_prova}} is returned.

iex> {:ok, {answer, %PROVA{}}} = [
...>    compare: [call: fn test_value -> test_value |> Map.get(:a) end],
...>    module: Map, value: %{a: 42},
...>    args: [:a], call: [:get],
...> ] |> PROVA.new! |> PROVA.test
...> answer
42

iex> {:error, error} = [
...>    compare: [call: fn test_value -> test_value |> Map.get(:b) end],
...>    module: Map, value: %{a: 42},
...>    args: [:a], call: [:get],
...> ] |> PROVA.new! |> PROVA.test
...> error |> Exception.message
"result invalid, got: 42"

update/2 takes an instance of the module’s struct and an optional opts.

The opts are normalised by calling the module’s update_canonical_opts/1 and then reduced with update_field/2:

 opts |> Enum.reduce(instance, fn {k,v}, s -> s |> update_field({k,v}) end)

{:ok, instance} is returned.

update!/2 calls update/2 and, if the result is {:ok, instance} returns the instance.