ceph/src/boost/libs/test/doc/testing_tools/custom_predicates.qbk

   1 [/
   2  / Copyright (c) 2003 Boost.Test contributors
   3  /
   4  / Distributed under the Boost Software License, Version 1.0. (See accompanying
   5  / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   6  /]
   7
   8
   9 [section:custom_predicates Custom predicate support]
  10
  11 [def __class_predicate_result__ [classref boost::test_tools::predicate_result]]
  12
  13 Even though supplied testing tools cover wide range of possible checks and provide detailed report on cause of error in
  14 some cases you may want to implement and use custom predicate that perform complex check and produce intelligent report
  15 on failure. To satisfy this need testing tools implement custom predicate support. There two layers of custom predicate
  16 support implemented by testing tools toolbox: with and without custom error message generation.
  17
  18 The first layer is supported by __BOOST_LEVEL_PREDICATE__ family of testing tools. You can use it to check any custom
  19 predicate that reports the result as boolean value. The values of the predicate arguments are reported by the tool
  20 automatically in case of failure.
  21
  22
  23 [bt_example example30..Custom predicate support using __BOOST_LEVEL_PREDICATE__..run-fail]
  24
  25 To use second layer your predicate has to return __class_predicate_result__.
  26
  27 This class encapsulates boolean result value along with any error or information message you opt to report.
  28
  29 Usually you construct the instance of class __class_predicate_result__ inside your predicate function and return it by
  30 value. The constructor expects one argument - the boolean result value. The constructor is implicit, so you can simply
  31 return boolean value from your predicate and __class_predicate_result__ is constructed automatically to hold your value
  32 and empty message. You can also assign boolean value to the constructed instance. You can check the current predicate
  33 value by using `operator!` or directly accessing public read-only property `p_predicate_value`. The error message is
  34 stored in public read-write property `p_message`.
  35
  36
  37 [bt_example example31..Custom predicate support using class __class_predicate_result__..run-fail]
  38
  39 [endsect] [/predicate]