source: trunk/contrib/cppunit-1.12.2/include/cppunit/XmlOutputterHook.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: 4.8 KB
Line 
1#ifndef CPPUNIT_XMLOUTPUTTERHOOK_H
2#define CPPUNIT_XMLOUTPUTTERHOOK_H
3
4#include <cppunit/Portability.h>
5
6
7CPPUNIT_NS_BEGIN
8
9
10class Test;
11class TestFailure;
12class XmlDocument;
13class XmlElement;
14
15
16
17/*! \brief Hook to customize Xml output.
18 *
19 * XmlOutputterHook can be passed to XmlOutputter to customize the XmlDocument.
20 *
21 * Common customizations are:
22 * - adding some datas to successfull or failed test with
23 *   failTestAdded() and successfulTestAdded(),
24 * - adding some statistics with statisticsAdded(),
25 * - adding other datas with beginDocument() or endDocument().
26 *
27 * See examples/ClockerPlugIn which makes use of most the hook.
28 *
29 * Another simple example of an outputter hook is shown below. It may be 
30 * used to add some meta information to your result files. In the example,
31 * the author name as well as the project name and test creation date is
32 * added to the head of the xml file.
33 *
34 * In order to make this information stored within the xml file, the virtual
35 * member function beginDocument() is overriden where a new
36 * XmlElement object is created.
37 *
38 * This element is simply added to the root node of the document which
39 * makes the information automatically being stored when the xml file
40 * is written.
41 *
42 * \code
43 * #include <cppunit/XmlOutputterHook.h>
44 * #include <cppunit/XmlElement.h>
45 * #include <cppunit/tools/StringTools.h>
46 *
47 * ...
48 *
49 * class MyXmlOutputterHook : public CppUnit::XmlOutputterHook
50 * {
51 * public:
52 *   MyXmlOutputterHook(const std::string projectName,
53 *                      const std::string author)
54 *   {
55 *      m_projectName = projectName;
56 *      m_author      = author;
57 *   };
58 *
59 *   virtual ~MyXmlOutputterHook()
60 *   {
61 *   };
62 *
63 *   void beginDocument(CppUnit::XmlDocument* document)
64 *   {
65 *     if (!document)
66 *       return;
67 *
68 *     // dump current time
69 *     std::string szDate          = CppUnit::StringTools::toString( (int)time(0) );
70 *     CppUnit::XmlElement* metaEl = new CppUnit::XmlElement("SuiteInfo",
71 *                                                           "");
72 *
73 *     metaEl->addElement( new CppUnit::XmlElement("Author", m_author) );
74 *     metaEl->addElement( new CppUnit::XmlElement("Project", m_projectName) );
75 *     metaEl->addElement( new CppUnit::XmlElement("Date", szDate ) );
76 *   
77 *     document->rootElement().addElement(metaEl);
78 *   };
79 * private:
80 *   std::string m_projectName;
81 *   std::string m_author;
82 * };
83 * \endcode
84 *
85 * Within your application's main code, you need to snap the hook
86 * object into your xml outputter object like shown below:
87 *
88 * \code
89 * CppUnit::TextUi::TestRunner runner;
90 * std::ofstream outputFile("testResults.xml");
91 *
92 * CppUnit::XmlOutputter* outputter = new CppUnit::XmlOutputter( &runner.result(),
93 *                                                               outputFile );   
94 * MyXmlOutputterHook hook("myProject", "meAuthor");
95 * outputter->addHook(&hook);
96 * runner.setOutputter(outputter);   
97 * runner.addTest( VectorFixture::suite() );   
98 * runner.run();
99 * outputFile.close();
100 * \endcode
101 *
102 * This results into the following output:
103 *
104 * \code
105 * <TestRun>
106 *   <suiteInfo>
107 *     <author>meAuthor</author>
108 *     <project>myProject</project>
109 *     <date>1028143912</date>
110 *   </suiteInfo>
111 *   <FailedTests>
112 *    ...
113 * \endcode
114 *
115 * \see XmlOutputter, CppUnitTestPlugIn.
116 */
117class CPPUNIT_API XmlOutputterHook
118{
119public:
120  /*! Called before any elements is added to the root element.
121   * \param document XML Document being created.
122   */
123  virtual void beginDocument( XmlDocument *document );
124
125  /*! Called after adding all elements to the root element.
126   * \param document XML Document being created.
127   */
128  virtual void endDocument( XmlDocument *document );
129
130  /*! Called after adding a fail test element.
131   * \param document XML Document being created.
132   * \param testElement \<FailedTest\> element.
133   * \param test Test that failed.
134   * \param failure Test failure data.
135   */
136  virtual void failTestAdded( XmlDocument *document,
137                              XmlElement *testElement,
138                              Test *test,
139                              TestFailure *failure );
140
141  /*! Called after adding a successful test element.
142   * \param document XML Document being created.
143   * \param testElement \<Test\> element.
144   * \param test Test that was successful.
145   */
146  virtual void successfulTestAdded( XmlDocument *document,
147                                    XmlElement *testElement,
148                                    Test *test );
149
150  /*! Called after adding the statistic element.
151   * \param document XML Document being created.
152   * \param statisticsElement \<Statistics\> element.
153   */
154  virtual void statisticsAdded( XmlDocument *document,
155                                XmlElement *statisticsElement );
156
157  virtual ~XmlOutputterHook() {}
158};
159
160
161CPPUNIT_NS_END
162
163#endif  // CPPUNIT_XMLOUTPUTTERHOOK_H
Note: See TracBrowser for help on using the repository browser.