PageRenderTime 65ms CodeModel.GetById 26ms RepoModel.GetById 0ms app.codeStats 0ms

/tools/NUnit/doc/exception.html

https://github.com/oyvindkinsey/dotnetopenid
HTML | 316 lines | 251 code | 57 blank | 8 comment | 0 complexity | ab11d6741f2af7a361bbe00dd6e795c5 MD5 | raw file
  1. <!-- saved from url=(0014)about:internet --><!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
  2. <html>
  3. <!-- Standard Head Part -->
  4. <head>
  5. <title>NUnit - Exception</title>
  6. <meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
  7. <meta http-equiv="Content-Language" content="en-US">
  8. <link rel="stylesheet" type="text/css" href="nunit.css">
  9. <link rel="shortcut icon" href="favicon.ico">
  10. </head>
  11. <!-- End Standard Head Part -->
  12. <body>
  13. <!-- Standard Header for NUnit.org -->
  14. <div id="header">
  15. <a id="logo" href="http://www.nunit.org"><img src="img/logo.gif" alt="NUnit.org" title="NUnit.org"></a>
  16. <div id="nav">
  17. <a href="http://www.nunit.org">NUnit</a>
  18. <a class="active" href="index.html">Documentation</a>
  19. </div>
  20. </div>
  21. <!-- End of Header -->
  22. <div id="content">
  23. <script language="JavaScript" src="codeFuncs.js" ></script> <!-- Do it this way for IE -->
  24. <h3>ExpectedExceptionAttribute (NUnit 2.0 plus Updates)</h3>
  25. <p>This is the way to specify that the execution of a test will throw an
  26. exception. This attribute has a number of positional and
  27. named parameters, which we will discuss in separate sections
  28. according to the purpose they serve.</p>
  29. <h4>Specifying the Expected Exception Type</h4>
  30. <p>The original attribute, introduced with NUnit 2.0 took a single
  31. argument giving the exact type of the expected exception. For example...</p>
  32. <div class="code"><pre>[ExpectedException( typeof( ArgumentException ) )]
  33. public void TestMethod()
  34. {
  35. ...</pre></div>
  36. <p>Beginning with NUnit 2.2.4, it became possible to specify the type
  37. of exception as a string, avoiding the need for a reference to the
  38. defining assembly...</p>
  39. <div class="code"><pre>[ExpectedException( "System.ArgumentException" ) )]
  40. public void TestMethod()
  41. {
  42. ...</pre></div>
  43. <p>The above two examples function identically: the test only succeeds if a
  44. System.Argument exception is thrown.</p>
  45. <h4>Specifying the Expected Message</h4>
  46. <p>NUnit 2.1 introduced a constructor with a second argument, specifying the
  47. exact text of the message property of the exception. After NUnit 2.2.4, the
  48. same extension was made to the constructor taking a string argument. With
  49. NUnit 2.4, these arguments are marked obsolete, and a named parameter
  50. is provided instead...</p>
  51. <div class="code" style="width: 44em"><pre>// Obsolete form:
  52. [ExpectedException( typeof( ArgumentException ), "expected message" )]
  53. [ExpectedException( "System.ArgumentException", "expected message" )]
  54. // Prefered form:
  55. [ExpectedException( typeof( ArgumentException ), ExpectedMessage="expected message" )]
  56. [ExpectedException( "System.ArgumentException", ExpectedMessage="expected message" )]</pre></div>
  57. <p>With NUnit 2.4, it is possible to specify additional tests on the
  58. exception message, beyond a simple exact match. This is done using the
  59. MatchType named parameter, whose argument is an enumeration, defined as
  60. follows:</p>
  61. <div class="code">
  62. <pre>public enum MessageMatch
  63. {
  64. /// Expect an exact match
  65. Exact,
  66. /// Expect a message containing the parameter string
  67. Contains,
  68. /// Match the regular expression provided as a parameter
  69. Regex,
  70. /// Expect a message starting with the parameter string
  71. StartsWith
  72. }</pre></div>
  73. <p>The following example is for a test that passes only if an ArgumentException
  74. with a message containing "unspecified" is received.</p>
  75. <div class="code" style="width: 57em">
  76. <pre>[ExpectedException( typeof( ArgumentException), ExpectedMessage="unspecified", MatchType=MessageMatch.Contains )]
  77. public void TestMethod()
  78. {
  79. ...</pre></div>
  80. <p>If MatchType is not specified, an exact match is used as before.</p>
  81. <h4>Specifying a Custom Error Message</h4>
  82. <p>With NUnit 2.4, it is possible to specify a custom message to be
  83. displayed if the ExpectedException attribute is not satisfied. This
  84. is done through the UserMessage named parameter...</p>
  85. <div class="code" style="width: 41em">
  86. <pre>[ExpectedException( typeof( ArgumentException ), UserMessage="Custom message" )]
  87. public void TestMethod()
  88. {
  89. ...</pre>
  90. </div>
  91. <h4>Handling the Exception in Code</h4>
  92. <p>If the processing required for an exception is too complex to express
  93. in the attribute declaration, the normal practice is to process it in the
  94. test code using a try/catch block. As an alternative, NUnit 2.4 allows
  95. designating a method that will be called to process the exception. This
  96. is particularly useful when multiple exceptions need to be processed
  97. in the same way.</p>
  98. <p>An common exception handler may be designated by implementing the
  99. <b>IExpectExceptionInterface</b>, which is defined as follows...</p>
  100. <div class="code">
  101. <pre>public interface IExpectException
  102. {
  103. void HandleException( System.Exception ex );
  104. }</pre>
  105. </div>
  106. <p>The exception handler is only called for methods marked with
  107. the <b>ExpectedException</b> attribute. If all checks - including
  108. the type of the exception - are to be performed in code, the
  109. attribute may be specified without any arguments in order to
  110. indicate that an exception is expected.</p>
  111. <p>An handler may be designated for a particular method
  112. using the <b>Handler</b> named parameter.</p>
  113. <div class="code"><pre>[ExpectedException( Handler="HandlerMethod" )]
  114. public void TestMethod()
  115. {
  116. ...
  117. }
  118. public void HandlerMethod( System.Exception ex )
  119. {
  120. ...
  121. }</pre></div>
  122. <p>This technique may be
  123. used without implementing <b>IExpectException</b> or in
  124. combination with it. In the latter case, the designated handler
  125. applies to any method that specifies it, while the normal
  126. exception handler applies to any other methods that specify
  127. an <b>ExpectedException</b>.</p>
  128. <p>However it is specified, the handler method should examine the exception and
  129. <b>Assert</b> on whatever properties are relevant. Any resulting failure message
  130. will then be consistent in format with other assertions performed in the tests.</p>
  131. <h4>Example:</h4>
  132. <div class="code">
  133. <div class="langFilter">
  134. <a href="javascript:Show('DD1')" onmouseover="Show('DD1')"><img src="img/langFilter.gif" width="14" height="14" alt="Language Filter"></a>
  135. <div id="DD1" class="dropdown" style="display: none" onclick="Hide('DD1')">
  136. <a href="javascript:ShowCS()">C#</a><br>
  137. <a href="javascript:ShowVB()">VB</a><br>
  138. <a href="javascript:ShowMC()">C++</a><br>
  139. </div>
  140. </div>
  141. <pre class="cs">namespace NUnit.Tests
  142. {
  143. using System;
  144. using NUnit.Framework;
  145. [TestFixture]
  146. public class SuccessTests
  147. {
  148. [Test]
  149. [ExpectedException(typeof(InvalidOperationException))]
  150. public void ExpectAnExceptionByType()
  151. { /* ... */ }
  152. [Test]
  153. [ExpectedException("System.InvalidOperationException")]
  154. public void ExpectAnExceptionByName()
  155. { /* ... */ }
  156. }
  157. }
  158. </pre>
  159. <pre class="vb">Imports System
  160. Imports Nunit.Framework
  161. Namespace Nunit.Tests
  162. &lt;TestFixture()&gt; Public Class SuccessTests
  163. &lt;Test(), ExpectedException(GetType(Exception))&gt;
  164. Public Sub ExpectAnExceptionByType()
  165. &#39; ...
  166. End Sub
  167. &lt;TestFixture()&gt; Public Class SuccessTests
  168. &lt;Test(), ExpectedException("System.Exception")&gt;
  169. Public Sub ExpectAnExceptionByName()
  170. &#39; ...
  171. End Sub
  172. End Class
  173. End Namespace
  174. </pre>
  175. <pre class="mc">#using &lt;Nunit.Framework.dll&gt;
  176. using namespace System;
  177. using namespace NUnit::Framework;
  178. namespace NUnitTests
  179. {
  180. [TestFixture]
  181. public __gc class SuccessTests
  182. {
  183. [Test]
  184. [ExpectedException(__typeof(InvalidOperationException))]
  185. void ExpectAnExceptionByType();
  186. [Test]
  187. [ExpectedException(S"SystemInvalidOperationException")]
  188. void ExpectAnExceptionByName();
  189. };
  190. }
  191. #include &quot;cppsample.h&quot;
  192. namespace NUnitTests {
  193. // ...
  194. }
  195. </pre>
  196. </div>
  197. </div>
  198. <!-- Submenu -->
  199. <div id="subnav">
  200. <ul>
  201. <li><a href="index.html">NUnit 2.5.9</a></li>
  202. <ul>
  203. <li><a href="getStarted.html">Getting&nbsp;Started</a></li>
  204. <li><a href="assertions.html">Assertions</a></li>
  205. <li><a href="constraintModel.html">Constraints</a></li>
  206. <li><a href="attributes.html">Attributes</a></li>
  207. <ul>
  208. <li><a href="category.html">Category</a></li>
  209. <li><a href="combinatorial.html">Combinatorial</a></li>
  210. <li><a href="culture.html">Culture</a></li>
  211. <li><a href="datapoint.html">Datapoint(s)</a></li>
  212. <li><a href="description.html">Description</a></li>
  213. <li id="current"><a href="exception.html">Exception</a></li>
  214. <li><a href="explicit.html">Explicit</a></li>
  215. <li><a href="ignore.html">Ignore</a></li>
  216. <li><a href="maxtime.html">Maxtime</a></li>
  217. <li><a href="pairwise.html">Pairwise</a></li>
  218. <li><a href="platform.html">Platform</a></li>
  219. <li><a href="property.html">Property</a></li>
  220. <li><a href="random.html">Random</a></li>
  221. <li><a href="range.html">Range</a></li>
  222. <li><a href="repeat.html">Repeat</a></li>
  223. <li><a href="requiredAddin.html">RequiredAddin</a></li>
  224. <li><a href="requiresMTA.html">Requires&nbsp;MTA</a></li>
  225. <li><a href="requiresSTA.html">Requires&nbsp;STA</a></li>
  226. <li><a href="requiresThread.html">Requires&nbsp;Thread</a></li>
  227. <li><a href="sequential.html">Sequential</a></li>
  228. <li><a href="setCulture.html">SetCulture</a></li>
  229. <li><a href="setup.html">Setup</a></li>
  230. <li><a href="setupFixture.html">SetupFixture</a></li>
  231. <li><a href="suite.html">Suite</a></li>
  232. <li><a href="teardown.html">Teardown</a></li>
  233. <li><a href="test.html">Test</a></li>
  234. <li><a href="testCase.html">TestCase</a></li>
  235. <li><a href="testCaseSource.html">TestCaseSource</a></li>
  236. <li><a href="testFixture.html">TestFixture</a></li>
  237. <li><a href="fixtureSetup.html">TestFixtureSetUp</a></li>
  238. <li><a href="fixtureTeardown.html">TestFixtureTearDown</a></li>
  239. <li><a href="theory.html">Theory</a></li>
  240. <li><a href="timeout.html">Timeout</a></li>
  241. <li><a href="values.html">Values</a></li>
  242. <li><a href="valueSource.html">ValueSource</a></li>
  243. </ul>
  244. <li><a href="runningTests.html">Running&nbsp;Tests</a></li>
  245. <li><a href="extensibility.html">Extensibility</a></li>
  246. <li><a href="releaseNotes.html">Release&nbsp;Notes</a></li>
  247. <li><a href="samples.html">Samples</a></li>
  248. <li><a href="license.html">License</a></li>
  249. </ul>
  250. </ul>
  251. </div>
  252. <!-- End of Submenu -->
  253. <!-- Standard Footer for NUnit.org -->
  254. <div id="footer">
  255. Copyright &copy; 2010 Charlie Poole. All Rights Reserved.
  256. </div>
  257. <!-- End of Footer -->
  258. </body>
  259. </html>