Using PollingCheck
[Using instructions]

Class PollingCheck allows to repeatedly execute a funtional check for some condition until it becomes true or a timeout has elapsed. More...

Collaboration diagram for Using PollingCheck:

---

Detailed Description

Class PollingCheck allows to repeatedly execute a funtional check for some condition until it becomes true or a timeout has elapsed.

In the context of testing this function should only be used when the following conditions apply:

• the condition represents the reaction of an test object
• the reaction occures asynchronously after some trigger action
• there is no other way to detect the moment of reaction (e.g. by receiving a notification about some state change)

The check of the condition is implemented within a boolean user function. The user function can optionally make use of any other test features (e.g. writing/ checking TestEvents).

Concept for PollingCheck::Run
A user definable function/functor is repeatedly called until the return value is true. If the user function returns false the next call is executed after a definable sleep time. The polling stops as soon as the user function returns true or a definable timeout value has been reached. The return value of Run() indicates whether the condition was fulfilled. The return value can be checked with one of the following methods:

• if
• assert
• BOOST_CHECK
• convenience macro POLL_VERIFY (requires usage of some EventReceiver class e.g. TTB::EventReceiverStdOut)

Elementar usage with if, assert, bind, BOOST_CHECK

 bool VerifyCounterIsZero ()
 {return s_pSomeTestObject->GetCounter() == 0;}

 bool VerifyCounterHasValue (
     int             in_value)
 {return s_pSomeTestObject->GetCounter() == in_value;}

 ... 

 // Configure timeouts used for polling
 TTB::ThePollingCheck()->SetSleepTimeMs(100);
 TTB::ThePollingCheck()->SetTimeoutMs(500);

 // check with if
 if (!TTB::ThePollingCheck()->Run(&VerifyCounterIsZero))
 {
     cout << "VerifyCounterIsZero failed!" << endl;
 }

 // check with assert
 assert(TTB::ThePollingCheck()->Run(&VerifyCounterIsZero));

 // Check with Boost verification macro
 BOOST_CHECK(TTB::ThePollingCheck()->Run(&VerifyCounterIsZero));

 // using bind to make use of any number of function arguments
 assert(TTB::ThePollingCheck()->Run(boost::bind(&VerifyCounterHasValue,98)));

 // directly using the member function to check
 assert(TTB::ThePollingCheck()->Run(boost::bind(
     &SomeTestObject::GetCounter,
     s_pSomeTestObject)==94));

Convenience macro POLL_VERIFY

 // define an EventReceiver to process events detected from the execution and
 // compare mechanism (e.g. use TTB::EventReceiverStdOut)
 TTB::EventReceiverStdOut eventReceiver;
 TTB::ThePollingCheck()->SetEventReceiver(&eventReceiver);
 // optional: configure amount of infos written to stdout
 // eventReceiver.SetOutputFilter(TTB::CTX_ONLY_ERROR);

 // Macro for use with free functions (other variants support also member functions)
 POLL_VERIFY_F1(VerifyCounterHasValue, 96);

In case of error the following output is produced:

 <VerifyCounterHasValue 96 [polling]
 INFO: Poll-Timeout after 515 ms
 c:\userdata\gerald\sw\c\testtoolbox\test\testpollingcheck\testpollingcheck.cpp (184): POLL-ERROR: verification failed

See also:

PollingCheck.h (File documentation)

TestToolBox::PollingCheck (class documentation)

TestPollingCheck (unit test for class Environment)