original source : http://www.vogella.com/articles/JUnit/article.html#junit_intro
JUnit - Tutorial
Version 2.1
Copyright © 2007, 2008, 2009, 2010, 2011, 2012 Lars Vogel
02.04.2012
Revision History | ||
---|---|---|
Revision 0.1-0.5 | 03.09.2007 | Lars Vogel |
JUnit description | ||
Revision 0.6 - 2.1 | 10.05.2008 - 02.04.2012 | Lars Vogel |
bugfixes and enhancements |
Table of Contents
A unit test is a piece of code written by a developer that executes a specific functionality in the code under test. Unit tests ensure that code is working as intended and validate that this is still the case after code changes.
JUnit 4.x is a test framework which uses annotations to identify methods that are tests. JUnit assumes that all test methods can be executed in an arbitrary order. Therefore tests should not depend on other tests.
To write a test with JUnit
-
Annotate a method with @org.junit.Test
-
Use a method provided by JUnit to check the expected result of the code execution versus the actual result
You can use Eclipse or the class "org.junit.runner.JUnitCore" to run the test.
If you use Eclipse you can use the integrated JUnit in Eclipse for your testing.
If you want to control the used JUnit library explicitly, download JUnit4.x.jar from the JUnit website athttp://www.junit.org/ . The download contains the "junit-4.*.jar" which is the JUnit library. Add this library to your Java project and add it to the classpath.
Create a new project de.vogella.junit.first
. We want to create the unit tests in a separate folder. The creation of a separate folder for tests is not mandatory. But it is a good practice to keep the code separated from the regular code. You might even create a separate project for the test classes, but we skip this step to make this example simpler.
Create a new source folder test
via right-clicking on your project, select "Properties" and choose the "Java Build Path". Select the "Source" tab.
![Create new source folder for the tests](http://www.vogella.com/articles/JUnit/images/xjunit10.gif.pagespeed.ic.Wmi1Kchw-P.png)
Press "Add folder" then press "Create new folder". Create the folder "test".
![Creating a new folder](http://www.vogella.com/articles/JUnit/images/junit20.gif)
Alternatively you can add a new source folder by right-clicking on a project and selecting
→ .In the "src" folder, create the de.vogella.junit.first
package and the following class.
package de.vogella.junit.first; public class MyClass { public int multiply(int x, int y) { return x / y; } }
Right click on your new class in the Package Explorer and select
→ . Select "New JUnit 4 test" and set the source folder to "test", so that your test class gets created in this folder.
![Create new test class](http://www.vogella.com/articles/JUnit/images/junit30.gif)
Press "Next" and select the methods which you want to test.
![Selecting the methods to test](http://www.vogella.com/articles/JUnit/images/junit50.gif)
If the JUnit library in not part of your classpath, Eclipse will prompt you to do so.
![Eclipes prompt for adding JUnit to the project class path](http://www.vogella.com/articles/JUnit/images/junit55.gif)
Create a test with the following code.
package de.vogella.junit.first; import org.junit.Test; import static org.junit.Assert.assertEquals; public class MyClassTest { @Test public void testMultiply() { MyClass tester = new MyClass(); assertEquals("Result", 50, tester.multiply(10, 5)); } }
Right click on your new test class and select
→ .
![Run JUnit test via Eclipse](http://www.vogella.com/articles/JUnit/images/junit60.gif)
The result of the tests will be displayed in the JUnit View
.
![Result of running a unit test](http://www.vogella.com/articles/JUnit/images/junit75.gif)
The test should be failing (indicated via a red bar).
This is because our multiplier class is currently not working correctly (it does a division instead of multiplication). Fix the bug and re-run test to get a green bar.
If you have several tests you can combine them into a test suite. Running a test suite will execute all tests in that suite.
To create a test suite,
→ → → → → .
![Create a test suite](http://www.vogella.com/articles/JUnit/images/junit80.gif)
Select "Next" and select the methods for which you want to create a test.
Change the code to the following to make your test suite run your test. If you develop another test later you can add it to @Suite.SuiteClasses
.
package mypackage; import org.junit.runner.RunWith; import org.junit.runners.Suite; @RunWith(Suite.class) @Suite.SuiteClasses( { MyClassTest.class }) public class AllTests { }
You can also run your tests from via your own code. The class org.junit.runner.JUnitCore
provides the method runClasses() which allows you to run one or several tests classes. As a return parameter you receive an object of the type org.junit.runner.Result
. This object can be used to retrieve information about the tests.
In your "test" folder create a new class MyTestRunner
with the following code. This class will execute your test class and write potential failures to the console.
package de.vogella.junit.first; import org.junit.runner.JUnitCore; import org.junit.runner.Result; import org.junit.runner.notification.Failure; public class MyTestRunner { public static void main(String[] args) { Result result = JUnitCore.runClasses(MyClassTest.class); for (Failure failure : result.getFailures()) { System.out.println(failure.toString()); } } }
JUnit uses a lot of static methods and Eclipse cannot always correctly automatically import static imports.
You can make the JUnit test methods available via the content assists.
Open the Preferences via Window -> Preferences and select
→ → → .Use the new "New Member" button to add the methods you need. The example below makes the assertTrue
,assertFalse
and assertEquals
methods available.
![Adding static imports to the preferences](http://www.vogella.com/articles/JUnit/images/staticimport10.gif)
You can now use Content Assist (Ctrl+Space) to add the method and the import.
I suggest to add at least the following new members:
-
org.junit.Assert.assertTrue
-
org.junit.Assert.assertFalse
-
org.junit.Assert.assertEquals
-
org.junit.Assert.fail
The following table gives an overview of the available annotations in JUnit 4.x.
Table 1. Annotations
Annotation | Description |
---|---|
@Test public void method() | The annotation @Test identifies that a method is a test method. |
@Before public void method() | Will execute the method before each test. This method can prepare the test environment (e.g. read input data, initialize the class). |
@After public void method() | Will execute the method after each test. This method can cleanup the test environment (e.g. delete temporary data, restore defaults). |
@BeforeClass public void method() | Will execute the method once, before the start of all tests. This can be used to perform time intensive activities, for example to connect to a database. |
@AfterClass public void method() | Will execute the method once, after all tests have finished. This can be used to perform clean-up activities, for example to disconnect from a database. |
@Ignore | Will ignore the test method. This is useful when the underlying code has been changed and the test case has not yet been adapted. Or if the execution time of this test is too long to be included. |
@Test (expected = Exception.class) | Fails, if the method does not throw the named exception. |
@Test(timeout=100) | Fails, if the method takes longer than 100 milliseconds. |
The following table gives an overview of the available assert statements.
Table 2. Test methods
Statement | Description |
---|---|
fail(String) | Let the method fail. Might be used to check that a certain part of the code is not reached. Or to have failing test before the test code is implemented. |
assertTrue(true) / assertTrue(false) | Will always be true / false. Can be used to predefine a test result, if the test is not yet implemented. |
assertTrue([message], boolean condition) | Checks that the boolean condition is true. |
assertsEquals([String message], expected, actual) | Tests that two values are the same. Note: for arrays the reference is checked not the content of the arrays. |
assertsEquals([String message], expected, actual, tolerance) | Test that float or double values match. The tolerance is the number of decimals which must be the same. |
assertNull([message], object) | Checks that the object is null. |
assertNotNull([message], object) | Checks that the object is not null. |
assertSame([String], expected, actual) | Checks that both variables refer to the same object. |
assertNotSame([String], expected, actual) | Checks that both variables refer to different objects. |
Unit testing uses also mocking of objects. In this case the real object is replaced by a replacement which has a predefined behavior the test. There are several frameworks available for mocking. To learn more about mock frameworks please see EasyMock Tutorial
Before posting questions, please see the vogella FAQ. If you have questions or find an error in this article please use the www.vogella.com Google Group. I have created a short list how to create good questions which might also help you.