so_5::experimental::testing::v1 Namespace Reference

Namespaces
namespace	details
namespace	impl

Classes
class	scenario_proxy_t
	A special wrapper around scenario object. More...
class	scenario_result_t
	The result of run of testing scenario. More...
class	step_definition_proxy_t
	A special object that should be used for definition of a step of a testing scenario. More...
class	testing_env_t
	A special testing environment that should be used for testing of agents. More...

Enumerations
enum class	scenario_status_t { not_started , in_progress , completed , timed_out }
	Status of testing scenario. More...

Functions
scenario_result_t	completed ()
	Create a value that means that scenario completed successfuly.
template<typename Msg_Type >
details::trigger_source_t< details::incident_status_t::handled >	reacts_to ()
	Define a trigger that activates when an agent receives and handles a message from the direct mbox.
template<typename Msg_Type >
details::trigger_source_t< details::incident_status_t::handled >	reacts_to (const so_5::mbox_t &mbox)
	Define a trigger that activates when an agent receives and handles a message from the specific mbox.
details::store_agent_state_name_t	store_state_name (std::string tag)
	Create a special marker for a trigger for storing agent's state name inside scenario.
template<typename Lambda >
details::store_msg_inspection_result_t	inspect_msg (std::string tag, Lambda &&inspector)
	Create a special marker for a trigger for inspecting an incoming message and storing the inspection result inside the scenario.
details::wait_event_handler_completion_t	wait_event_handler_completion ()
	Create a special marker for a trigger that requires waiting for completion of an event handler.
template<typename Msg_Type >
details::trigger_source_t< details::incident_status_t::ignored >	ignores ()
	Define a trigger that activates when an agent rejects a message from the direct mbox.
template<typename Msg_Type >
details::trigger_source_t< details::incident_status_t::ignored >	ignores (const so_5::mbox_t &mbox)
	Define a trigger that activates when an agent rejects a message from the direct mbox.
details::constraint_unique_ptr_t	not_before (std::chrono::steady_clock::duration pause)
	Create a constraint not-before.
details::constraint_unique_ptr_t	not_after (std::chrono::steady_clock::duration pause)
	Create a constraint not-after.
template<typename Msg >
details::receives_indicator_t< Msg >	receives ()
	Helper function to be used for a trigger that receives a message/singal from a mbox.

Enumeration Type Documentation

scenario_status_t

enum class so_5::experimental::testing::v1::scenario_status_t

strong

Status of testing scenario.

This enumeration is used by testing scenario itself and by scenario_result_t type.

Since

v.5.5.24

Enumerator
not_started	Testing scenario is not started yet. New step can be added when scenario is in state.
in_progress	Testing scenario is started but not finished yet. New steps can't be added.
completed	Testing scenario is successfuly completed.
timed_out	Testing scenario is not working any more, but it is not completed becase there is no more time to run the scenario.

Definition at line 1142 of file experimental/testing/v1/all.hpp.

Function Documentation

completed()

scenario_result_t so_5::experimental::testing::v1::completed ( )

inlinenodiscard

Create a value that means that scenario completed successfuly.

Usage example:

TEST_CASE("some_case") {
  using namespace so_5::experimental::testing;
 
  testing_env_t env;
  ...
  env.scenario().run_for(std::chrono::milliseconds(500));
 
  REQUIRE(completed() == env.scenario().result());
}

Since

v.5.5.24

Definition at line 1293 of file experimental/testing/v1/all.hpp.

ignores() [1/2]

template<typename Msg_Type >

details::trigger_source_t< details::incident_status_t::ignored > so_5::experimental::testing::v1::ignores ( )

nodiscard

Define a trigger that activates when an agent rejects a message from the direct mbox.

Usage example:

using namespace so_5::experimental::testing;
...
env.scenario().define_step("my_step")
  .when(some_agent & ignores<some_message>());

Attention

It is necessary that agent should be subscribed to that message but ignores it in the current state. If an agent is not subscribed to a message then the message can be simply skipped inside a call to send() function. It means that there won't be delivery of message at all.

Since

v.5.5.24

Definition at line 1502 of file experimental/testing/v1/all.hpp.

ignores() [2/2]

template<typename Msg_Type >

details::trigger_source_t< details::incident_status_t::ignored > so_5::experimental::testing::v1::ignores ( const so_5::mbox_t & mbox )

nodiscard

Define a trigger that activates when an agent rejects a message from the direct mbox.

Usage example:

using namespace so_5::experimental::testing;
...
env.scenario().define_step("my_step")
  .when(some_agent & ignores<some_message>(some_mbox));

Attention

It is necessary that agent should be subscribed to that message but ignores it in the current state. If an agent is not subscribed to a message then the message can be simply skipped inside a call to send() function. It means that there won't be delivery of message at all.

Since

v.5.5.24

Definition at line 1531 of file experimental/testing/v1/all.hpp.

inspect_msg()

template<typename Lambda >

details::store_msg_inspection_result_t so_5::experimental::testing::v1::inspect_msg ( std::string tag, Lambda && inspector )

nodiscard

Create a special marker for a trigger for inspecting an incoming message and storing the inspection result inside the scenario.

Usage example:

using namespace so_5::experimental::testing;
...
env.scenario().define_step("my_step")
  .when(some_agent & reacts_to<some_message>()
    & inspect_msg("msg-check", [](const some_message & msg) -> std::string {
        return msg.some_field == expected_value ? "OK" : "FAILED";
      })
  );
...
env.scenario().run_for(std::chrono::seconds(1));
 
REQUIRE(completed() == env.scenario().result());
REQUIRE("OK" == env.scenario().stored_msg_inspection_result("my_step", "msg-check"));

The inspect_msg() can be used for mutable messages too:

env.scenario().define_step("my_step")
  .when(some_agent & reacts_to<so_5::mutable_msg<some_message>>()
    & inspect_msg("msg-check", [](const some_message & msg) -> std::string {
        return msg.some_field == expected_value ? "OK" : "FAILED";
      })
  );

The inspect_msg() can't be used with signals, because signals have no actual data.

Attention

The inspect_msg() doesn't check the type of the message. So it's possible to make a mistake like this:

env.scenario().define_step("my_step")
  .when(some_agent & reacts_to<some_message>()
    & inspect_msg("msg-check", [](const another_msg & msg) -> std::string {
        return msg.some_field == expected_value ? "OK" : "FAILED";
      })
  );

And this will lead to a run-time error (with possible termination of the application).

Since

v.5.8.3

Parameters

tag	Tag to be used for indentification of the inspection result.
inspector	Inspection functor.

Definition at line 1421 of file experimental/testing/v1/all.hpp.

not_after()

details::constraint_unique_ptr_t so_5::experimental::testing::v1::not_after ( std::chrono::steady_clock::duration pause )

inlinenodiscard

Create a constraint not-after.

That constraint is fulfilled if an event is happened before a specified pause. Time is calculated from moment of preactivation of a scenario's step.

Usage example:

using namespace so_5::experimental::testing;
env.scenario().define_step("my_step")
  .constraints(not_after(std::chrono::milliseconds(50)))
  .when(some_agent & reacts_to<some_message>());

In that case step won't be activated if agent receives a message after, for example, 55ms.

Note

If not_after() is used with not_before() then the correctness of those constraints is not checked.

Since

v.5.5.24

Definition at line 1595 of file experimental/testing/v1/all.hpp.

not_before()

details::constraint_unique_ptr_t so_5::experimental::testing::v1::not_before ( std::chrono::steady_clock::duration pause )

inlinenodiscard

Create a constraint not-before.

That constraint is fulfilled if an event is happened after a specified pause. Time is calculated from moment of preactivation of a scenario's step.

Usage example:

using namespace so_5::experimental::testing;
env.scenario().define_step("my_step")
  .constraints(not_before(std::chrono::milliseconds(50)))
  .when(some_agent & reacts_to<some_message>());

In that case step won't be activated if agent receives a message after, for example, 15ms.

Note

If not_before() is used with not_after() then the correctness of those constraints is not checked.

Since

v.5.5.24

Definition at line 1564 of file experimental/testing/v1/all.hpp.

reacts_to() [1/2]

template<typename Msg_Type >

details::trigger_source_t< details::incident_status_t::handled > so_5::experimental::testing::v1::reacts_to ( )

nodiscard

Define a trigger that activates when an agent receives and handles a message from the direct mbox.

Usage example:

using namespace so_5::experimental::testing;
...
env.scenario().define_step("my_step")
  .when(some_agent & reacts_to<some_message>());

Since

v.5.5.24

Definition at line 1312 of file experimental/testing/v1/all.hpp.

reacts_to() [2/2]

template<typename Msg_Type >

details::trigger_source_t< details::incident_status_t::handled > so_5::experimental::testing::v1::reacts_to ( const so_5::mbox_t & mbox )

nodiscard

Define a trigger that activates when an agent receives and handles a message from the specific mbox.

Usage example:

using namespace so_5::experimental::testing;
...
env.scenario().define_step("my_step")
  .when(some_agent & reacts_to<some_message>(some_mbox));

Since

v.5.5.24

Definition at line 1334 of file experimental/testing/v1/all.hpp.

receives()

template<typename Msg >

details::receives_indicator_t< Msg > so_5::experimental::testing::v1::receives ( )

nodiscard

Helper function to be used for a trigger that receives a message/singal from a mbox.

Usage example:

so_5::testing::testing_env_t env;
...
so_5::mbox_t dest = env.environment().create_mbox();
...
env.scenario().define_step("message_arrives")
  .when(dest & tests::receives<some_msg>());
...

Since v.5.8.4 this helper can be used for the same mbox and the same message type several times in one scenario (but in different scenario steps):

so_5::testing::testing_env_t env;
...
so_5::mbox_t dest = env.environment().create_mbox();
...
env.scenario().define_step("message_arrives")
  .when(dest & tests::receives<some_msg>());
...
env.scenario().define_step("another_time")
  .when(dest & tests::receives<some_msg>());
...
env.scenario().define_step("and_yet_another_time")
  .when(dest & tests::receives<some_msg>());

Note

A mutable message can be specified too. But the mbox should allow subscription for mutable messages. For example:

so_5::testing::testing_env_t env;
...
so_5::mbox_t dest = so_5::make_unique_subscribers_mbox(env.environment());
...
env.scenario().define_step("message_arrives")
  .when(dest & tests::receives< so_5::mutable_msg<some_msg> >());
...

Since

v.5.8.3

Definition at line 2237 of file experimental/testing/v1/all.hpp.

store_state_name()

details::store_agent_state_name_t so_5::experimental::testing::v1::store_state_name ( std::string tag )

inlinenodiscard

Create a special marker for a trigger for storing agent's state name inside scenario.

Usage example:

using namespace so_5::experimental::testing;
...
env.scenario().define_step("my_step")
  .when(some_agent & reacts_to<some_message>() & store_agent_name("my_agent"));
...
env.scenario().run_for(std::chrono::seconds(1));
 
REQUIRE(completed() == env.scenario().result());
REQUIRE("some_state" == env.scenario().stored_state_name("my_step", "my_agent"));

Since

v.5.5.24

Definition at line 1363 of file experimental/testing/v1/all.hpp.

wait_event_handler_completion()

details::wait_event_handler_completion_t so_5::experimental::testing::v1::wait_event_handler_completion ( )

inlinenodiscard

Create a special marker for a trigger that requires waiting for completion of an event handler.

Usage example:

using namespace so_5::experimental::testing;
...
env.scenario().define_step("my_step")
  .when(some_agent & reacts_to<some_message>() & wait_event_handler_completion());
...
env.scenario().run_for(std::chrono::seconds(1));
 
REQUIRE(completed() == env.scenario().result());

Note

This marker can be combined with reacts_to(), but not with ignores().

Since

v.5.8.3

Definition at line 1473 of file experimental/testing/v1/all.hpp.