:orphan:

.. index:: pair: group; Test execution flow
.. _doxid-group__te__ts__tapi__test__log:

Test execution flow
===================

.. toctree::
	:hidden:

Overview
~~~~~~~~

Macros to be used in tests. :ref:`More...<details-group__te__ts__tapi__test__log>`


.. ref-code-block:: cpp
	:class: doxyrest-overview-code-block

	
	// global functions

	void :ref:`te_test_tester_message<doxid-group__te__ts__tapi__test__log_1gaf5004db4652f5789174a33a89035aa77>`(:ref:`te_test_msg_type<doxid-tester__msg_8h_1aa1da7549e6672ee1d6bb2c81e5a1e8ab>` type, const char* fmt, ...);
	void :ref:`te_test_fail_state_update<doxid-group__te__ts__tapi__test__log_1gacd22a80c2a7a6d7acf9d92353c0b99e9>`(const char* fmt, ...);
	void void :ref:`te_test_fail_substate_update<doxid-group__te__ts__tapi__test__log_1ga2c4b6690699496d4f9e6db384f4cef15>`(const char* fmt, ...);
	void void const char* :ref:`te_test_fail_state_get<doxid-group__te__ts__tapi__test__log_1gaf0ab6292ac92962aa7ba26ae7fc088d7>`(void);
	const char* :ref:`te_test_fail_substate_get<doxid-group__te__ts__tapi__test__log_1gaebb37dcd7deea2eef2038a14fc4516b5>`(void);

	// macros

	#define :ref:`ERROR_ARTIFACT<doxid-group__te__ts__tapi__test__log_1gabecf331a6fe9014e274781c943ed6d1c>`(_fmt...)
	#define :ref:`ERROR_VERDICT<doxid-group__te__ts__tapi__test__log_1ga94071907f6aa95da8040a653092be626>`(fmt...)
	#define :ref:`MI_ARTIFACT<doxid-group__te__ts__tapi__test__log_1ga905a2f63d85ae43512fa8917dcb2a8ed>`(_fmt...)
	#define :ref:`REGISTER_ARTIFACT<doxid-group__te__ts__tapi__test__log_1gadb673e27dd5ed24f60e177f7bb32a4c0>`(_level, _fmt...)
	#define :ref:`RING_ARTIFACT<doxid-group__te__ts__tapi__test__log_1gac3b18300a5051e2880f6548a7c1aa86d>`(_fmt...)
	#define :ref:`RING_VERDICT<doxid-group__te__ts__tapi__test__log_1ga0da50d9de370aed732bc0056d56e4d2f>`(fmt...)
	#define :ref:`TEST_ARTIFACT<doxid-group__te__ts__tapi__test__log_1gadf1d117abc8e842875100d64a98177e1>`(_fmt...)
	#define :ref:`TEST_OBJECTIVE<doxid-group__te__ts__tapi__test__log_1ga8e5c25eedbab5d25178a770cdaf4788e>`(fmt...)
	#define :ref:`TEST_STEP<doxid-group__te__ts__tapi__test__log_1gafdd8471d8dcb92d81fa0df1bcceaa77d>`(_fs...)
	#define :ref:`TEST_STEP_NEXT<doxid-group__te__ts__tapi__test__log_1ga3b9afda36e3e9422f12942558f6e37bb>`(_fs...)
	#define :ref:`TEST_STEP_POP<doxid-group__te__ts__tapi__test__log_1gaf42441766f2a59bd57bab60cc1006ee8>`(_fs...)
	#define :ref:`TEST_STEP_POP_INFO<doxid-group__te__ts__tapi__test__log_1ga22f0ea90e4a021a6741e3e9960598813>`(_fs...)
	#define :ref:`TEST_STEP_PUSH<doxid-group__te__ts__tapi__test__log_1gaea0bf5d3c96ab194d2a00b5be6b6c1ed>`(_fs...)
	#define :ref:`TEST_STEP_PUSH_INFO<doxid-group__te__ts__tapi__test__log_1ga3f132a98e8440abb3b7aa511a6e030a2>`(_fs...)
	#define :ref:`TEST_STEP_RESET<doxid-group__te__ts__tapi__test__log_1gacaf08e99854b92d1bed2416b1ad7e039>`()
	#define :ref:`TEST_SUBSTEP<doxid-group__te__ts__tapi__test__log_1ga4de4e7fc71504a98421234f5bd1e5869>`(_fs...)
	#define :ref:`TEST_VERDICT<doxid-group__te__ts__tapi__test__log_1gaa36c8292e774ba1625bcb80593cfb006>`(fmt...)
	#define :ref:`TE_TEST_OBJECTIVE_ID<doxid-group__te__ts__tapi__test__log_1gab4c10abf1b0c1254bbe683e65604c66d>`
	#define :ref:`WARN_ARTIFACT<doxid-group__te__ts__tapi__test__log_1ga5a5fb4f324b09568fb7eecafe0e2dc8a>`(_fmt...)
	#define :ref:`WARN_VERDICT<doxid-group__te__ts__tapi__test__log_1ga5feb21a8b2453917f3d4cc043bcff599>`(fmt...)

.. _details-group__te__ts__tapi__test__log:

Detailed Documentation
~~~~~~~~~~~~~~~~~~~~~~

Macros to be used in tests. The header must be included from test sources only. It is allowed to use the macros only from **main()** function of the test.

Copyright (C) 2004-2022 OKTET Labs Ltd. All rights reserved.

Global Functions
----------------

.. index:: pair: function; te_test_tester_message
.. _doxid-group__te__ts__tapi__test__log_1gaf5004db4652f5789174a33a89035aa77:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	void te_test_tester_message(:ref:`te_test_msg_type<doxid-tester__msg_8h_1aa1da7549e6672ee1d6bb2c81e5a1e8ab>` type, const char* fmt, ...)

Compose test message and send it to Tester.

The function uses *te_test_id* global variable.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- type

		- Message type

	*
		- fmt

		- printf()-like format string with TE extensions

.. index:: pair: function; te_test_fail_state_update
.. _doxid-group__te__ts__tapi__test__log_1gacd22a80c2a7a6d7acf9d92353c0b99e9:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	void te_test_fail_state_update(const char* fmt, ...)

Update state of the test to be dumped in case of failure.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- fmt

		- printf()-like format string w/o! TE extensions

.. index:: pair: function; te_test_fail_substate_update
.. _doxid-group__te__ts__tapi__test__log_1ga2c4b6690699496d4f9e6db384f4cef15:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	void void te_test_fail_substate_update(const char* fmt, ...)

Update substate of the test to be dumped in case of failure.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- fmt

		- printf()-like format string w/o! TE extensions

.. index:: pair: function; te_test_fail_state_get
.. _doxid-group__te__ts__tapi__test__log_1gaf0ab6292ac92962aa7ba26ae7fc088d7:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	void void const char* te_test_fail_state_get(void)

Get the current test state string or ``NULL`` if it's not filled in.

.. index:: pair: function; te_test_fail_substate_get
.. _doxid-group__te__ts__tapi__test__log_1gaebb37dcd7deea2eef2038a14fc4516b5:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	const char* te_test_fail_substate_get(void)

Get the current test substate string or ``NULL`` if it's not filled in.

Macros
------

.. index:: pair: define; ERROR_ARTIFACT
.. _doxid-group__te__ts__tapi__test__log_1gabecf331a6fe9014e274781c943ed6d1c:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define ERROR_ARTIFACT(_fmt...)

Macro should be used to output artifact with ERROR log level from tests.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- _fmt

		- the content of the artifact as format string with arguments

.. index:: pair: define; ERROR_VERDICT
.. _doxid-group__te__ts__tapi__test__log_1ga94071907f6aa95da8040a653092be626:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define ERROR_VERDICT(fmt...)

Macro should be used to output verdict with ERROR log level from tests.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- fmt

		- the content of the verdict as format string with arguments

.. index:: pair: define; MI_ARTIFACT
.. _doxid-group__te__ts__tapi__test__log_1ga905a2f63d85ae43512fa8917dcb2a8ed:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define MI_ARTIFACT(_fmt...)

Macro should be used to output artifact with MI log level from tests.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- _fmt

		- the content of the artifact as format string with arguments

.. index:: pair: define; REGISTER_ARTIFACT
.. _doxid-group__te__ts__tapi__test__log_1gadb673e27dd5ed24f60e177f7bb32a4c0:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define REGISTER_ARTIFACT(_level, _fmt...)

Print test artifact to log. Artifact is a string describing test results like a verdict. But it is not taken into account when matching obtained results to TRC database.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- _level

		- Level of the message/artifact that will go into the log

	*
		- _fmt

		- Message describing the artifact (format string with parameters)

.. index:: pair: define; RING_ARTIFACT
.. _doxid-group__te__ts__tapi__test__log_1gac3b18300a5051e2880f6548a7c1aa86d:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define RING_ARTIFACT(_fmt...)

Macro should be used to output artifact from tests.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- _fmt

		- the content of the artifact as format string with arguments

.. index:: pair: define; RING_VERDICT
.. _doxid-group__te__ts__tapi__test__log_1ga0da50d9de370aed732bc0056d56e4d2f:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define RING_VERDICT(fmt...)

Macro should be used to output verdict from tests.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- fmt

		- the content of the verdict as format string with arguments

.. index:: pair: define; TEST_ARTIFACT
.. _doxid-group__te__ts__tapi__test__log_1gadf1d117abc8e842875100d64a98177e1:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define TEST_ARTIFACT(_fmt...)

Print test artifact to log. Artifact is a string describing test results like a verdict. But it is not taken into account when matching obtained results to TRC database.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- _fmt

		- Message describing the artifact (format string with parameters)

.. index:: pair: define; TEST_OBJECTIVE
.. _doxid-group__te__ts__tapi__test__log_1ga8e5c25eedbab5d25178a770cdaf4788e:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define TEST_OBJECTIVE(fmt...)

The macro should be used to output per-iteration test objectives



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- fmt

		- Format string for the following arguments

.. index:: pair: define; TEST_STEP
.. _doxid-group__te__ts__tapi__test__log_1gafdd8471d8dcb92d81fa0df1bcceaa77d:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define TEST_STEP(_fs...)

Logging of nesting level step.

Reset nesting level to 0, log message with zero nesting level and increment it for subsequent messages (level equal to 1). The macro should be used in the test main function only. The macro is used to extract the test description (generated using Doxygen).



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- _fs

		- - format string and arguments

.. index:: pair: define; TEST_STEP_NEXT
.. _doxid-group__te__ts__tapi__test__log_1ga3b9afda36e3e9422f12942558f6e37bb:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define TEST_STEP_NEXT(_fs...)

Logging of nesting level step next.

Keep current nesting level, but log the message with previous nesting level. So, the message will have the same nesting level as previous step-push and subsequent step-next messages.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- _fs

		- - format string and arguments

.. index:: pair: define; TEST_STEP_POP
.. _doxid-group__te__ts__tapi__test__log_1gaf42441766f2a59bd57bab60cc1006ee8:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define TEST_STEP_POP(_fs...)

Logging of nesting level step pop.

Decrement log nesting level and log the message (if not empty). It wraps the block and message could be used to summarize results.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- _fs

		- - format string and arguments

.. index:: pair: define; TEST_STEP_POP_INFO
.. _doxid-group__te__ts__tapi__test__log_1ga22f0ea90e4a021a6741e3e9960598813:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define TEST_STEP_POP_INFO(_fs...)

Same as :ref:`TEST_STEP_POP() <doxid-group__te__ts__tapi__test__log_1gaf42441766f2a59bd57bab60cc1006ee8>` but uses INFO log level instead of RING. Should be used together with :ref:`TEST_STEP_PUSH_INFO() <doxid-group__te__ts__tapi__test__log_1ga3f132a98e8440abb3b7aa511a6e030a2>`.

.. index:: pair: define; TEST_STEP_PUSH
.. _doxid-group__te__ts__tapi__test__log_1gaea0bf5d3c96ab194d2a00b5be6b6c1ed:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define TEST_STEP_PUSH(_fs...)

Logging of nesting level step push.

Log message at current nesting level and increment nesting level for subsequent log messages. Subsequent messages will have greater nesting level and will be considered as details of the step implementation.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- _fs

		- - format string and arguments

.. index:: pair: define; TEST_STEP_PUSH_INFO
.. _doxid-group__te__ts__tapi__test__log_1ga3f132a98e8440abb3b7aa511a6e030a2:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define TEST_STEP_PUSH_INFO(_fs...)

Same as :ref:`TEST_STEP_PUSH() <doxid-group__te__ts__tapi__test__log_1gaea0bf5d3c96ab194d2a00b5be6b6c1ed>` but uses INFO log level instead of RING. This results in hiding messages between :ref:`TEST_STEP_PUSH_INFO() <doxid-group__te__ts__tapi__test__log_1ga3f132a98e8440abb3b7aa511a6e030a2>` and corresponding :ref:`TEST_STEP_POP_INFO() <doxid-group__te__ts__tapi__test__log_1ga22f0ea90e4a021a6741e3e9960598813>` in HTML log by default. Such hidden messages can be viewed by clicking on "+".



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- _fs

		- - format string and arguments

.. index:: pair: define; TEST_STEP_RESET
.. _doxid-group__te__ts__tapi__test__log_1gacaf08e99854b92d1bed2416b1ad7e039:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define TEST_STEP_RESET()

Logging of nesting level step reset

Reset nesting level to 0

.. index:: pair: define; TEST_SUBSTEP
.. _doxid-group__te__ts__tapi__test__log_1ga4de4e7fc71504a98421234f5bd1e5869:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define TEST_SUBSTEP(_fs...)

Logging of nesting level sub-step.

Reset nesting level to 1, log message with the nesting level and increment it for subsequent messages (level equal to 2). The macro should be used in the test main function only. The macro is used to extract the test description (generated using Doxygen).



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- _fs

		- - format string and arguments

.. index:: pair: define; TEST_VERDICT
.. _doxid-group__te__ts__tapi__test__log_1gaa36c8292e774ba1625bcb80593cfb006:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define TEST_VERDICT(fmt...)

Terminate a test with failure status, report an error as verdict.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- fmt

		- error message format string with parameters

.. index:: pair: define; TE_TEST_OBJECTIVE_ID
.. _doxid-group__te__ts__tapi__test__log_1gab4c10abf1b0c1254bbe683e65604c66d:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define TE_TEST_OBJECTIVE_ID

A string used to identify per-iteration objectives, generated by test control messages

.. index:: pair: define; WARN_ARTIFACT
.. _doxid-group__te__ts__tapi__test__log_1ga5a5fb4f324b09568fb7eecafe0e2dc8a:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define WARN_ARTIFACT(_fmt...)

Macro should be used to output artifact with WARN log level from tests.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- _fmt

		- the content of the artifact as format string with arguments

.. index:: pair: define; WARN_VERDICT
.. _doxid-group__te__ts__tapi__test__log_1ga5feb21a8b2453917f3d4cc043bcff599:

.. ref-code-block:: cpp
	:class: doxyrest-title-code-block

	#define WARN_VERDICT(fmt...)

Macro should be used to output verdict with WARN log level from tests.



.. rubric:: Parameters:

.. list-table::
	:widths: 20 80

	*
		- fmt

		- the content of the verdict as format string with arguments