UnitTests/cppunit/include/cppunit/TestPath.h

   1 #ifndef CPPUNIT_TESTPATH_H
   2 #define CPPUNIT_TESTPATH_H
   3
   4 #include <cppunit/Portability.h>
   5
   6 #if CPPUNIT_NEED_DLL_DECL
   7 #pragma warning( push )
   8 #pragma warning( disable: 4251 )  // X needs to have dll-interface to be used by clients of class Z
   9 #endif
  10
  11 #include <cppunit/portability/CppUnitDeque.h>
  12 #include <string>
  13
  14 CPPUNIT_NS_BEGIN
  15
  16
  17 class Test;
  18
  19 #if CPPUNIT_NEED_DLL_DECL
  20 //  template class CPPUNIT_API std::deque<Test *>;
  21 #endif
  22
  23
  24 /*! \brief A List of Test representing a path to access a Test.
  25  * \ingroup ExecutingTest
  26  *
  27  * The path can be converted to a string and resolved from a string with toString()
  28  * and TestPath( Test *root, const std::string &pathAsString ).
  29  *
  30  * Pointed tests are not owned by the class.
  31  *
  32  * \see Test::resolvedTestPath()
  33  */
  34 class CPPUNIT_API TestPath
  35 {
  36 public:
  37   /*! \brief Constructs an invalid path.
  38    *
  39    * The path is invalid until a test is added with add().
  40    */
  41   TestPath();
  42
  43   /*! \brief Constructs a valid path.
  44    *
  45    * \param root Test to add.
  46    */
  47   TestPath( Test *root );
  48
  49   /*! \brief Constructs a path using a slice of another path.
  50    * \param otherPath Path the test are copied from.
  51    * \param indexFirst Zero based index of the first test to copy. Adjusted to be in valid
  52    *                   range. \a count is adjusted with \a indexFirst.
  53    * \param count Number of tests to copy. If < 0 then all test starting from index
  54    *              \a indexFirst are copied.
  55    */
  56   TestPath( const TestPath &otherPath,
  57             int indexFirst,
  58             int count = -1 );
  59
  60   /*! \brief Resolves a path from a string returned by toString().
  61    *
  62    * If \a pathAsString is an absolute path (begins with '/'), then the first test name
  63    * of the path must be the name of \a searchRoot. Otherwise, \a pathAsString is a
  64    * relative path, and the first test found using Test::findTest() matching the first
  65    * test name is used as root. An empty string resolve to a path containing
  66    * \a searchRoot.
  67    *
  68    * The resolved path is always valid.
  69    *
  70    * \param searchRoot Test used to resolve the path.
  71    * \param pathAsString String that contains the path as a string created by toString().
  72    * \exception std::invalid_argument if one of the test names can not be resolved.
  73    * \see toString().
  74    */
  75   TestPath( Test *searchRoot,
  76             const std::string &pathAsString );
  77
  78   /*! \brief Copy constructor.
  79    * \param other Object to copy.
  80    */
  81   TestPath( const TestPath &other );
  82
  83   virtual ~TestPath();
  84
  85   /*! \brief Tests if the path contains at least one test.
  86    * \return \c true if the path contains at least one test, otherwise returns \c false.
  87    */
  88   virtual bool isValid() const;
  89
  90   /*! \brief Adds a test to the path.
  91    * \param test Pointer on the test to add. Must not be \c NULL.
  92    */
  93   virtual void add( Test *test );
  94
  95   /*! \brief Adds all the tests of the specified path.
  96    * \param path Path that contains the test to add.
  97    */
  98   virtual void add( const TestPath &path );
  99
 100   /*! \brief Inserts a test at the specified index.
 101    * \param test Pointer on the test to insert. Must not be \c NULL.
 102    * \param index Zero based index indicating where the test is inserted.
 103    * \exception std::out_of_range is \a index < 0 or \a index > getTestCount().
 104    */
 105   virtual void insert( Test *test, int index );
 106
 107   /*! \brief Inserts all the tests at the specified path at a given index.
 108    * \param path Path that contains the test to insert.
 109    * \param index Zero based index indicating where the tests are inserted.
 110    * \exception std::out_of_range is \a index < 0 or \a index > getTestCount(), and
 111    *            \a path is valid.
 112    */
 113   virtual void insert( const TestPath &path, int index );
 114
 115   /*! \brief Removes all the test from the path.
 116    *
 117    * The path becomes invalid after this call.
 118    */
 119   virtual void removeTests();
 120
 121   /*! \brief Removes the test at the specified index of the path.
 122    * \param index Zero based index of the test to remove.
 123    * \exception std::out_of_range is \a index < 0 or \a index >= getTestCount().
 124    */
 125   virtual void removeTest( int index );
 126
 127   /*! \brief Removes the last test.
 128    * \exception std::out_of_range is the path is invalid.
 129    * \see isValid().
 130    */
 131   virtual void up();
 132
 133   /*! \brief Returns the number of tests in the path.
 134    * \return Number of tests in the path.
 135    */
 136   virtual int getTestCount() const;
 137
 138   /*! \brief Returns the test of the specified index.
 139    * \param index Zero based index of the test to return.
 140    * \return Pointer on the test at index \a index. Never \c NULL.
 141    * \exception std::out_of_range is \a index < 0 or \a index >= getTestCount().
 142    */
 143   virtual Test *getTestAt( int index ) const;
 144
 145   /*! \brief Get the last test of the path.
 146    * \return Pointer on the last test (test at the bottom of the hierarchy). Never \c NULL.
 147    * \exception std::out_of_range if the path is not valid ( isValid() returns \c false ).
 148    */
 149   virtual Test *getChildTest() const;
 150
 151   /*! \brief Returns the path as a string.
 152    *
 153    * For example, if a path is composed of three tests named "All Tests", "Math" and
 154    * "Math::testAdd", toString() will return:
 155    *
 156    * "All Tests/Math/Math::testAdd".
 157    *
 158    * \return A string composed of the test names separated with a '/'. It is a relative
 159    *         path.
 160    */
 161   virtual std::string toString() const;
 162
 163   /*! \brief Assignment operator.
 164    * \param other Object to copy.
 165    * \return This object.
 166    */
 167   TestPath &operator =( const TestPath &other );
 168
 169 protected:
 170   /*! \brief Checks that the specified test index is within valid range.
 171    * \param index Zero based index to check.
 172    * \exception std::out_of_range is \a index < 0 or \a index >= getTestCount().
 173    */
 174   void checkIndexValid( int index ) const;
 175
 176   /// A list of test names.
 177   typedef CppUnitDeque<std::string> PathTestNames;
 178
 179   /*! \brief Splits a path string into its test name components.
 180    * \param pathAsString Path string created with toString().
 181    * \param testNames Test name components are added to that container.
 182    * \return \c true if the path is relative (does not begin with '/'), \c false
 183    *         if it is absolute (begin with '/').
 184    */
 185   bool splitPathString( const std::string &pathAsString,
 186                         PathTestNames &testNames );
 187
 188   /*! \brief Finds the actual root of a path string and get the path string name components.
 189    * \param searchRoot Test used as root if the path string is absolute, or to search
 190    *                   the root test if the path string is relative.
 191    * \param pathAsString Path string. May be absolute or relative.
 192    * \param testNames Test name components are added to that container.
 193    * \return Pointer on the resolved root test. Never \c NULL.
 194    * \exception std::invalid_argument if either the root name can not be resolved or if
 195    *            pathAsString contains no name components.
 196    */
 197   Test *findActualRoot( Test *searchRoot,
 198                         const std::string &pathAsString,
 199                         PathTestNames &testNames );
 200
 201 protected:
 202   typedef CppUnitDeque<Test *> Tests;
 203   Tests m_tests;
 204
 205 };
 206
 207
 208 CPPUNIT_NS_END
 209
 210 #endif // CPPUNIT_TESTPATH_H
 211