PageRenderTime 23ms CodeModel.GetById 25ms RepoModel.GetById 1ms 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. 

  2. <html>
    3. 

  3. <!-- Standard Head Part -->
    4. 

  4. <head>
    5. 

  5. <title>NUnit - Exception</title>
    6. 

  6. <meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
    7. 

  7. <meta http-equiv="Content-Language" content="en-US">
    8. 

  8. <link rel="stylesheet" type="text/css" href="nunit.css">
    9. 

  9. <link rel="shortcut icon" href="favicon.ico">
    10. 

  10. </head>
    11. 

  11. <!-- End Standard Head Part -->
    12. 

  12. 

  13. <body>
    14. 

  14. 

  15. <!-- Standard Header for NUnit.org -->
    16. 

  16. <div id="header">
    17. 

  17.   <a id="logo" href="http://www.nunit.org"><img src="img/logo.gif" alt="NUnit.org" title="NUnit.org"></a>
    18. 

  18.   <div id="nav">
    19. 

  19.     <a href="http://www.nunit.org">NUnit</a>
    20. 

  20.     <a class="active" href="index.html">Documentation</a>
    21. 

  21.   </div>
    22. 

  22. </div>
    23. 

  23. <!-- End of Header -->
    24. 

  24. 

  25. <div id="content">
    26. 

  26. 

  27. <script language="JavaScript" src="codeFuncs.js" ></script> <!-- Do it this way for IE -->
    28. 

  28. 

  29. <h3>ExpectedExceptionAttribute (NUnit 2.0 plus Updates)</h3>
    30. 

  30. 

  31. <p>This is the way to specify that the execution of a test will throw an 
    32. 

  32. 	exception. This attribute has a number of positional and
    33. 

  33. 	named parameters, which we will discuss in separate sections
    34. 

  34. 	according to the purpose they serve.</p>
    35. 

  35. 	
    36. 

  36. <h4>Specifying the Expected Exception Type</h4>
    37. 

  37. 

  38. <p>The original attribute, introduced with NUnit 2.0 took a single
    39. 

  39. argument giving the exact type of the expected exception. For example...</p>
    40. 

  40. 

  41. 

  42. <div class="code"><pre>[ExpectedException( typeof( ArgumentException ) )]
    43. 

  43. public void TestMethod()
    44. 

  44. {
    45. 

  45. ...</pre></div>
    46. 

  46. 

  47. <p>Beginning with NUnit 2.2.4, it became possible to specify the type
    48. 

  48. of exception as a string, avoiding the need for a reference to the
    49. 

  49. defining assembly...</p>
    50. 

  50. 

  51. <div class="code"><pre>[ExpectedException( "System.ArgumentException" ) )]
    52. 

  52. public void TestMethod()
    53. 

  53. {
    54. 

  54. ...</pre></div>
    55. 

  55. 

  56. <p>The above two examples function identically: the test only succeeds if a
    57. 

  57. System.Argument exception is thrown.</p>
    58. 

  58. 

  59. <h4>Specifying the Expected Message</h4>
    60. 

  60. 

  61. <p>NUnit 2.1 introduced a constructor with a second argument, specifying the
    62. 

  62. exact text of the message property of the exception. After NUnit 2.2.4, the
    63. 

  63. same extension was made to the constructor taking a string argument. With
    64. 

  64. NUnit 2.4, these arguments are marked obsolete, and a named parameter
    65. 

  65. is provided instead...</p>
    66. 

  66. 

  67. <div class="code" style="width: 44em"><pre>// Obsolete form:
    68. 

  68. [ExpectedException( typeof( ArgumentException ), "expected message" )]
    69. 

  69. [ExpectedException( "System.ArgumentException", "expected message" )]
    70. 

  70. 

  71. // Prefered form:
    72. 

  72. [ExpectedException( typeof( ArgumentException ), ExpectedMessage="expected message" )]
    73. 

  73. [ExpectedException( "System.ArgumentException", ExpectedMessage="expected message" )]</pre></div>
    74. 

  74. 

  75. <p>With NUnit 2.4, it is possible to specify additional tests on the
    76. 

  76. exception message, beyond a simple exact match. This is done using the 
    77. 

  77. MatchType named parameter, whose argument is an enumeration, defined as
    78. 

  78. follows:</p>
    79. 

  79.    
    80. 

  80. <div class="code">
    81. 

  81. <pre>public enum MessageMatch
    82. 

  82. {
    83. 

  83.     /// Expect an exact match
    84. 

  84.     Exact,	
    85. 

  85.     /// Expect a message containing the parameter string
    86. 

  86.     Contains,
    87. 

  87.     /// Match the regular expression provided as a parameter
    88. 

  88.     Regex,
    89. 

  89.     /// Expect a message starting with the parameter string
    90. 

  90.     StartsWith
    91. 

  91. }</pre></div>
    92. 

  92. 

  93. <p>The following example is for a test that passes only if an ArgumentException
    94. 

  94. with a message containing "unspecified" is received.</p>
    95. 

  95. 

  96. <div class="code" style="width: 57em">
    97. 

  97. <pre>[ExpectedException( typeof( ArgumentException), ExpectedMessage="unspecified", MatchType=MessageMatch.Contains )]
    98. 

  98. public void TestMethod()
    99. 

  99. {
    100. 

  100. ...</pre></div>
    101. 

  101. 

  102. <p>If MatchType is not specified, an exact match is used as before.</p>
    103. 

  103. 

  104. <h4>Specifying a Custom Error Message</h4>
    105. 

  105. 

  106. <p>With NUnit 2.4, it is possible to specify a custom message to be
    107. 

  107. displayed if the ExpectedException attribute is not satisfied. This
    108. 

  108. is done through the UserMessage named parameter...</p>
    109. 

  109. 

  110. <div class="code" style="width: 41em">
    111. 

  111. <pre>[ExpectedException( typeof( ArgumentException ), UserMessage="Custom message" )]
    112. 

  112. public void TestMethod()
    113. 

  113. {
    114. 

  114. ...</pre>
    115. 

  115. </div>
    116. 

  116. 

  117. <h4>Handling the Exception in Code</h4>
    118. 

  118. 

  119. <p>If the processing required for an exception is too complex to express
    120. 

  120. in the attribute declaration, the normal practice is to process it in the
    121. 

  121. test code using a try/catch block. As an alternative, NUnit 2.4 allows
    122. 

  122. designating a method that will be called to process the exception. This
    123. 

  123. is particularly useful when multiple exceptions need to be processed
    124. 

  124. in the same way.</p>
    125. 

  125. 

  126. <p>An common exception handler may be designated by implementing the
    127. 

  127. <b>IExpectExceptionInterface</b>, which is defined as follows...</p>
    128. 

  128. 

  129. <div class="code">
    130. 

  130. <pre>public interface IExpectException
    131. 

  131. {
    132. 

  132.     void HandleException( System.Exception ex );
    133. 

  133. }</pre>
    134. 

  134. </div>
    135. 

  135. 

  136. <p>The exception handler is only called for methods marked with
    137. 

  137. the <b>ExpectedException</b> attribute. If all checks - including
    138. 

  138. the type of the exception - are to be performed in code, the
    139. 

  139. attribute may be specified without any arguments in order to
    140. 

  140. indicate that an exception is expected.</p>
    141. 

  141. 

  142. <p>An handler may be designated for a particular method
    143. 

  143. using the <b>Handler</b> named parameter.</p>
    144. 

  144. 

  145. <div class="code"><pre>[ExpectedException( Handler="HandlerMethod" )]
    146. 

  146. public void TestMethod()
    147. 

  147. {
    148. 

  148. ...
    149. 

  149. }
    150. 

  150. 

  151. public void HandlerMethod( System.Exception ex )
    152. 

  152. {
    153. 

  153. ...
    154. 

  154. }</pre></div>
    155. 

  155. 

  156. <p>This technique may be
    157. 

  157. used without implementing <b>IExpectException</b> or in
    158. 

  158. combination with it. In the latter case, the designated handler
    159. 

  159. applies to any method that specifies it, while the normal
    160. 

  160. exception handler applies to any other methods that specify
    161. 

  161. an <b>ExpectedException</b>.</p>
    162. 

  162. 

  163. <p>However it is specified, the handler method should examine the exception and 
    164. 

  164. <b>Assert</b> on whatever properties are relevant. Any resulting failure message 
    165. 

  165. will then be consistent in format with other assertions performed in the tests.</p>
    166. 

  166. 

  167. 

  168. <h4>Example:</h4>
    169. 

  169. 

  170. <div class="code">
    171. 

  171. 

  172. <div class="langFilter">
    173. 

  173. 	<a href="javascript:Show('DD1')" onmouseover="Show('DD1')"><img src="img/langFilter.gif" width="14" height="14" alt="Language Filter"></a>
    174. 

  174. 	<div id="DD1" class="dropdown" style="display: none" onclick="Hide('DD1')">
    175. 

  175. 		<a href="javascript:ShowCS()">C#</a><br>
    176. 

  176. 		<a href="javascript:ShowVB()">VB</a><br>
    177. 

  177. 		<a href="javascript:ShowMC()">C++</a><br>
    178. 

  178. 	</div>
    179. 

  179. </div>
    180. 

  180. 

  181. <pre class="cs">namespace NUnit.Tests
    182. 

  182. {
    183. 

  183.   using System;
    184. 

  184.   using NUnit.Framework;
    185. 

  185. 

  186.   [TestFixture]
    187. 

  187.   public class SuccessTests
    188. 

  188.   {
    189. 

  189.     [Test]
    190. 

  190.     [ExpectedException(typeof(InvalidOperationException))]
    191. 

  191.     public void ExpectAnExceptionByType()
    192. 

  192.     { /* ... */ }
    193. 

  193. 

  194.     [Test]
    195. 

  195.     [ExpectedException("System.InvalidOperationException")]
    196. 

  196.     public void ExpectAnExceptionByName()
    197. 

  197.     { /* ... */ }
    198. 

  198.   }
    199. 

  199. }
    200. 

  200. </pre>
    201. 

  201. 

  202. <pre class="vb">Imports System
    203. 

  203. Imports Nunit.Framework
    204. 

  204. 

  205. Namespace Nunit.Tests
    206. 

  206. 

  207.   &lt;TestFixture()&gt; Public Class SuccessTests
    208. 

  208.     &lt;Test(), ExpectedException(GetType(Exception))&gt;
    209. 

  209.       Public Sub ExpectAnExceptionByType()
    210. 

  210.     &#39; ...
    211. 

  211.     End Sub
    212. 

  212. 

  213.   &lt;TestFixture()&gt; Public Class SuccessTests
    214. 

  214.     &lt;Test(), ExpectedException("System.Exception")&gt;
    215. 

  215.       Public Sub ExpectAnExceptionByName()
    216. 

  216.     &#39; ...
    217. 

  217.     End Sub
    218. 

  218.   End Class
    219. 

  219. End Namespace
    220. 

  220. </pre>
    221. 

  221. 

  222. <pre class="mc">#using &lt;Nunit.Framework.dll&gt;
    223. 

  223. using namespace System;
    224. 

  224. using namespace NUnit::Framework;
    225. 

  225. 

  226. namespace NUnitTests
    227. 

  227. {
    228. 

  228.   [TestFixture]
    229. 

  229.   public __gc class SuccessTests
    230. 

  230.   {
    231. 

  231.     [Test]
    232. 

  232.     [ExpectedException(__typeof(InvalidOperationException))]
    233. 

  233.     void ExpectAnExceptionByType();
    234. 

  234. 

  235.     [Test]
    236. 

  236.     [ExpectedException(S"SystemInvalidOperationException")]
    237. 

  237.     void ExpectAnExceptionByName();
    238. 

  238.   };
    239. 

  239. }
    240. 

  240. 

  241. #include &quot;cppsample.h&quot;
    242. 

  242. 

  243. namespace NUnitTests {
    244. 

  244.   // ...
    245. 

  245. }
    246. 

  246. </pre>
    247. 

  247. 

  248. </div>
    249. 

  249. 

  250. </div>
    251. 

  251. 

  252. <!-- Submenu -->
    253. 

  253. <div id="subnav">
    254. 

  254. <ul>
    255. 

  255. <li><a href="index.html">NUnit 2.5.9</a></li>
    256. 

  256. <ul>
    257. 

  257. <li><a href="getStarted.html">Getting&nbsp;Started</a></li>
    258. 

  258. <li><a href="assertions.html">Assertions</a></li>
    259. 

  259. <li><a href="constraintModel.html">Constraints</a></li>
    260. 

  260. <li><a href="attributes.html">Attributes</a></li>
    261. 

  261. <ul>
    262. 

  262. <li><a href="category.html">Category</a></li>
    263. 

  263. <li><a href="combinatorial.html">Combinatorial</a></li>
    264. 

  264. <li><a href="culture.html">Culture</a></li>
    265. 

  265. <li><a href="datapoint.html">Datapoint(s)</a></li>
    266. 

  266. <li><a href="description.html">Description</a></li>
    267. 

  267. <li id="current"><a href="exception.html">Exception</a></li>
    268. 

  268. <li><a href="explicit.html">Explicit</a></li>
    269. 

  269. <li><a href="ignore.html">Ignore</a></li>
    270. 

  270. <li><a href="maxtime.html">Maxtime</a></li>
    271. 

  271. <li><a href="pairwise.html">Pairwise</a></li>
    272. 

  272. <li><a href="platform.html">Platform</a></li>
    273. 

  273. <li><a href="property.html">Property</a></li>
    274. 

  274. <li><a href="random.html">Random</a></li>
    275. 

  275. <li><a href="range.html">Range</a></li>
    276. 

  276. <li><a href="repeat.html">Repeat</a></li>
    277. 

  277. <li><a href="requiredAddin.html">RequiredAddin</a></li>
    278. 

  278. <li><a href="requiresMTA.html">Requires&nbsp;MTA</a></li>
    279. 

  279. <li><a href="requiresSTA.html">Requires&nbsp;STA</a></li>
    280. 

  280. <li><a href="requiresThread.html">Requires&nbsp;Thread</a></li>
    281. 

  281. <li><a href="sequential.html">Sequential</a></li>
    282. 

  282. <li><a href="setCulture.html">SetCulture</a></li>
    283. 

  283. <li><a href="setup.html">Setup</a></li>
    284. 

  284. <li><a href="setupFixture.html">SetupFixture</a></li>
    285. 

  285. <li><a href="suite.html">Suite</a></li>
    286. 

  286. <li><a href="teardown.html">Teardown</a></li>
    287. 

  287. <li><a href="test.html">Test</a></li>
    288. 

  288. <li><a href="testCase.html">TestCase</a></li>
    289. 

  289. <li><a href="testCaseSource.html">TestCaseSource</a></li>
    290. 

  290. <li><a href="testFixture.html">TestFixture</a></li>
    291. 

  291. <li><a href="fixtureSetup.html">TestFixtureSetUp</a></li>
    292. 

  292. <li><a href="fixtureTeardown.html">TestFixtureTearDown</a></li>
    293. 

  293. <li><a href="theory.html">Theory</a></li>
    294. 

  294. <li><a href="timeout.html">Timeout</a></li>
    295. 

  295. <li><a href="values.html">Values</a></li>
    296. 

  296. <li><a href="valueSource.html">ValueSource</a></li>
    297. 

  297. </ul>
    298. 

  298. <li><a href="runningTests.html">Running&nbsp;Tests</a></li>
    299. 

  299. <li><a href="extensibility.html">Extensibility</a></li>
    300. 

  300. <li><a href="releaseNotes.html">Release&nbsp;Notes</a></li>
    301. 

  301. <li><a href="samples.html">Samples</a></li>
    302. 

  302. <li><a href="license.html">License</a></li>
    303. 

  303. </ul>
    304. 

  304. </ul>
    305. 

  305. </div>
    306. 

  306. <!-- End of Submenu -->
    307. 

  307. 

  308. 

  309. <!-- Standard Footer for NUnit.org -->
    310. 

  310. <div id="footer">
    311. 

  311.   Copyright &copy; 2010 Charlie Poole. All Rights Reserved.
    312. 

  312. </div>
    313. 

  313. <!-- End of Footer -->
    314. 

  314. 

  315. </body>
    316. 

  316. </html>
    317. 

  317.