[gtest-runner-qt] r26 committed - Removed useless file. Added some more documentation.
gtest-r...@googlecode.com
Author: sandychapman
Date: Tue Aug 10 15:48:07 2010
Log: Removed useless file. Added some more documentation.
http://code.google.com/p/gtest-runner-qt/source/detail?r=26
Deleted:
/trunk/include/GTestResultsItem.h
Modified:
/trunk/GTestRunner.pro
/trunk/include/GTest.h
/trunk/include/GTestExecutable.h
/trunk/include/GTestParser.h
/trunk/include/GTestResults.h
/trunk/src/GTestExecutable.cpp
=======================================
--- /trunk/include/GTestResultsItem.h Sat Aug 7 11:11:45 2010
+++ /dev/null
@@ -1,24 +0,0 @@
-/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* * * * * * * * * *
- * GTestResultItem.h - Created on 2010-07-29
- *
- * Copyright (C) 2010 Sandy Chapman
- *
- * This library is free software; you can redistribute it and/or modify it
under the
- * terms of the GNU Lesser General Public License as published by the Free
Software
- * Foundation; either version 2.1 of the License, or (at your option) any
later version.
- * This library is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY;
- * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.
- * See the GNU Lesser General Public License for more details.
- * You should have received a copy of the GNU Lesser General Public
License along with this
- * library; if not, write to the Free Software Foundation, Inc., 59 Temple
Place, Suite 330,
- * Boston, MA 02111-1307 USA
- * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* * * * * * * * * */
-
-#ifndef GTESTRESULTITEM_H_
-#define GTESTRESULTITEM_H_
-
-class GTestResultsItem {
-
-};
-
-#endif /* GTESTRESULTITEM_H_ */
=======================================
--- /trunk/GTestRunner.pro Sat Aug 7 11:11:45 2010
+++ /trunk/GTestRunner.pro Tue Aug 10 15:48:07 2010
@@ -4,7 +4,6 @@
gui
HEADERS += include/TestTreeWidgetItem.h \
include/TestTreeWidget.h \
- include/GTestResultsItem.h \
include/GTestSuiteResults.h \
include/GTestResults.h \
include/GTestSuite.h \
=======================================
--- /trunk/include/GTest.h Sun Aug 8 10:59:31 2010
+++ /trunk/include/GTest.h Tue Aug 10 15:48:07 2010
@@ -24,7 +24,7 @@
#include "GTestResults.h"
-/*! \brief The class logically represents a single unit test.
+/*! \brief This class logically represents a single unit test.
*
* This class attempts to mirror what an actual unit test is comprised of.
* For example, it contains a name and a result and the varying methods
=======================================
--- /trunk/include/GTestExecutable.h Sat Aug 7 11:11:45 2010
+++ /trunk/include/GTestExecutable.h Tue Aug 10 15:48:07 2010
@@ -26,31 +26,49 @@
#include "GTestExecutableResults.h"
#include "GTestSuite.h"
+/*! \brief This class logically represens a gtest executable file.
+ *
+ * This class attempts to mirror what an actual gtest executable is
comprised of.
+ * For example, it contains a name (filepath) and contains a collection
+ * of unit test suites. Thus, this structure is reflected in objects of
this
+ * type hold a number of GTestSuites which hold the actual GTests.
+ * \note This file may separate into two or more classes to separate the
+ * process functionality from the logic. However, as it stands now,
+ * I think this is acceptable (for the current size).
+ */
class GTestExecutable : public GTestSuite {
Q_OBJECT
public:
+
+ /*! The state of the file executable as determined by the name
+ * instance variable (which is actually the file path).
+ */
enum STATE {
- VALID = 0x0,
- FILE_NOT_FOUND = 0x1,
- INSUFFICIENT_PRIVILEGES = 0x2
+ VALID = 0x0, /*!< The file exists and is a valid gtest
+ * executable */
+ FILE_NOT_FOUND = 0x1, //!< The file does not exist
+ INSUFFICIENT_PRIVILEGES = 0x2 /*!< The file exists, but the user has
+ * insufficient privileges to view it */
};
private:
- STATE state;
- QMutex processLock;
- QMutex outputLock;
- QProcess *gtest;
- QBuffer standardOutput;
- QBuffer standardError;
- QStringList listing;
- QStringList testsToRun;
- bool runOnSignal;
-
- QProcess::ProcessError error;
- QProcess::ExitStatus exitStatus;
- int exitCode;
+ STATE state; //!< The state of the executable defined by 'name'
+ QMutex processLock; //!< A lock to ensure only a single process is active
+ QMutex outputLock; /*!< A lock to ensure that the output buffers only
+ * have a single writer. */
+ QProcess *gtest; //!< The process thread for running tests.
+ QBuffer standardOutput; //!< The buffer to hold the stdout text.
+ QBuffer standardError; //!< The buffer to hold the stderr text.
+ QStringList listing; //!< The list of unit test suites provided.
+ QStringList testsToRun; //!< The list of tests to run.
+ bool runOnSignal; /*!< A flag to indicate whether a process should be
+ * run when the runTest slot is called */
+
+ QProcess::ProcessError error; //!< The state of the QProcess after its run
+ QProcess::ExitStatus exitStatus;//!< The exit status of the QProcess
+ int exitCode; //!< The exit code of the QProcess
void runExecutable(QStringList args);
void readExecutableOutput(QBuffer& standardChannel);
@@ -70,7 +88,6 @@
public:
GTestExecutable(QObject* parent = 0, QString executablePath = QString());
- GTestExecutable(const GTestExecutable& other);
virtual ~GTestExecutable();
//GETS:
@@ -92,20 +109,68 @@
Q_DECLARE_METATYPE(GTestExecutable*);
+/*! \brief Retrieves the listing (not necessarily populated).
+ *
+ * The caller should ensure that produce listing has been called first and
+ * that the QProcess has successfully completed.
+ * \see GTestExecutable::produceListing()
+ */
inline QStringList GTestExecutable::getListing() const { return listing; }
+/*! \brief Retrieves the executable path (i.e. name) of the executable file
+ *
+ * \note This function duplicates the functionality of getName(), however,
+ * this is semantically clearer. This should either be removed, or
+ * perhaps a 'name' and 'filepath' could be two separate variables
+ * where 'filepath' is the full path and 'name' is simply the filename.
+ * \TODO TODO::create a new instance variable 'filePath'.
+ */
inline QString GTestExecutable::getExecutablePath() const { return name; }
+/*! \brief Retrieves the error produced from running the gtest executable.
+ *
+ * This is only populated after either produceListing() or runTest() is
called
+ * while the state is STATE::VALID.
+ */
inline QProcess::ProcessError GTestExecutable::getError() const { return
error; }
+/*! \brief Retrieves the exit status from running the gtest executable.
+ *
+ * This is only populated after either produceListing() or runTest() is
called
+ * while the state is STATE::VALID.
+ */
inline QProcess::ExitStatus GTestExecutable::getExitStatus() const {
return exitStatus; }
+/*! \brief Retrieves the exit code from running the gtest executable.
+ *
+ * This is only populated after either produceListing() or runTest() is
called
+ * while the state is STATE::VALID.
+ */
inline int GTestExecutable::getExitCode() const { return exitCode; }
+/*! \brief Sets the executable's path.
+ *
+ * This will set the executables path. One can check to see if the path is
+ * valid and that produceListing() and runTest() will work by calling
+ * GTestExecutable::getState()
+ * \param executablePath The fully qualified path to a gtest executable.
+ * \TODO TODO::set the return value of this function to return STATE
+ */
inline void GTestExecutable::setExecutablePath(QString executablePath) {
this->name = executablePath; }
+/*! \brief Sets the flag that determines whether this GTestExecutable
+ * responds to the runTest() slot.
+ *
+ * \param runOnSignal whether the flag should allow the signal (true), or
not.
+ */
inline void GTestExecutable::setRunFlag(bool runOnSignal) {
this->runOnSignal = runOnSignal; }
+/*! \brief Slot that resets the run state of this executable.
+ *
+ * Resetting the executable prepares it to be run again and produce new
+ * test results.
+ * \TODO TODO::This should be clearing the buffers, runList, etc.
+ */
inline void GTestExecutable::resetRunState() { setRunFlag(false); }
#endif /* GTESTEXECUTABLE_H_ */
=======================================
--- /trunk/include/GTestParser.h Thu Jul 29 17:53:34 2010
+++ /trunk/include/GTestParser.h Tue Aug 10 15:48:07 2010
@@ -22,16 +22,22 @@
#include "GTestExecutableResults.h"
+/*! \brief This class parses an .xml file outputted by a gtest executable.
+ *
+ * This parser takes a generic QIODevice and parses the results out of it.
+ * The iodevice enables a user to pass anything from a file handle (QFile)
+ * to a buffer (QBuffer). The parsed results are returned as a tree of
+ * GTestResults objects.
+ */
class GTestParser {
private:
- QIODevice *xmlSource;
+ QIODevice *xmlSource; //!< A pointer to the gtest .xml source
public:
GTestParser(QIODevice *inStream);
GTestExecutableResults* parse();
-
};
#endif /* GTESTPARSER_H_ */
=======================================
--- /trunk/include/GTestResults.h Sat Aug 7 11:11:45 2010
+++ /trunk/include/GTestResults.h Tue Aug 10 15:48:07 2010
@@ -19,24 +19,35 @@
#include <QStringList>
+/* \brief This class logically represents the results of running a unit
test.
+ *
+ * The class is the analogue to a gtest unit test result. It consists of
the name of
+ * the test (which is used to assign the result to the correct GTest), the
running
+ * time of the test, any failure messages that were produced and a summary
result
+ * status (pass/fail). In the subclasses, these variables also apply, but
differ
+ * in that a GTestSuiteResults comprises the results of all tests within
the suite.
+ */
class GTestResults {
public:
+ //! The run status of the GTest.
enum STATUS {
- RUN,
- UNDEFINED
+ RUN, //!< The test was run.
+ //! \TODO TODO::Investigate other run status of a GTest.
+ UNDEFINED //!< Currently not sure what the other possibilities are.
};
+ //! The outcome of the running of the test.
enum OUTCOME {
- PASSED,
- FAILED
+ PASSED, //The test passed.
+ FAILED //The test has at least one failure.
};
protected:
- QString name;
- uint time;
- QStringList failureMessages;
- STATUS status;
+ QString name; //!< The name of the GTest that corresponds to this result.
+ uint time; //!< The time it took to run this test (or suite of tests).
+ QStringList failureMessages; //!< The list of failure messages --unparsed.
+ STATUS status; //!< The run status of the unit test \see
GTestResults::STATUS
public:
GTestResults(QString name);
=======================================
--- /trunk/src/GTestExecutable.cpp Sat Aug 7 11:11:45 2010
+++ /trunk/src/GTestExecutable.cpp Tue Aug 10 15:48:07 2010
@@ -21,6 +21,12 @@
#include <QFile>
#include <QMessageBox>
+/*! \brief Constructor
+ *
+ * \param parent The parent QObject.
+ * \param filePath The path to the executable file.
+ * This is validated by a getState() call.
+ */
GTestExecutable::GTestExecutable(QObject* parent, QString filePath)
: GTestSuite(parent, filePath), state(VALID), processLock(),
outputLock(), gtest(0), standardOutput(), standardError(),
@@ -29,18 +35,27 @@
getState();
}
-GTestExecutable::GTestExecutable(const GTestExecutable& other)
-: GTestSuite(other.parent(), other.name), state(other.state),
- processLock(), outputLock(), gtest(0), standardOutput(),
- standardError(), listing(), testsToRun(), runOnSignal(false)
-{
- getState();
-}
-
+/*! \brief Destructor
+ *
+ * Deletes the process handle to the executable file.
+ */
GTestExecutable::~GTestExecutable() {
-
+ if(gtest)
+ delete gtest;
}
+/*! \brief Produces a listing of the unit tests available from this
executable.
+ *
+ * The function produces a listing of all unit tests provided by the
executable
+ * located at the filePath 'name'. Since QProcess allows us to execute the
+ * executable in another thread, we have an asynchronous return the this
object.
+ * This allows the runner to continue calling produceListing() on other
+ * GTestExecutable objects while the QProcess retrieves the result.
+ * A caller can determine when the listing is ready by connecting a slot to
+ * the listingReady() slot.
+ *
+ * \TODO TODO::check the state variable before running.
+ */
void GTestExecutable::produceListing() {
//We lock so that any attempt to try to produce a listing
//or run a test will block until we're done with what we're
@@ -57,6 +72,15 @@
//unlock the processLock in the parseListing slot
}
+/*! \brief Parses the listing once the QProcess has exited.
+ *
+ * This function is called after the QProcess emits its finished() signal.
+ * It first checks the exit status and if everything has gone smoothly, it
+ * processes the stdout buffer that was filled by the gtest executable.
+ * It breaks the buffer into lines which is then understood by the
GTestRunner.
+ *
+ * \TODO TODO::Have this function create the GTest / GTestSuite tree
instead of the test runner
+ */
void GTestExecutable::parseListing(int /*exitCode*/, QProcess::ExitStatus
exitStatus) {
if(exitStatus != QProcess::NormalExit) {
QMessageBox::warning((QWidget*)this->parent(),"Error Retrieving Listing",
@@ -76,6 +100,13 @@
emit listingReady(this);
}
+/*! \brief Launches a QProcess to run the gtest executable
+ *
+ * This creates a process and runs it based on the 'name' instance
+ * variable which represents the filepath of the executable.
+ *
+ * \TODO TODO::Check the state before running the test.
+ */
void GTestExecutable::runTest() {
//We lock so that any attempt to try to produce a listing
//or run a test will block until we're done with what we're
@@ -90,6 +121,11 @@
//unlock the processLock in the parseTestResults slot
}
+/*! \brief Parses the test results .xml file produced by the QProcess.
+ *
+ * This function opens the .xml file produced by the gtest process and
parses
+ * its contents. It uses the GTestParser
+ */
void GTestExecutable::parseTestResults(int exitCode, QProcess::ExitStatus
exitStatus) {
QObject::disconnect(gtest, SIGNAL(finished(int, QProcess::ExitStatus)),
this, SLOT(parseTestResults(int, QProcess::ExitStatus)));
@@ -112,6 +148,14 @@
emit testResultsReady();
}
+/*! \brief Slot that is called when stdout data is available from the
process.
+ *
+ * This function sets up the executable reader function using a lock so
that
+ * data isn't attempted to be read from both standard output and standard
+ * error simultaneously (which currently isn't supported by the QProcess
+ * class).
+ * \see GTestExecutable::readExecutableOutput()
+ */
void GTestExecutable::standardOutputAvailable() {
qDebug() << "std output available...";
outputLock.lock();
@@ -121,6 +165,14 @@
qDebug() << "List finished populating";
}
+/*! \brief Slot that is called when stderr data is available from the
process.
+ *
+ * This function sets up the executable reader function using a lock so
that
+ * data isn't attempted to be read from both standard output and standard
+ * error simultaneously (which currently isn't supported by the QProcess
+ * class).
+ * \see GTestExecutable::readExecutableOutput()
+ */
void GTestExecutable::standardErrorAvailable() {
qDebug() << "std error available...";
outputLock.lock();
@@ -130,6 +182,14 @@
qDebug() << "List finished populating";
}
+/*! \brief Reads the current readChannel data into the appropriate QBuffer.
+ *
+ * This function is called when either standard output or standard error
+ * data is available from the gtest executable process. Setup is done prior
+ * to calling this function, so that the correct buffer is populated.
+ * \see GTestExecutable::standardErrorAvailable()
+ * \see GTestExecutable::standardOutputAvailable()
+ */
void GTestExecutable::readExecutableOutput(QBuffer& standardChannel) {
//Don't expect it to be that large,
//but whatever, who doesn't have a MB
@@ -151,6 +211,12 @@
standardChannel.close();
}
+/*! \brief Slot to be called when the QProcess has finished execution.
+ *
+ * This function is called after a QProcess has finished either generating
+ * a listing, or running the tests in the gtest executable. It populates
+ * the exit statuses which can be subsequently checked by the test runner.
+ */
void GTestExecutable::executableFinished(int exitCode,
QProcess::ExitStatus exitStatus) {
qDebug() << "exe finished";
QObject::disconnect(gtest, SIGNAL(readyReadStandardOutput()),
@@ -167,6 +233,11 @@
gtest = 0;
}
+/*! \brief Retrieves the state of the executable.
+ *
+ * \return The state of the executable (one of VALID, FILE_NOT_FOUND,
+ * or INSUFFICIENT_PRIVILEGES).
+ */
GTestExecutable::STATE GTestExecutable::getState() {
state = VALID;
QFile file(name);