source: trunk/contrib/cppunit-1.12.2/include/cppunit/TestPath.h @ 876

Last change on this file since 876 was 876, checked in by sam, 9 years ago

contrib: add a precompiled Win32 version of CppUnit and update build system
accordingly.

File size: 7.0 KB
Line 
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
14CPPUNIT_NS_BEGIN
15
16
17class 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 */
34class CPPUNIT_API TestPath
35{
36public:
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
169protected:
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
201protected:
202  typedef CppUnitDeque<Test *> Tests;
203  Tests m_tests;
204
205};
206
207
208CPPUNIT_NS_END
209
210#endif // CPPUNIT_TESTPATH_H
211
Note: See TracBrowser for help on using the repository browser.