nunit24/NUnitCore/interfaces/TestRunner.cs

   1 // ****************************************************************
   2 // This is free software licensed under the NUnit license. You
   3 // may obtain a copy of the license as well as information regarding
   4 // copyright ownership at http://nunit.org/?p=license&r=2.4.
   5 // ****************************************************************
   6
   7 using System;
   8 using System.Collections;
   9 using System.IO;
  10
  11 namespace NUnit.Core
  12 {
  13         /// <summary>
  14         /// The TestRunner Interface allows client code, such as the NUnit console and
  15         /// gui runners, to load and run tests. This is the lowest level interface generally
  16         /// supported for running tests and is implemented by the RemoteTestRunner class in
  17         /// the NUnit core as well as by other classes running on the client side.
  18         ///
  19         /// The Load method is used to load a suite of tests from one or more
  20         /// assemblies, returning a tree of TestNodes to the caller.
  21         ///
  22         /// The CountTestCases family of methods returns the number of test cases in the
  23         /// loaded suite, either in its entirety or by using a filter to count a subset of tests.
  24         ///
  25         /// The Run family of methods performs a test run synchronously, returning a TestResult
  26         /// or TestResult[] to the caller. If provided, an EventListener interface will be
  27         /// notified of significant events in the running of the tests. A filter may be used
  28     /// to run a subset of the tests.
  29     ///
  30     /// BeginRun and EndRun provide a simplified form of the asynchronous invocation
  31         /// pattern used in many places within the .NET framework. Because the current
  32         /// implementation allows only one run to be in process at a time, an IAsyncResult
  33         /// is not used at this time.
  34     ///
  35     /// Methods to cancel a run and to wait for a run to complete are also provided. The
  36     /// result of the last run may be obtained by querying the TestResult property.
  37     ///
  38     /// </summary>
  39         public interface TestRunner
  40         {
  41                 #region Properties
  42                 /// <summary>
  43                 /// TestRunners are identified by an ID. So long as there
  44                 /// is only one test runner or a single chain of test runners,
  45                 /// the default id of 0 may be used. However, any client that
  46                 /// creates multiple runners must ensure that each one has a
  47                 /// unique ID in order to locate and run specific tests.
  48                 /// </summary>
  49                 int ID
  50                 {
  51                         get;
  52                 }
  53
  54                 /// <summary>
  55                 /// IsTestRunning indicates whether a test is in progress. To retrieve the
  56                 /// results from an asynchronous test run, wait till IsTestRunning is false.
  57                 /// </summary>
  58                 bool Running
  59                 {
  60                         get;
  61                 }
  62
  63                 /// <summary>
  64                 /// Returns information about loaded assemblies
  65                 /// </summary>
  66                 IList AssemblyInfo
  67                 {
  68                         get;
  69                 }
  70
  71                 /// <summary>
  72                 /// The loaded test, converted to a tree of TestNodes so they can be
  73                 /// serialized and marshalled to a remote client.
  74                 /// </summary>
  75                 ITest Test
  76                 {
  77                         get;
  78                 }
  79
  80                 /// <summary>
  81                 /// Result of the last test run.
  82                 /// </summary>
  83                 TestResult TestResult
  84                 {
  85                         get;
  86                 }
  87                 #endregion
  88
  89                 #region Load and Unload Methods
  90                 /// <summary>
  91                 /// Load the assemblies in a test package
  92                 /// </summary>
  93                 /// <param name="package">The test package to be loaded</param>
  94                 /// <returns>True if the tests were loaded successfully, otherwise false</returns>
  95                 bool Load( TestPackage package );
  96
  97                 /// <summary>
  98                 /// Unload all tests previously loaded
  99                 /// </summary>
 100                 void Unload();
 101                 #endregion
 102
 103                 #region CountTestCases Methods
 104                 /// <summary>
 105                 /// Count Test Cases using a filter
 106                 /// </summary>
 107                 /// <param name="filter">The filter to apply</param>
 108                 /// <returns>The number of test cases found</returns>
 109                 int CountTestCases(ITestFilter filter );
 110                 #endregion
 111
 112                 #region Run Methods
 113                 /// <summary>
 114                 /// Run all loaded tests and return a test result. The test is run synchronously,
 115                 /// and the listener interface is notified as it progresses.
 116                 /// </summary>
 117                 /// <param name="listener">Interface to receive EventListener notifications.</param>
 118                 TestResult Run(NUnit.Core.EventListener listener);
 119
 120                 /// <summary>
 121                 /// Run selected tests and return a test result. The test is run synchronously,
 122                 /// and the listener interface is notified as it progresses.
 123                 /// </summary>
 124                 /// <param name="listener">Interface to receive EventListener notifications.</param>
 125                 /// <param name="filter">The filter to apply when running the tests</param>
 126                 TestResult Run(NUnit.Core.EventListener listener, ITestFilter filter);
 127
 128                 /// <summary>
 129                 /// Start a run of all loaded tests. The tests are run aynchronously and the
 130                 /// listener interface is notified as it progresses.
 131                 /// </summary>
 132                 /// <param name="listener">Interface to receive EventListener notifications.</param>
 133                 void BeginRun(NUnit.Core.EventListener listener);
 134
 135                 /// <summary>
 136                 /// Start a run of selected tests. The tests are run aynchronously and the
 137                 /// listener interface is notified as it progresses.
 138                 /// </summary>
 139                 /// <param name="listener">Interface to receive EventListener notifications.</param>
 140                 /// <param name="filter">The filter to apply when running the tests</param>
 141                 void BeginRun(NUnit.Core.EventListener listener, ITestFilter filter);
 142
 143                 /// <summary>
 144                 /// Wait for an asynchronous run to complete and return the result.
 145                 /// </summary>
 146                 /// <returns>A TestResult for the entire run</returns>
 147                 TestResult EndRun();
 148
 149                 /// <summary>
 150                 ///  Cancel the test run that is in progress. For a synchronous run,
 151                 ///  a client wanting to call this must create a separate run thread.
 152                 /// </summary>
 153                 void CancelRun();
 154
 155                 /// <summary>
 156                 /// Wait for the test run in progress to complete. For a synchronous run,
 157                 /// a client wanting to call this must create a separate run thread. In
 158                 /// particular, a gui client calling this method is likely to hang, since
 159                 /// events will not be able to invoke methods on the gui thread.
 160                 /// </summary>
 161                 void Wait();
 162                 #endregion
 163         }
 164 }
 165