diff options
Diffstat (limited to 'tools/NUnit/doc/nunitAddins.html')
| -rw-r--r-- | tools/NUnit/doc/nunitAddins.html | 331 |
1 files changed, 331 insertions, 0 deletions
diff --git a/tools/NUnit/doc/nunitAddins.html b/tools/NUnit/doc/nunitAddins.html new file mode 100644 index 0000000..35fb2dc --- /dev/null +++ b/tools/NUnit/doc/nunitAddins.html @@ -0,0 +1,331 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
+<html>
+<!-- Standard Head Part -->
+<head>
+<title>NUnit - NunitAddins</title>
+<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
+<meta http-equiv="Content-Language" content="en-US">
+<link rel="stylesheet" type="text/css" href="nunit.css">
+<link rel="shortcut icon" href="favicon.ico">
+</head>
+<!-- End Standard Head Part -->
+
+<body>
+
+<!-- Standard Header for NUnit.org -->
+<div id="header">
+ <a id="logo" href="http://www.nunit.org"><img src="img/logo.gif" alt="NUnit.org" title="NUnit.org"></a>
+ <div id="nav">
+ <a href="http://www.nunit.org">NUnit</a>
+ <a class="active" href="index.html">Documentation</a>
+ </div>
+</div>
+<!-- End of Header -->
+
+<div id="content">
+
+<h2>NUnit Addins</h2>
+
+<div style="text-align: center; margin: 2em 10%; padding: 4px 0; border: 2px solid black">
+ <h4>Preliminary documentation, subject to change.</h4>
+</div>
+
+<p>NUnit originally identified tests in the time-honored way used in many xUnit
+test frameworks. Test classes inherited from the framework's
+TestCase class. Individual test case methods were identified by having names
+starting with "test..."</p>
+
+<p>With NUnit 2.0, we introduced the use of attributes to identify both fixtures
+and test cases. Use of attributes in this way was a natural outcome of their
+presence in .NET and gave us a way of identifying tests that was completely
+independent of both inheritance and naming conventions.</p>
+
+<p>However, by moving away from an inheritance-based mechanism we no longer
+had an easy way for others to extend NUnit's internal behavior. NUnit Addins are
+intended to fill that gap, providing an mechanism to introduce new or changed
+behavior without modifying NUnit itself.</p>
+
+<h3>Extension Points, Extensions and Addins</h3>
+
+<p>NUnit provides a number of <b>Extension Points</b>, places where it is
+possible to extend its behavior. Because NUnit works with various hosts
+and uses separate AppDomains to run tests, <b>Extension Points</b> are
+categorized into three types: Core, Client and Gui. Each of these types is
+supported by a different <b>Extension Host</b>.
+
+<p>An NUnit <b>Addin</b> provides enhanced functionality through one or more
+extensions, which it installs at identified <b>Extension Points</b>. Each
+<b>Addin</b> is characterized by the types of extensions it supplies, so that
+an <b>Extension Host</b> knows whether to invoke it.</p>
+
+<blockquote>
+<p><b>Note:</b> In the current release, only Core extensions are actually
+supported. An Addin may characterize itself as a Client or Gui extension and
+will be listed as such in the <a href="addinsDialog.html">Addins Dialog</a>,
+but no other action is taken.</p>
+</blockquote>
+
+<h3>Addin Identification, Loading and Installation</h3>
+
+<p>NUnit examines all assemblies in the <b>bin/addins</b> directory, looking
+for public classes with the <b>NUnitAddinAttribute</b> and implementing the
+<b>IAddin</b> interface. It loads all those it finds as Addins.</p>
+
+<p><b>NUnitAddinAttribute</b> supports three optional named parameters: Type,
+Name and Description. Name and Description are strings representing the name
+of the extension and a description of what it does. If no name is provided,
+the name of the class is used. Type may be any one or a combination of the
+ExtensionType enum members:
+
+<pre>
+ [Flags]
+ public enum ExtensionType
+ {
+ Core=1,
+ Client=2,
+ Gui=4
+ }
+</pre>
+
+The values may be or'ed together, allowing for future Addins that require
+extensions at multiple levels of the application. If not provided, Type
+defaults to ExtensionType.Core.</p>
+
+<p>The <b>IAddin</b> interface, which must be implemented by each Addin,
+is defined as follows:</p>
+
+<pre>
+ public interface IAddin
+ {
+ bool Install( IExtensionHost host );
+ }
+</pre>
+
+<p> The <b>Install</b> method is called by each host for which the addin has
+specified an ExtensionType. The addin should check that the necessary extension
+points are available and install itself, returning true for success or false
+for failure to install. The method will be called once for each extension
+host and - for Core extensions - each time a new test domain is loaded.</p>
+
+<p>The Install method uses the <b>IExtensionHost</b> interface to locate
+extension points. It is defined as follows:</p>
+
+<pre>
+ public interface IExtensionHost
+ {
+ IExtensionPoint[] ExtensionPoints { get; }
+ IFrameworkRegistry FrameworkRegistry{ get; }
+ IExtensionPoint GetExtensionPoint( string name );
+ }
+</pre>
+
+<p>The <b>ExtensionPoints</b> property returns an array of all extension points
+for those extensions that need the information. The <b>FrameworkRegistry</b>
+is provided for advanced extensions that emulate external test frameworks. See
+the source code for details.</p>
+
+<p>Most addins will only need to use the <b>GetExtensionPoint</b> method to
+get the interface to a particular extension point. The <b>IExtensionPoint</b>
+interface is defined as follows:</p>
+
+<pre>
+ public interface IExtensionPoint
+ {
+ string Name { get; }
+ IExtensionHost Host { get; }
+ void Install( object extension );
+ void Remove( object extension );
+ }
+</pre>
+
+<p>Once again, most addins will only need to use one method - the
+<b>Install</b> method in this case. This method passes an extension object
+to the <b>Extension Point</b> where it is installed. Generally, extensions
+do not need to remove themselves once installed, but the method is
+provided in any case.</p>
+
+<h3>Extension Point Details</h3>
+
+<p>Depending on the particular extension point, the object passed will
+need to implement one or more interfaces. The following <b>ExtensionPoints</b>
+are implemented in this release of NUnit:
+
+<ul>
+ <li><a href="#suiteBuilders">SuiteBuilders</a>
+ <li><a href="#testBuilders">TestCaseBuilders</a>
+ <li><a href="#testDecorators">TestDecorators</a>
+ <li><a href="#eventListeners">Listeners</a>
+</ul></p>
+
+<p>For examples of implementing each type of extension, see the Extensibility
+samples provided with NUnit. More complete examples are available in the
+code of NUnit itself, since NUnit uses the same mechanism internally.</p>
+
+<h4><a name="suiteBuilders">SuiteBuilders</a></h4>
+<p>
+<p>Addins use the host to access this extension point by name:
+
+<pre>
+ IExtensionPoint suiteBuilders = host.GetExtensionPoint( "SuiteBuilders" );</pre>
+
+<p>The extension object passed to Install must implement the ISuiteBuilder interface:
+
+<pre>
+ public interface ISuiteBuilder
+ {
+ bool CanBuildFrom( Type type );
+ Test BuildFrom( Type type );
+ }
+</pre>
+
+<p>The BuildFrom method should return a test fixture completely populated
+with its contained test cases.
+
+<h4><a name="testBuilders">TestCaseBuilders</a></h4>
+<p>
+<p>Addins use the host to access this extension point by name:
+
+<pre>
+ IExtensionPoint testCaseBuilders = host.GetExtensionPoint( "TestCaseBuilders" );</pre>
+
+<p>The extension object passed to Install must implement the ITestCaseBuilder interface:
+
+<pre>
+ public interface ITestCaseBuilder
+ {
+ bool CanBuildFrom( MethodInfo method );
+ Test BuildFrom( MethodInfo method );
+ }
+</pre>
+
+<p>Note that this extension point will be called for methods in any type
+of fixture. If the addin is intended to only work on methods within
+a particular type of fixture, the CanBuildFrom method must check
+the fixture type.
+
+<h4><a name="testDecorators">TestDecorators</a></h4>
+<p>
+<p>Addins use the host to access this extension point by name:
+
+<pre>
+ IExtensionPoint testDecorators = host.GetExtensionPoint( "TestDecorators" );</pre>
+
+<p>The extension object passed to Install must implement the ITestDecorator interface:
+
+<pre>
+ public interface ITestDecorator
+ {
+ Test Decorate( Test test, MemberInfo member );
+ }
+</pre>
+
+<p>The Decorator may do several things, depending on what it needs
+to accomplish:
+<ol>
+ <li>Return test unmodified
+ <li>Modify properties of the test object and return it
+ <li>Replace test with another object, either discarding the
+ original or aggregating it in the new test.
+</ol>
+
+<h4><a name="eventListeners">EventListeners</a></h4>
+<p>
+<p>Addins use the host to access this extension point by name:
+
+<pre>
+ IExtensionPoint listeners = host.GetExtensionPoint( "EventListeners" );</pre>
+
+<p>The extension object passed to Install must implement the EventListener interface:
+
+<pre>
+ public interface EventListener
+ {
+ void RunStarted( string name, int testCount );
+ void RunFinished( TestResult result );
+ void RunFinished( Exception exception );
+ void TestStarted(TestName testName);
+ void TestFinished(TestCaseResult result);
+ void SuiteStarted(TestName testName);
+ void SuiteFinished(TestSuiteResult result);
+ void UnhandledException( Exception exception );
+ void TestOutput(TestOutput testOutput);
+ }
+</pre>
+
+<p>You must provide all the methods, but the body may be empty for any
+that you have no need of.
+
+<h3>Tips for Writing Extensions</h3>
+
+<p>An Extenders Guide will be published in the future. At the moment, writing an
+extension is a bit of an adventure. Extension authors are advised to join the
+nunit-developer list and post questions and comments there.
+
+<p>For the moment, the following tips may be of assistance.
+<ul>
+<li>The <b>nunit.core.interfaces</b> assembly is intended to be stable in the future
+while the <b>nunit.core</b> assembly will change from release to release. Right now,
+both assemblies are still in flux, but extensions that depend solely on the interfaces
+assembly will have a much better chance of surviving NUnit version changes. Unfortunately,
+this is rather difficult to do without duplicating a great deal of NUnit code. Most
+of the add-in samples provided with NUnit are currently version dependent.
+
+<li>If you place the definition of a custom attribute in the same assembly as your
+add-in, then user tests are dependent on the add-in assembly. If the add-in is
+version-dependent, then the user tests will also be version-dependent. We suggest
+placing any types referenced by user tests in a separate assembly, particularly if
+your extension relies on nunit.core.
+
+<li>If using Visual Studio, set Copy Local to false for any references to nunit.core
+or nunit.core.interfaces. This is especially important if you are also building
+NUnit itself.
+
+<li>There is currently no mechanism to allow decorators to apply in a particular order.
+NUnit applies decorators in the order in which they are returned through reflection,
+which may vary among different runtimes.
+
+<li>Avoid trying to "stretch" the existing extension points to do more than they were
+intended to do. Rather, let us know what further extension points you would like to see!
+</ul>
+
+
+</div>
+
+<!-- Submenu -->
+<div id="subnav">
+<ul> +<li><a href="index.html">NUnit 2.4.7</a></li> +<ul> +<li><a href="getStarted.html">Getting Started</a></li> +<li><a href="assertions.html">Assertions</a></li> +<li><a href="attributes.html">Attributes</a></li> +<li><a href="nunit-console.html">Console Runner</a></li> +<li><a href="nunit-gui.html">Gui Runner</a></li> +<li><a href="features.html">Other Features</a></li> +<ul> +<li><a href="configFiles.html">Configuration Files</a></li> +<li><a href="multiAssembly.html">Multiple Assemblies</a></li> +<li><a href="vsSupport.html">Visual Studio Support</a></li> +<li><a href="extensibility.html">Extensibility</a></li> +<ul> +<li><a href="customAsserts.html">Custom Asserts</a></li> +<li id="current"><a href="nunitAddins.html">NUnit Addins</a></li> +</ul> +</ul> +<li><a href="releaseNotes.html">Release Notes</a></li> +<li><a href="samples.html">Samples</a></li> +<li><a href="license.html">License</a></li> +</ul> +</ul> +</div>
+<!-- End of Submenu -->
+
+
+<!-- Standard Footer for NUnit.org -->
+<div id="footer">
+ Copyright © 2008 Charlie Poole. All Rights Reserved.
+</div>
+<!-- End of Footer -->
+
+</body>
+</html>
|