1 #ifndef CPPUNIT_TESTPATH_H
2 #define CPPUNIT_TESTPATH_H
4 #include <cppunit/Portability.h>
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
11 #include <cppunit/portability/CppUnitDeque.h>
19 #if CPPUNIT_NEED_DLL_DECL
20 // template class CPPUNIT_API std::deque<Test *>;
24 /*! \brief A List of Test representing a path to access a Test.
25 * \ingroup ExecutingTest
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 ).
30 * Pointed tests are not owned by the class.
32 * \see Test::resolvedTestPath()
34 class CPPUNIT_API TestPath
37 /*! \brief Constructs an invalid path.
39 * The path is invalid until a test is added with add().
43 /*! \brief Constructs a valid path.
45 * \param root Test to add.
47 TestPath( Test *root );
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.
56 TestPath( const TestPath &otherPath,
60 /*! \brief Resolves a path from a string returned by toString().
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
68 * The resolved path is always valid.
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.
75 TestPath( Test *searchRoot,
76 const std::string &pathAsString );
78 /*! \brief Copy constructor.
79 * \param other Object to copy.
81 TestPath( const TestPath &other );
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.
88 virtual bool isValid() const;
90 /*! \brief Adds a test to the path.
91 * \param test Pointer on the test to add. Must not be \c NULL.
93 virtual void add( Test *test );
95 /*! \brief Adds all the tests of the specified path.
96 * \param path Path that contains the test to add.
98 virtual void add( const TestPath &path );
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().
105 virtual void insert( Test *test, int index );
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
113 virtual void insert( const TestPath &path, int index );
115 /*! \brief Removes all the test from the path.
117 * The path becomes invalid after this call.
119 virtual void removeTests();
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().
125 virtual void removeTest( int index );
127 /*! \brief Removes the last test.
128 * \exception std::out_of_range is the path is invalid.
133 /*! \brief Returns the number of tests in the path.
134 * \return Number of tests in the path.
136 virtual int getTestCount() const;
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().
143 virtual Test *getTestAt( int index ) const;
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 ).
149 virtual Test *getChildTest() const;
151 /*! \brief Returns the path as a string.
153 * For example, if a path is composed of three tests named "All Tests", "Math" and
154 * "Math::testAdd", toString() will return:
156 * "All Tests/Math/Math::testAdd".
158 * \return A string composed of the test names separated with a '/'. It is a relative
161 virtual std::string toString() const;
163 /*! \brief Assignment operator.
164 * \param other Object to copy.
165 * \return This object.
167 TestPath &operator =( const TestPath &other );
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().
174 void checkIndexValid( int index ) const;
176 /// A list of test names.
177 typedef CppUnitDeque<std::string> PathTestNames;
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 '/').
185 bool splitPathString( const std::string &pathAsString,
186 PathTestNames &testNames );
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.
197 Test *findActualRoot( Test *searchRoot,
198 const std::string &pathAsString,
199 PathTestNames &testNames );
202 typedef CppUnitDeque<Test *> Tests;
210 #endif // CPPUNIT_TESTPATH_H