veritas/test.h

   1 /* KDevelop xUnit plugin
   2  *
   3  * Copyright 2006 Ernst Huber <qxrunner@systest.ch>
   4  * Copyright 2008 Manuel Breugelmans <mbr.nxi@gmail.com>
   5  *
   6  * This program is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU General Public License
   8  * as published by the Free Software Foundation; either version 2
   9  * of the License, or (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License
  17  * along with this program; if not, write to the Free Software
  18  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19  * 02110-1301, USA.
  20  */
  21
  22 #ifndef VERITAS_TEST_H
  23 #define VERITAS_TEST_H
  24
  25 #include "veritas/testresult.h"
  26 #include "veritas/veritasexport.h"
  27
  28 #include <QtCore/QMap>
  29 #include <QtCore/QList>
  30 #include <QtCore/QVariant>
  31 #include <QtCore/QStringList>
  32 #include <QtCore/QModelIndex>
  33
  34 class QAbstractItemModel;
  35
  36 namespace Veritas
  37 {
  38
  39 /*!
  40  * Prime class, represents a single test entity in a
  41  * test tree. Also used as data for the RunnerModel.
  42  * It is not intended to be used directly, but must
  43  * be subclassed. Concrete test runner implementations
  44  * can introduce structure in this test tree, but this
  45  * is not a must.
  46  *
  47  * Test loosely implements the Composite pattern.
  48  *
  49  * eg
  50  * TestSuite
  51  *   TestCase
  52  *      TestCommand
  53  *
  54  * Subclasses must reimplement the abstract run() method to do useful
  55  * application specific work.
  56  *
  57  */
  58 // TODO Factually there are 3 kinds of tests
  59 //        -> aggregates without associated executable
  60 //        -> aggregates with exe
  61 //        -> leaf tests.
  62 //      This should be reflected in the class hierarchy.
  63 class VERITAS_EXPORT Test : public QObject
  64 {
  65 Q_OBJECT
  66 Q_PROPERTY(bool verboseToggle READ needVerboseToggle WRITE setVerboseToggle)
  67 Q_PROPERTY(bool selectionToggle READ needSelectionToggle WRITE setSelectionToggle)
  68
  69 public Q_SLOTS:
  70
  71     /*! Implement this in a subclass. Default to doing nada. */
  72     virtual int run();
  73
  74 public: // Operations
  75
  76     bool needVerboseToggle() const;
  77     void setVerboseToggle(bool);
  78     bool needSelectionToggle() const;
  79     void setSelectionToggle(bool);
  80
  81     /*! Factory method that constructs a blank root test. Always use
  82      *  this method to construct test-tree roots. */
  83     static Test* createRoot();
  84
  85     /*!
  86      * Constructs a test item with the given \a parent and the
  87      * \a data associated with each column. Ensures that number of
  88      * columns equals number of columns in \a parent. Initial result
  89      * is set to Veritas::NoResult.
  90      *
  91      * TODO should be removed
  92      */
  93     explicit Test(const QList<QVariant>& data, Test* parent = 0);
  94
  95     explicit Test(const QString& name, Test* parent = 0);
  96     virtual ~Test();
  97
  98     /*! Returns false if this test's run method should not be executed.
  99         eg because it is a test container (suite).
 100         Implement this in a subclass. Default to not run. */
 101     virtual bool shouldRun() const;
 102
 103     /*! Performs a hard stop if test was running, to be implemented by
 104      *  concrete tests. */
 105     virtual void kill();
 106
 107     /*! Identifies this test. Also shown in the runnerview-tree */
 108     QString name() const;
 109
 110     /*! The test that owns this one.
 111      * Eg a suite can be parent of a case */
 112     Test* parent() const;
 113
 114     /*! Append a child test */
 115     void addChild(Test* child);
 116
 117     /*! Retrieve the row-th child */
 118     Test* child(int row) const;
 119
 120     /*! Find the (first) direct child with the specified name. */
 121     Test* childNamed(const QString& name) const;
 122
 123     /*! The number of children */
 124     int childCount() const;
 125
 126     /*! Reports the item's location within its parent's list */
 127     int row() const; // whats a better name for this?
 128
 129     /*! Fetch all leafs of this test in the test tree. */
 130     QList<Test*> leafs() const;
 131
 132     /*! The overall state of the test.
 133      * This can be NotRun, RunSuccess, RunError (among others) */
 134     TestState state() const;
 135     void setResult(TestResult* res);
 136     TestResult* result() const;
 137
 138     void signalStarted();
 139     void signalFinished();
 140
 141     /*! Contains methods that are only to be used inside the library.
 142      *  This nested class is not exported nor is the header installed.
 143      *  Sole purpose is to hide stuff from the outside. */
 144     class Internal;
 145     Internal* internal();
 146
 147 Q_SIGNALS:
 148     /*! Implementor needs to emit this when an aggregate
 149      *  Test completed executing its children */
 150     void executionFinished();
 151
 152     /*! Implementor needs to emit this when execution
 153      * of a leaf test commences. */
 154     void started(QModelIndex);
 155
 156     /*! Implementor needs to emit this when a leaf test
 157      * finished. */
 158     void finished(QModelIndex);
 159
 160 private:
 161     friend class Internal;
 162     Internal* const d;
 163
 164     // Copy and assignment not supported.
 165     Test(const Test&);
 166     Test& operator=(const Test&);
 167 };
 168
 169 } // namespace
 170
 171 #endif // VERITAS_TEST_H