5
<title>Example: Advanced Test Options</title>
6
<link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Maven+Pro:400,700">
7
<link rel="stylesheet" href="../../build/cssgrids/grids-min.css">
8
<link rel="stylesheet" href="../assets/css/main.css">
9
<link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
10
<script src="../../build/yui/yui-min.js"></script>
15
<h1>Example: Advanced Test Options</h1>
18
<a href="#toc" class="jump">Jump to Table of Contents</a>
22
<div class="yui3-u-3-4">
24
<div class="content"><div class="intro">
25
<p>This example shows how to use advanced test options, which allow you to specify additional information about how a test should be run.
26
Each <a href="index.html#testcase"><code>TestCase</code></a> can specify up to three different options for tests,
27
including tests that should be ignored, tests that should throw an error, and tests that should fail.</p>
30
<div class="example yui3-skin-sam">
31
<div id="testLogger"></div>
34
YUI().use('node', 'test-console', 'test', function (Y) {
36
Y.namespace("example.test");
38
Y.example.test.AdvancedOptionsTestCase = new Y.Test.Case({
40
//the name of the test case - if not provided, one is automatically generated
41
name: "Advanced Options Tests",
44
* Specifies tests that "should" be doing something other than the expected.
49
* Tests listed in here should fail, meaning that if they fail, the test
50
* has passed. This is used mostly for YuiTest to test itself, but may
51
* be helpful in other cases.
55
//the test named "testFail" should fail
61
* Tests listed here should throw an error of some sort. If they throw an
62
* error, then they are considered to have passed.
67
* You can specify "true" for each test, in which case any error will
68
* cause the test to pass.
70
testGenericError: true,
73
* You can specify an error message, in which case the test passes only
74
* if the error thrown matches the given message.
76
testStringError: "I'm a specific error message.",
77
testStringError2: "I'm a specific error message.",
80
* You can also specify an error object, in which case the test passes only
81
* if the error thrown is on the same type and has the same message.
83
testObjectError: new TypeError("Number expected."),
84
testObjectError2: new TypeError("Number expected."),
85
testObjectError3: new TypeError("Number expected.")
90
* Tests listed here should be ignored when the test case is run. For these tests,
91
* setUp() and tearDown() are not called.
100
//-------------------------------------------------------------------------
101
// Basic tests - all method names must begin with "test"
102
//-------------------------------------------------------------------------
104
testFail : function() {
106
//force a failure - but since this test "should" fail, it will pass
107
Y.Assert.fail("Something bad happened.");
111
testGenericError : function() {
112
throw new Error("Generic error");
115
testStringError : function() {
117
//throw a specific error message - this will pass because it "should" happen
118
throw new Error("I'm a specific error message.");
121
testStringError2 : function() {
123
//throw a specific error message - this will fail because the message isn't expected
124
throw new Error("I'm a specific error message, but a wrong one.");
127
testObjectError : function() {
129
//throw a specific error and message - this will pass because it "should" happen
130
throw new TypeError("Number expected.");
133
testObjectError2 : function() {
135
//throw a specific error and message - this will fail because the type doesn't match
136
throw new Error("Number expected.");
139
testObjectError3 : function() {
141
//throw a specific error and message - this will fail because the message doesn't match
142
throw new TypeError("String expected.");
145
testIgnore : function () {
146
alert("You'll never see this.");
153
(new Y.Test.Console({
155
style: 'block' // to anchor in the example content
156
})).render('#testLogger');
158
Y.Test.Runner.add(Y.example.test.AdvancedOptionsTestCase);
168
<h2 class="first" id="advanced-test-options">Advanced Test Options</h2>
170
<p>This example begins by creating a namespace and a <code>Y.Test.Case</code> object:</p>
171
<pre class="code prettyprint">Y.namespace("example.test");
172
Y.example.test.AdvancedOptionsTestCase = new Y.TestCase({
173
name: "Advanced Options Tests"
177
<p>This <code>Y.Test.Case</code> serves as the basis for this example.</p>
179
<h3 id="using-_should">Using <code>_should</code></h3>
181
<p>Immediately after the <code>name</code> of the <code>Y.Test.Case</code> is defined, there is a <code>_should</code> property.
182
This property specifies information about how tests <em>should</em> behave and is defined as an object literal with one
183
or more of the following properties: <code>fail</code>, <code>error</code>, and <code>ignore</code>.Each of these three
184
is also defined as an object literal whose property names map directly to the names of test methods in the <code>Y.Test.Case</code>.
185
This example uses all three properties:</p>
186
<pre class="code prettyprint">Y.example.test.AdvancedOptionsTestCase = new Y.TestCase({
188
//the name of the test case - if not provided, one is automatically generated
189
name: "Advanced Options Tests",
192
* Specifies tests that "should" be doing something other than the expected.
197
* Tests listed in here should fail, meaning that if they fail, the test
198
* has passed. This is used mostly for YuiTest to test itself, but may
199
* be helpful in other cases.
203
//the test named "testFail" should fail
209
* Tests listed here should throw an error of some sort. If they throw an
210
* error, then they are considered to have passed.
215
* You can specify "true" for each test, in which case any error will
216
* cause the test to pass.
218
testGenericError: true,
221
* You can specify an error message, in which case the test passes only
222
* if the error thrown matches the given message.
224
testStringError: "I'm a specific error message.",
225
testStringError2: "I'm a specific error message.",
228
* You can also specify an error object, in which case the test passes only
229
* if the error thrown is on the same type and has the same message.
231
testObjectError: new TypeError("Number expected."),
232
testObjectError2: new TypeError("Number expected."),
233
testObjectError3: new TypeError("Number expected.")
238
* Tests listed here should be ignored when the test case is run. For these tests,
239
* setUp() and tearDown() are not called.
252
<p>This <code>Y.Test.Case</code> specifies one test that should fail, six that should throw an error, and one that should be ignored.</p>
253
<p>In the <code>fail</code> section, the test method <code>testFail()</code> is specified as one that should fail. By adding the
254
property <code>testFail</code> and settings its value to true, the <code>Y.Test.Runner</code> knows that this test is expected to fail.
255
If the test were to be run without failing, it would be considered a failure of the test. This feature is useful when testing
256
YUI Test itself or addon components to YUI Test.</p>
257
<p>Moving on to the <code>error</code> section, there are six tests specified that should throw an error. There are three different ways
258
to indicate that a test is expected to throw an error. The first is simply to add a property with the same name as the test method
259
and set its value equal to true (similar to specifying tests that should fail). In this example, the <code>testGenericError()</code>
260
method is specified this way. When specified like this, the test passes regardless of the type of error that occurs. This can be
261
dangerous since unexpected errors will also cause the test to pass. To be more specific, set the property value for the test method
262
to an error message string. When a string is used instead of the Boolean true, the test passes only when an error is thrown and that
263
error message matches the string. In this example, <code>testStringError()</code> and <code>testStringError2()</code> expect an error
264
to be thrown with an error message of "I'm a specific error message." If any other error occurs inside of the these methods,
265
the test will fail because the error message doesn't match. The last way to specify an error should occur is to create an actual error
266
object, which is the case with <code>testObjectError()</code>, <code>testObjectError2()</code>, and <code>testObjectError3()</code>.
267
When specified in this way, a test will pass only when an error is thrown whose constructor and error message match that of the
269
<p>The last section is <code>ignore</code>, which determines tests that should be ignored. In this example, the method <code>testIgnore()</code>
270
is set to be ignored when the <code>Y.Test.Case</code> is executed. Test in the <code>ignore</code> section are specified the same way
271
as those in the <code>fail</code> section, by adding the name as a property and setting its value to true.</p>
273
<h3 id="creating-the-test-methods">Creating the test methods</h3>
275
<p>The next part of the example contains the actual test methods. Since each test method is specified as having a certain behavior in
276
<code>_should</code>, they each do something to show their particular functionality.</p>
277
<p>The first method is <code>testFail()</code>, which does nothing but purposely fail. Since this method is specified as one that should
278
fail, it means that this test will pass:</p>
279
<pre class="code prettyprint">Y.example.test.AdvancedOptionsTestCase = new Y.Test.Case({
281
//the name of the test case - if not provided, one is automatically generated
282
name: "Advanced Options Tests",
286
testFail : function() {
288
//force a failure - but since this test "should" fail, it will pass
289
Y.Assert.fail("Something bad happened.");
296
<p>This method uses <code>Assert.fail()</code> to force the test to fail. This type of method is helpful if you are creating your own
297
type of assert methods that should fail when certain data is passed in.</p>
298
<p>Next, the test methods that should error are defined. The <code>testGenericError()</code> method is specified as needing to throw
299
an error to pass. In the <code>error</code> section, <code>testGenericError</code> is set to true, meaning that any error causes
300
this method to pass. To illustrate this, the method simply throws an error:</p>
301
<pre class="code prettyprint">Y.example.test.AdvancedOptionsTestCase = new Y.Test.Case({
303
//the name of the test case - if not provided, one is automatically generated
304
name: "Advanced Options Tests",
308
testGenericError : function() {
309
throw new Error("Generic error");
315
<p>The fact that this method throws an error is enough to cause it to pass (the type of error and error message don't matter). The next
316
two methods, <code>testStringError()</code> and <code>testStringError2()</code> are specified as throwing an error with a specific
317
message ("I'm a specific error message."):</p>
318
<pre class="code prettyprint">Y.example.test.AdvancedOptionsTestCase = new Y.Test.Case({
320
//the name of the test case - if not provided, one is automatically generated
321
name: "Advanced Options Tests",
325
testStringError : function() {
327
//throw a specific error message - this will pass because it "should" happen
328
throw new Error("I'm a specific error message.");
331
testStringError2 : function() {
333
//throw a specific error message - this will fail because the message isn't expected
334
throw new Error("I'm a specific error message, but a wrong one.");
340
<p>The <code>testStringError()</code> method will pass when executed because the error message matches up exactly with the one
341
specified in the <code>error</code> section. The <code>testStringError2()</code> method, however, will fail because its
342
error message is different from the one specified.</p>
343
<p>To be more specific, <code>testObjectError()</code>, <code>testObjectError2()</code>, and <code>testObjectError3()</code>,
344
specified an error type (<code>TypeError</code>) and an error messsage ("Number expected."):</p>
345
<pre class="code prettyprint">Y.example.test.AdvancedOptionsTestCase = new Y.Test.Case({
347
//the name of the test case - if not provided, one is automatically generated
348
name: "Advanced Options Tests",
352
testObjectError : function() {
354
//throw a specific error and message - this will pass because it "should" happen
355
throw new TypeError("Number expected.");
358
testObjectError2 : function() {
360
//throw a specific error and message - this will fail because the type doesn't match
361
throw new Error("Number expected.");
364
testObjectError3 : function() {
366
//throw a specific error and message - this will fail because the message doesn't match
367
throw new TypeError("String expected.");
373
<p>Of the these three methods, only <code>testObjectError()</code> will pass because it's the only one that throws a <code>TypeError</code>
374
object with the message, "Number expected." The <code>testObjectError2()</code> method will fail because the type of error
375
being thrown (<code>Error</code>) is different from the expected type (<code>TypeError</code>), as specified in the <code>error</code>
376
section. The last method, <code>testObjectError3()</code>, also fails. Though it throws the right type of error, the error message
377
doesn't match the one that was specified.</p>
378
<p>The last method in the <code>Y.Test.Case</code> is <code>testIgnore()</code>, which is specified to be ignored. To be certain, this
379
method pops up a message:</p>
380
<pre class="code prettyprint">Y.example.test.AdvancedOptionsTestCase = new Y.Test.Case({
382
//the name of the test case - if not provided, one is automatically generated
383
name: "Advanced Options Tests",
387
testIgnore : function () {
388
alert("You'll never see this.");
392
<p>If this test weren't ignored, then the alert should be displayed. Since it is ignored, though, you will never see the alert. Additionally,
393
there is a special message displayed in the <code>Y.Console</code> when a test is ignored.</p>
395
<h3 id="running-the-tests">Running the tests</h3>
397
<p>With all of the tests defined, the last step is to run them:</p>
399
<pre class="code prettyprint">//create the console
400
(new Y.Test.Console({
403
})).render('#testLogger');
405
//add the test suite to the runner's queue
406
Y.Test.Runner.add(Y.example.test.AdvancedOptionsTestCase);
408
//run the tests
409
Y.Test.Runner.run();</pre>
412
<p>Before running the tests, it's necessary to create a <code>Y.Console</code> object to display the results (otherwise the tests would run
413
but you wouldn't see the results). After that, the <code>Y.Test.Runner</code> is loaded with the <code>Y.Test.Suite</code> object by calling
414
<code>add()</code> (any number of <code>Y.Test.Case</code> and <code>Y.Test.Suite</code> objects can be added to a <code>Y.Test.Runner</code>,
415
this example only adds one for simplicity). The very last step is to call <code>run()</code>, which begins executing the tests in its
416
queue and displays the results in the <code>Y.Console</code>.</p>
418
<h2 id="complete-example-source">Complete Example Source</h2>
420
<pre class="code prettyprint"><div id="testLogger"></div>
423
YUI().use('node', 'test-console', 'test', function (Y) {
425
Y.namespace("example.test");
427
Y.example.test.AdvancedOptionsTestCase = new Y.Test.Case({
429
//the name of the test case - if not provided, one is automatically generated
430
name: "Advanced Options Tests",
433
* Specifies tests that "should" be doing something other than the expected.
438
* Tests listed in here should fail, meaning that if they fail, the test
439
* has passed. This is used mostly for YuiTest to test itself, but may
440
* be helpful in other cases.
444
//the test named "testFail" should fail
450
* Tests listed here should throw an error of some sort. If they throw an
451
* error, then they are considered to have passed.
456
* You can specify "true" for each test, in which case any error will
457
* cause the test to pass.
459
testGenericError: true,
462
* You can specify an error message, in which case the test passes only
463
* if the error thrown matches the given message.
465
testStringError: "I'm a specific error message.",
466
testStringError2: "I'm a specific error message.",
469
* You can also specify an error object, in which case the test passes only
470
* if the error thrown is on the same type and has the same message.
472
testObjectError: new TypeError("Number expected."),
473
testObjectError2: new TypeError("Number expected."),
474
testObjectError3: new TypeError("Number expected.")
479
* Tests listed here should be ignored when the test case is run. For these tests,
480
* setUp() and tearDown() are not called.
489
//-------------------------------------------------------------------------
490
// Basic tests - all method names must begin with "test"
491
//-------------------------------------------------------------------------
493
testFail : function() {
495
//force a failure - but since this test "should" fail, it will pass
496
Y.Assert.fail("Something bad happened.");
500
testGenericError : function() {
501
throw new Error("Generic error");
504
testStringError : function() {
506
//throw a specific error message - this will pass because it "should" happen
507
throw new Error("I'm a specific error message.");
510
testStringError2 : function() {
512
//throw a specific error message - this will fail because the message isn't expected
513
throw new Error("I'm a specific error message, but a wrong one.");
516
testObjectError : function() {
518
//throw a specific error and message - this will pass because it "should" happen
519
throw new TypeError("Number expected.");
522
testObjectError2 : function() {
524
//throw a specific error and message - this will fail because the type doesn't match
525
throw new Error("Number expected.");
528
testObjectError3 : function() {
530
//throw a specific error and message - this will fail because the message doesn't match
531
throw new TypeError("String expected.");
534
testIgnore : function () {
535
alert("You'll never see this.");
541
//create the console
542
(new Y.Test.Console({
544
style: 'block' // to anchor in the example content
545
})).render('#testLogger');
547
Y.Test.Runner.add(Y.example.test.AdvancedOptionsTestCase);
549
//run the tests
553
</script></pre>
559
<div class="yui3-u-1-4">
560
<div class="sidebar">
562
<div id="toc" class="sidebox">
564
<h2 class="no-toc">Table of Contents</h2>
570
<a href="#advanced-test-options">Advanced Test Options</a>
573
<a href="#using-_should">Using <code>_should</code></a>
576
<a href="#creating-the-test-methods">Creating the test methods</a>
579
<a href="#running-the-tests">Running the tests</a>
584
<a href="#complete-example-source">Complete Example Source</a>
592
<div class="sidebox">
594
<h2 class="no-toc">Examples</h2>
598
<ul class="examples">
601
<li data-description="Demonstrates basic usage of YUI Test for setting up and running tests.">
602
<a href="test-simple-example.html">Simple Testing Example</a>
607
<li data-description="Demonstrates how to use advanced testing features such as defining tests that should fail, tests that should be ignored, and tests that should throw an error.">
608
<a href="test-advanced-test-options.html">Advanced Test Options</a>
613
<li data-description="Demonstrates how to use the ArrayAssert object to test array data.">
614
<a href="test-array-tests.html">Array Processing</a>
619
<li data-description="Demonstrates basic asynchronous tests.">
620
<a href="test-async-test.html">Asynchronous Testing</a>
625
<li data-description="Demonstrates using events with asynchronous tests.">
626
<a href="test-async-event-tests.html">Asynchronous Event Testing</a>
641
<script src="../assets/vendor/prettify/prettify-min.js"></script>
642
<script>prettyPrint();</script>