source: BMXNET_RPMS_dotNET_UTILITIES-BMX/branch/IHS BMX Framework/lib/NUnit/NUnit-2.5.10.11092/doc/testCaseSource.html@ 1146

Last change on this file since 1146 was 1146, checked in by Sam Habiel, 13 years ago

Initial Import of BMX4
File size: 11.8 KB
Line 
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 - TestCaseSource</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
13<body>
14
15<!-- Standard Header for NUnit.org -->
16<div id="header">
17 <a id="logo" href="http://www.nunit.org"><img src="img/logo.gif" alt="NUnit.org" title="NUnit.org"></a>
18 <div id="nav">
19 <a href="http://www.nunit.org">NUnit</a>
20 <a class="active" href="index.html">Documentation</a>
21 </div>
22</div>
23<!-- End of Header -->
24
25<div id="content">
26
27<script language="JavaScript" src="codeFuncs.js" ></script> <!-- Do it this way for IE -->
28
29<h3>TestCaseSourceAttribute (NUnit 2.5)</h3>
30
31<p><b>TestCaseSourceAttribute</b> is used on a parameterized test method to
32identify the property, method or field that will provide the required
33arguments. The attribute has two public constructors.
34
35<div class="code">
36<pre>
37TestCaseSourceAttribute(Type sourceType, string sourceName);
38TestCaseSourceAttribute(string sourceName);
39</pre>
40</div>
41
42<p>If <b>sourceType</b> is specified, it represents the class that provides
43the test cases. It must have a default constructor.
44
45<p>If <b>sourceType</b> is not specified, the class containing the test
46method is used. NUnit will construct it using either the default constructor
47or - if arguments are provided - the appropriate constructor for those
48arguments.
49
50<p>The <b>sourceName</b> argument represents the name of the source used
51to provide test cases. It has the following characteristics:
52<ul>
53<li>It may be a field, property or method.
54<li>It may be either an instance or a static member.
55<li>It must return an IEnumerable or a type that implements IEnumerable.
56<li>The individual items returned by the enumerator must be compatible
57 with the signature of the method on which the attribute appears.
58 The rules for this are described in the next section.
59</ul>
60
61<h3>Constructing Test Cases</h3>
62
63<p>In constructing tests, NUnit uses each item returned by
64the enumerator as follows:
65<ol>
66
67<li><p>If it is an object implementing <b>NUnit.Framework.ITestCaseData</b>,
68its properties are used to provide the test case. In NUnit 2.5, this is
69done using reflection to allow compatibility with earlier versions that
70did not implement <b>ITestCaseData</b>.
71
72<p>The following public fields or properties are used:
73 <p><dl>
74 <dt><b>Arguments</b>
75 <dd>An <b>object[]</b> representing the arguments to the method
76 <dt><b>Categories</b>
77 <dd>An IList of categories to be applied to the test case.
78 <dt><b>Description</b>
79 <dd>Sets the description property of the test
80 <dt><b>ExpectedException</b>
81 <dd>Specifies a the Type of an exception that should be thrown by this invocation
82 <dt><b>ExpectedExceptionName</b>
83 <dd>Specifies a the FullName of an exception that should be thrown by this invocation
84 <dt><b>Properties</b>
85 <dd>An IDictionary of properties to be applied to the test case.
86 Note that the values provided must be compatible with PropertiesAttribute.
87 In particular, use of custom types or enums will cause problems.
88 <dt><b>Result</b>
89 <dd>The expected result to be returned from the method, which must have
90 a compatible return type.
91 <dt><b>TestName</b>
92 <dd>Provides a name for the test. If not specified, a name is generated based on
93 the method name and the arguments provided
94 <dt><b>Ignored</b>
95 <dd>If true, the test case is ignored.
96 <dt><b>IgnoreReason</b>
97 <dd>Specifies the reason for ignoring this test case. If set to a non-empty
98 string, then the test is ignored.
99 </dl>
100
101<p>
102<li><p>If the test has a single argument and the returned value matches the type of
103that argument it is used directly.
104
105<li><p>If it is an <b>object[]</b>, its members are used to provide
106the arguments for the method, as in this example, which returns
107arguments from a named static field.
108
109<div class="code">
110<pre>[Test, TestCaseSource("DivideCases")]
111public void DivideTest(int n, int d, int q)
112{
113 Assert.AreEqual( q, n / d );
114}
115
116static object[] DivideCases =
117{
118 new object[] { 12, 3, 4 },
119 new object[] { 12, 2, 6 },
120 new object[] { 12, 4, 3 }
121};
122</pre></div>
123
124<li><p>If it is an array of some other type, NUnit can use it provided
125that the arguments to the method are all of that type. For example,
126the above code could be modified to make the three nested arrays
127of type int[].
128
129<li><p>If anything else is returned, it is used directly as the sole
130argument to the method. This allows NUnit to give an error message
131in cases where the method requires a different number arguments or
132an argument of a different type.
133This can also eliminate a bit of extra typing by the programmer,
134as in this example:
135
136<div class="code"><pre>
137static int[] EvenNumbers = new int[] { 2, 4, 6, 8 };
138
139[Test, TestCaseSource("EvenNumbers")]
140public void TestMethod(int num)
141{
142 Assert.IsTrue( num % 2 == 0 );
143}
144</pre></div>
145
146</ol>
147
148<h3>TestCaseData Class</h3>
149
150<p>Although any object implementing <b>ITestCaseData</b> may be used to
151 provide extended test case information, NUnit provides the <b>TestCaseData</b>
152 class for this purpose. The following example returns <b>TestCaseData</b>
153 instances from a data source in a separately defined class.
154
155<div class="code">
156<pre>[TestFixture]
157public class MyTests
158{
159 [Test,TestCaseSource(typeof(MyFactoryClass),"TestCases")]
160 public int DivideTest(int n, int d)
161 {
162 return n/d;
163 }
164
165 ...
166}
167
168public class MyFactoryClass
169{
170 public static IEnumerable TestCases
171 {
172 get
173 {
174 yield return new TestCaseData( 12, 3 ).Returns( 4 );
175 yield return new TestCaseData( 12, 2 ).Returns( 6 );
176 yield return new TestCaseData( 12, 4 ).Returns( 3 );
177 yield return new TestCaseData( 0, 0 )
178 .Throws(typeof(DivideByZeroException))
179 .SetName("DivideByZero")
180 .SetDescription("An exception is expected");
181 }
182 }
183}
184</div>
185
186<p>This example uses the fluent interface supported by <b>TestCaseData</b>
187to make the program more readable. The last yield statement above is equivalent to
188
189<div class="code"><pre>
190 TestCaseData data = new TestCaseData(0,0);
191 data.ExpectedException = typeof(DivideByZeroException;
192 data.TestName = "DivideByZero";
193 data.Description = "An exception is expected";
194 yield return data;
195</pre>
196</div>
197
198<p><b>TestCaseData</b> supports the following properties
199and methods, which may be appended to an instance in any order.
200
201<p>
202<dl>
203 <dt><b>.Returns</b>
204 <dd>The expected result to be returned from the method, which must have
205 a compatible return type.
206 <dt><b>.SetCategory(string)</b>
207 <dd>Applies a category to the test
208 <dt><b>.SetProperty(string, string)</b>
209 <dt><b>.SetProperty(string, int)</b>
210 <dt><b>.SetProperty(string, double)</b>
211 <dd>Applies a named property and value to the test
212 <dt><b>.SetDescription(string)</b>
213 <dd>Sets the description property of the test
214 <dt><b>.SetName(string)</b>
215 <dd>Provides a name for the test. If not specified, a name is generated based on
216 the method name and the arguments provided
217 <dt><b>.Throws(Type)</b>
218 <dt><b>.Throws(string)</b>
219 <dd>Specifies a the Type or FullName of an exception that should be thrown by this invocation
220 <dt><b>.Ignore()</b>
221 <dd>Causes the test case to be ignored.
222 <dt><b>.Ignore(string)</b>
223 <dd>Causes the test case to be ignored with a reason specified.
224</dl>
225
226<h3>Order of Execution</h3>
227
228<p>In NUnit 2.5, individual test cases are sorted alphabetically and executed in
229 that order. With NUnit 2.5.1, the individual cases are not sorted, but are
230 executed in the order in which NUnit discovers them. This order does <b>not</b>
231 follow the lexical order of the attributes and will often vary between different
232 compilers or different versions of the CLR.
233
234<p>As a result, when <b>TestCaseSourceAttribute</b> appears multiple times on a
235 method or when other data-providing attributes are used in combination with
236 <b>TestCaseSourceAttribute</b>, the order of the test cases is undefined.
237
238<p>However, when a single <b>TestCaseSourceAttribute</b> is used by itself,
239 the order of the tests follows exactly the order in which the test cases
240 are returned from the source.
241
242<h3>Note on Object Construction</h3>
243
244<p>NUnit locates the test cases at the time the tests are loaded, creates
245instances of each class with non-static sources and builds a list of
246tests to be executed. Each source object is only created once at this
247time and is destroyed after all tests are loaded.
248
249<p>If the data source is in the test fixture itself, the object is created
250using the appropriate constructor for the fixture parameters provided on
251the <b>TestFixtureAttribute</b> or
252the default constructor if no parameters were specified. Since this object
253is destroyed before the tests are run, no communication is possible between
254these two phases - or between different runs - except through the parameters
255themselves.
256
257
258
259</div>
260
261<!-- Submenu -->
262<div id="subnav">
263<ul>
264<li><a href="index.html">NUnit 2.5.10</a></li>
265<ul>
266<li><a href="getStarted.html">Getting&nbsp;Started</a></li>
267<li><a href="assertions.html">Assertions</a></li>
268<li><a href="constraintModel.html">Constraints</a></li>
269<li><a href="attributes.html">Attributes</a></li>
270<ul>
271<li><a href="category.html">Category</a></li>
272<li><a href="combinatorial.html">Combinatorial</a></li>
273<li><a href="culture.html">Culture</a></li>
274<li><a href="datapoint.html">Datapoint(s)</a></li>
275<li><a href="description.html">Description</a></li>
276<li><a href="exception.html">Exception</a></li>
277<li><a href="explicit.html">Explicit</a></li>
278<li><a href="ignore.html">Ignore</a></li>
279<li><a href="maxtime.html">Maxtime</a></li>
280<li><a href="pairwise.html">Pairwise</a></li>
281<li><a href="platform.html">Platform</a></li>
282<li><a href="property.html">Property</a></li>
283<li><a href="random.html">Random</a></li>
284<li><a href="range.html">Range</a></li>
285<li><a href="repeat.html">Repeat</a></li>
286<li><a href="requiredAddin.html">RequiredAddin</a></li>
287<li><a href="requiresMTA.html">Requires&nbsp;MTA</a></li>
288<li><a href="requiresSTA.html">Requires&nbsp;STA</a></li>
289<li><a href="requiresThread.html">Requires&nbsp;Thread</a></li>
290<li><a href="sequential.html">Sequential</a></li>
291<li><a href="setCulture.html">SetCulture</a></li>
292<li><a href="setUICulture.html">SetUICulture</a></li>
293<li><a href="setup.html">Setup</a></li>
294<li><a href="setupFixture.html">SetupFixture</a></li>
295<li><a href="suite.html">Suite</a></li>
296<li><a href="teardown.html">Teardown</a></li>
297<li><a href="test.html">Test</a></li>
298<li><a href="testCase.html">TestCase</a></li>
299<li id="current"><a href="testCaseSource.html">TestCaseSource</a></li>
300<li><a href="testFixture.html">TestFixture</a></li>
301<li><a href="fixtureSetup.html">TestFixtureSetUp</a></li>
302<li><a href="fixtureTeardown.html">TestFixtureTearDown</a></li>
303<li><a href="theory.html">Theory</a></li>
304<li><a href="timeout.html">Timeout</a></li>
305<li><a href="values.html">Values</a></li>
306<li><a href="valueSource.html">ValueSource</a></li>
307</ul>
308<li><a href="runningTests.html">Running&nbsp;Tests</a></li>
309<li><a href="extensibility.html">Extensibility</a></li>
310<li><a href="releaseNotes.html">Release&nbsp;Notes</a></li>
311<li><a href="samples.html">Samples</a></li>
312<li><a href="license.html">License</a></li>
313</ul>
314</ul>
315</div>
316<!-- End of Submenu -->
317
318
319<!-- Standard Footer for NUnit.org -->
320<div id="footer">
321 Copyright &copy; 2010 Charlie Poole. All Rights Reserved.
322</div>
323<!-- End of Footer -->
324
325</body>
326</html>
Note: See TracBrowser for help on using the repository browser.