bundles/org.eclipse.jdt.doc.user/gettingStarted/qs-junit.htm - platform/eclipse.platform.common - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
 <html>
   <head>
     <title>
       Implementing and running JUnit Tests
     </title>
     <link rel="stylesheet" href="../book.css" charset="ISO-8859-1" type="text/css">
     <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
     <meta http-equiv="Content-Style-Type" content="text/css">
   </head>
   <body>
     <h1>
       Writing and running JUnit tests
     </h1>
     <p>
       In this section, you will be using the <a href="http://www.junit.org"> JUnit</a>
     testing framework to write and run tests. To get started with JUnit you can
     refer to the <a href="http://junit.sourceforge.net/doc/cookbook/cookbook.htm">JUnit
     Cookbook</a>.
     </p>
     <h2>
       Writing Tests
     </h2>

     <p>
       Before you can write JUnit tests you have to add the <strong>junit.jar</strong>
       library to your build class path. The Eclipse installation includes JUnit
       in the <i>org.junit</i> plug-in:
     </p>

     <ol>
       <li>Create a project &quot;JUnitTest&quot;
       <li>Open the project's build path property page
       <li>Switch to the <b> Libraries</b> tab</li>
       <li>Add the <i> junit.jar</i> contained in org.junit in the plug-ins
         directory as an external JAR to your
         project.</li>
     </ol>
     Optionally, if you want to browse the JUnit source, then attach the <i>junitsrc.zip</i>
     to the <i> junit.jar</i>. The source zip is located in the org.eclipse.jdt.source
     plug-in in src/org.junit_3.8.1.
     <p>
       Now that the JUnitTest project has access to the JUnit classes you can write your
       first test. You implement the test in a subclass of <strong>TestCase</strong>. You can
       do so either using the standard Class wizard or the specialized <strong>Test Case
       </strong> wizard:
     </p>
     <ol>
       <li>Open the New wizard (<strong>File  &gt; New  &gt; Other...</strong>)</li>
       <li>Select <strong>Java &gt; JUnit</strong> in the left pane
         and <strong>TestCase</strong> in the right pane and click <strong>Next</strong>.</li>
       <li>Enter &quot;<i>TestFailure&quot;</i> as the name of your test class:
        <p>
         <img src="../images/qs-jun1.gif" width=500 height=500 border="0" alt="TestCase creation wizard page 1"><br>
        </p>
       </li>
       <li>Click <strong>Finish</strong> to create the test class.
       </li>
     </ol>

     <p>
       Add a test method that fails to the class <i>TestFailure</i>. A quick
       way to enter a test method is with the <i>test</i> template. To do so
       type &quot;test&quot; followed by Ctrl+Space to activate code
       assist and select the &quot;test&quot; template. Change the name of the
       created method to <i>testFailure</i> and invoke the <i>fail() </i>method.
     </p>
     <p><code>
       public void testFailure() {<br>
       &nbsp;&nbsp;&nbsp; fail();<br>
       }
     </code></p>

     <p>Now you are ready to run your first test.</p>

     <h2>
       Running Tests
     </h2>

     <p>To run TestFailure, activate the <b>Run</b> drop-down
     menu in the toolbar and select <span class="control">Run as &gt; JUnit Test</span>.
     You can inspect the test results in the <i>JUnit</i> view. This view shows
     you the test run progress and status:</p>

     <p><img src="../images/qs-jun3.gif" width=255 height=395 border="0" alt="Failed test"></p>

     <p> The view is shown in the current
     perspective whenever you start a test run. A convenient arrangement for the
     JUnit view is to dock it as a fast view. The JUnit view has two tabs: one shows
     you a list of failures and the other shows you the full test suite as
     a tree. You can navigate from a failure to the corresponding source by
     double clicking the corresponding line in the failure trace.</p>

     <p>Dock the JUnit view as a fast view, remove the <i>
     fail()</i> statement in the method <i> testFailure()</i> so that the test passes and rerun
     the test again. You can rerun a test either by clicking the <b>Rerun</b> button in
     the view's tool bar or you can re-run the program that was last launched by activating
     the <b>Run</b> drop down. This time the test should succeed. Because the test was successful,
      the JUnit view doesn't pop up, but the success indicator shows on
     the JUnit view icon and the status line shows the test result. As a reminder
     to rerun your tests the view icon is decorated by a &quot;*&quot;
     whenever you change the workspace contents after the run.</p>

     <blockquote>
       <p><img src="../images/qs-jun2.gif" width=23 height=23 border="0" alt="Successful test">
       - A successful test run<br>
       <img src="../images/qs-jun4.gif" width=25 height=23 border="0" alt="Successful test but workspace has changed"> -
       A successful test run, but the workspace contents has changed since the
       last test run.</p>

     </blockquote>
     <p>In addition to running a test case as described above you can also:</p>
     <ul>
       <li>Run all tests inside a project, source folder, or package - &nbsp;<br>
         Select a package or source folder and run all the included tests with <strong>Run as &gt; JUnit Test</strong>.
         This command finds all tests inside a project, source folder or package
         and executes them.</li>
       <li>Run a single test method - <br>
         Select a test method in the Outline or Package Explorer and with <strong>Run as &gt; JUnit Test</strong>
         the selected test method will be run.</li>
       <li>Rerun a single test - <br>
         Select a test in the JUnit view and execute <b>Rerun </b>from the context
         menu.</li>
     </ul>

     <h2>
       Customizing a Test Configuration
     </h2>

     <p>When you want to pass parameters or customize the
     settings for a test run you open the Launch Configuration Dialog. Select <strong>Run...</strong>.in the <strong>Run</strong>
     drop-down menu in the toolbar:</p>
     <p><img src="../images/qs-jun5.gif" width=612 height=475 border="0" alt="JUnit Launch Configuration"></p>
     <p>In this dialog you can specify the test to be run, its arguments, its run-time
     class path, and the Java run-time environment.</p>

     <h2>
       Debugging a Test Failure
     </h2>

     <p>In the case of a test failure you can follow these steps to debug it:</p>
     <ol>
       <li>Double click the failure entry from the stack trace in the JUnit view to open the
         corresponding file in the editor.
       <li>Set a breakpoint at the beginning of the test method.
       <li>Select the test case and execute&nbsp; <b>Debug As&gt;JUnit Test</b> from
         the <b>Debug </b>drop down.
     </ol>
     <p>A JUnit launch configuration has a &quot;keep alive&quot; option. If your
     Java virtual machine supports &quot;hot code replacement&quot; you can fix the code and rerun the test
     without restarting the full test run. To enable this option select the <strong>Keep
     JUnit running after a test run when debugging</strong>  checkbox in the JUnit
     launch configuration.</p>

     <h2>
       Creating a Test Suite
     </h2>

     <p>
       The JUnit <b>TestSuite </b>wizard helps you with the creation of a test
       suite. You can select the set of classes that should belong to a suite.
     </p>

     <ol>
       <li>Open the New wizard</li>
       <li>Select <strong>Java &gt; JUnit</strong> in the left pane
         and <strong>TestSuite</strong> in the right pane and click <strong>Next</strong>.</li>
       <li>Enter a name for your test suite class (the convention is to use
         &quot;AllTests&quot; which appears by default).<br>
         <p><img src="../images/qs-jun6.gif" width=500 height=526 border="0" alt="Test Suite wizard"></p>
       </li>
       <li>Select the classes that should be included in the suite. We currently
         have a single test class only, but you can add to the suite later.</li>
     </ol>

     <p>You can add or remove test classes from the test suite in two ways:</p>
     <ul>
       <li>Manually
       by editing the test suite file<li>By re-running the wizard and selecting the new set of test classes.</li>
     </ul>
     <p>Note: the wizard puts 2 markers, <code>//$JUnit-BEGIN$</code> and
     <code>//$JUnit-END$</code>, into the created Test suite class, which allows
     the wizard to update existing test suite classes. Editing code between the markers is
     not recommended.</p>
     <p>
       <a href="../hglegal2003.htm"><img src="../images/ngibmcpy2003.gif" width=324 height=14 alt="Copyright (c) 2000, 2003 IBM Corporation and others. All Rights Reserved." border="0"></a>
     </p>
   </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
	<html>
	<head>
	<title>
	Implementing and running JUnit Tests
	</title>
	<link rel="stylesheet" href="../book.css" charset="ISO-8859-1" type="text/css">
	<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
	<meta http-equiv="Content-Style-Type" content="text/css">
	</head>
	<body>
	<h1>
	Writing and running JUnit tests
	</h1>
	<p>
	In this section, you will be using the <a href="http://www.junit.org"> JUnit</a>
	testing framework to write and run tests. To get started with JUnit you can
	refer to the <a href="http://junit.sourceforge.net/doc/cookbook/cookbook.htm">JUnit
	Cookbook</a>.
	</p>
	<h2>
	Writing Tests
	</h2>

	<p>
	Before you can write JUnit tests you have to add the <strong>junit.jar</strong>
	library to your build class path. The Eclipse installation includes JUnit
	in the <i>org.junit</i> plug-in:
	</p>

	<ol>
	<li>Create a project "JUnitTest"
	<li>Open the project's build path property page
	<li>Switch to the <b> Libraries</b> tab</li>
	<li>Add the <i> junit.jar</i> contained in org.junit in the plug-ins
	directory as an external JAR to your
	project.</li>
	</ol>
	Optionally, if you want to browse the JUnit source, then attach the <i>junitsrc.zip</i>
	to the <i> junit.jar</i>. The source zip is located in the org.eclipse.jdt.source
	plug-in in src/org.junit_3.8.1.
	<p>
	Now that the JUnitTest project has access to the JUnit classes you can write your
	first test. You implement the test in a subclass of <strong>TestCase</strong>. You can
	do so either using the standard Class wizard or the specialized <strong>Test Case
	</strong> wizard:
	</p>
	<ol>
	<li>Open the New wizard (<strong>File > New > Other...</strong>)</li>
	<li>Select <strong>Java > JUnit</strong> in the left pane
	and <strong>TestCase</strong> in the right pane and click <strong>Next</strong>.</li>
	<li>Enter "<i>TestFailure"</i> as the name of your test class:
	<p>
	<img src="../images/qs-jun1.gif" width=500 height=500 border="0" alt="TestCase creation wizard page 1"><br>
	</p>
	</li>
	<li>Click <strong>Finish</strong> to create the test class.
	</li>
	</ol>

	<p>
	Add a test method that fails to the class <i>TestFailure</i>. A quick
	way to enter a test method is with the <i>test</i> template. To do so
	type "test" followed by Ctrl+Space to activate code
	assist and select the "test" template. Change the name of the
	created method to <i>testFailure</i> and invoke the <i>fail() </i>method.
	</p>
	<p><code>
	public void testFailure() {<br>
	fail();<br>
	}
	</code></p>

	<p>Now you are ready to run your first test.</p>

	<h2>
	Running Tests
	</h2>

	<p>To run TestFailure, activate the <b>Run</b> drop-down
	menu in the toolbar and select <span class="control">Run as > JUnit Test</span>.
	You can inspect the test results in the <i>JUnit</i> view. This view shows
	you the test run progress and status:</p>

	<p><img src="../images/qs-jun3.gif" width=255 height=395 border="0" alt="Failed test"></p>

	<p> The view is shown in the current
	perspective whenever you start a test run. A convenient arrangement for the
	JUnit view is to dock it as a fast view. The JUnit view has two tabs: one shows
	you a list of failures and the other shows you the full test suite as
	a tree. You can navigate from a failure to the corresponding source by
	double clicking the corresponding line in the failure trace.</p>

	<p>Dock the JUnit view as a fast view, remove the <i>
	fail()</i> statement in the method <i> testFailure()</i> so that the test passes and rerun
	the test again. You can rerun a test either by clicking the <b>Rerun</b> button in
	the view's tool bar or you can re-run the program that was last launched by activating
	the <b>Run</b> drop down. This time the test should succeed. Because the test was successful,
	the JUnit view doesn't pop up, but the success indicator shows on
	the JUnit view icon and the status line shows the test result. As a reminder
	to rerun your tests the view icon is decorated by a "*"
	whenever you change the workspace contents after the run.</p>

	<blockquote>
	<p><img src="../images/qs-jun2.gif" width=23 height=23 border="0" alt="Successful test">
	- A successful test run<br>
	<img src="../images/qs-jun4.gif" width=25 height=23 border="0" alt="Successful test but workspace has changed"> -
	A successful test run, but the workspace contents has changed since the
	last test run.</p>

	</blockquote>
	<p>In addition to running a test case as described above you can also:</p>
	<ul>
	<li>Run all tests inside a project, source folder, or package -  <br>
	Select a package or source folder and run all the included tests with <strong>Run as > JUnit Test</strong>.
	This command finds all tests inside a project, source folder or package
	and executes them.</li>
	<li>Run a single test method - <br>
	Select a test method in the Outline or Package Explorer and with <strong>Run as > JUnit Test</strong>
	the selected test method will be run.</li>
	<li>Rerun a single test - <br>
	Select a test in the JUnit view and execute <b>Rerun </b>from the context
	menu.</li>
	</ul>

	<h2>
	Customizing a Test Configuration
	</h2>

	<p>When you want to pass parameters or customize the
	settings for a test run you open the Launch Configuration Dialog. Select <strong>Run...</strong>.in the <strong>Run</strong>
	drop-down menu in the toolbar:</p>
	<p><img src="../images/qs-jun5.gif" width=612 height=475 border="0" alt="JUnit Launch Configuration"></p>
	<p>In this dialog you can specify the test to be run, its arguments, its run-time
	class path, and the Java run-time environment.</p>

	<h2>
	Debugging a Test Failure
	</h2>

	<p>In the case of a test failure you can follow these steps to debug it:</p>
	<ol>
	<li>Double click the failure entry from the stack trace in the JUnit view to open the
	corresponding file in the editor.
	<li>Set a breakpoint at the beginning of the test method.
	<li>Select the test case and execute  <b>Debug As>JUnit Test</b> from
	the <b>Debug </b>drop down.
	</ol>
	<p>A JUnit launch configuration has a "keep alive" option. If your
	Java virtual machine supports "hot code replacement" you can fix the code and rerun the test
	without restarting the full test run. To enable this option select the <strong>Keep
	JUnit running after a test run when debugging</strong> checkbox in the JUnit
	launch configuration.</p>

	<h2>
	Creating a Test Suite
	</h2>

	<p>
	The JUnit <b>TestSuite </b>wizard helps you with the creation of a test
	suite. You can select the set of classes that should belong to a suite.
	</p>

	<ol>
	<li>Open the New wizard</li>
	<li>Select <strong>Java > JUnit</strong> in the left pane
	and <strong>TestSuite</strong> in the right pane and click <strong>Next</strong>.</li>
	<li>Enter a name for your test suite class (the convention is to use
	"AllTests" which appears by default).<br>
	<p><img src="../images/qs-jun6.gif" width=500 height=526 border="0" alt="Test Suite wizard"></p>
	</li>
	<li>Select the classes that should be included in the suite. We currently
	have a single test class only, but you can add to the suite later.</li>
	</ol>

	<p>You can add or remove test classes from the test suite in two ways:</p>
	<ul>
	<li>Manually
	by editing the test suite file<li>By re-running the wizard and selecting the new set of test classes.</li>
	</ul>
	<p>Note: the wizard puts 2 markers, <code>//$JUnit-BEGIN$</code> and
	<code>//$JUnit-END$</code>, into the created Test suite class, which allows
	the wizard to update existing test suite classes. Editing code between the markers is
	not recommended.</p>
	<p>
	<a href="../hglegal2003.htm"><img src="../images/ngibmcpy2003.gif" width=324 height=14 alt="Copyright (c) 2000, 2003 IBM Corporation and others. All Rights Reserved." border="0"></a>
	</p>
	</body>
	</html>