◆ Problem
You’ve been using Eclipse to write code for a while, but you haven’t built JUnit tests yet. You’d like to know if there is anything specific to know about building JUnit tests with Eclipse.
◆ Background
Eclipse, the powerful open source IDE of choice these days, is interesting in that, on its own, it does virtually nothing. All the real power behind Eclipse comes in the form of high-powered plug-ins. After downloading Eclipse, trying it out, and using it on a daily basis, you begin to wonder whether you’ll ever know everything there is to know about using Eclipse effectively. While there are definite limits to the power of the Eclipse plug-ins, it can seem as though they provide limitless ben- efit. It can be easy to believe that integrating something like JUnit into Eclipse is fraught with complexity.
◆ Recipe
Eclipse makes building your tests simple, whether you decide to put everything in one project and one source tree or use multiple projects and multiple source trees. Your task consists of little more than setting a few Java project properties. As with building your tests using any other tool set, you must have junit.jar on your build-time class path, and your test code must have the production code in its build-time class path. If you already know how to do these things with Eclipse, then go to it; but if you don’t, then read on.
Adding JUnit to your project’s build-time class path is the same whether you have one “kitchen drawer” Eclipse project20 or have separated each kind of test
20That is, a project into which you throw everything. It’s a wonder we ever find anything in there.
100 CHAPTER 3
Organizing and building JUnit tests
code into its own project. The steps in table 3.1 describe how to add JUnit to a project’s Java Build Path.
NOTE If you don’t have a Classpath Variable for JUnit, then follow these steps first:
1 From the workbench menu bar, select Window > Preferences.
2 In the left pane of the Preferences dialog, expand Java and then select Classpath Variables.
3 At the list of Classpath Variables, press New.
4 At the New Variable Entry dialog box, enter JUNIT_JAR for the Name and then browse to (or type) the location of junit.jar on your file system. Press OK.
5 Press OK at the Preferences dialog box to return to the workbench.
Your Classpath Variable is now ready to use in your project’s Java Build Path.
Table 3.1 Adding JUnit to an Eclipse project’s Java Build Path
Action Result
1 Right-click the project and then select Properties.
Eclipse opens the project properties dialog box.
2 In the left pane, select Java Build Path.
Eclipse displays the Source tab, showing the various source folders in your project. Here you can add, change, or remove source folders to manage multiple source trees. No matter how many source trees you have, all the classes will be built to the same folder, the output folder, which you can choose at the bot- tom of this pane.
3 Select the Libraries tab. Eclipse lists the external *.jar files and class folders—that is, folders containing loose class files—where the Java compiler currently looks for classes during compilation.
4 Press Add Variable. Eclipse lists all available Classpath Variables. These variables point to various locations on the local file system and allow you to install JUnit to any location you choose without having to change the build path of every project that depends on it.
5 Select JUNIT_JAR, and then press OK.
Eclipse adds JUNIT_JAR to the list of *.jar files on the project’s build path.
6 Select the Order and Export tab.
Eclipse shows the order in which locations on the build path are evaluated. When searching for a class at build time, Eclipse starts at the top of the list, then works its way to the bottom, so that classes from libraries near the top of the list are used before classes from libraries near the bottom of the list.
TE AM FL Y
Team-Fly®
101 Build tests using Eclipse
Now that you have added JUnit to your project’s Java Build Path, simply configure your source trees and your build output folder as you need for your project. By default, Eclipse suggests naming your directories “source” and “classes” for each Java project. Much of the time, these settings suffice.
If you follow our recommendations in recipe 3.2, then you will have separate Eclipse projects for your production code and each kind of test. In that case, use the Projects tab in your project’s Java Build Path properties to include your pro- duction code project in the build path of each test code project. You may need to select multiple production code projects for a test project containing End-to-End Tests that use classes from the entire system.
◆ Discussion
Eclipse simplifies managing the build-time class path (or Java Build Path, which is probably a better term to use, anyway) by providing intuitive dialogs for adding projects and external *.jar files through Classpath Variables. We are generally quite happy with the features that Eclipse’s Java Development Toolkit (JDT) pro- vides; however, there is one minor feature missing.
We have recommended you have separate source and build trees for your pro- duction code and each kind of test you intend to write. This implies multiple source folders and multiple build output folders, a configuration that the Eclipse JDT does not enable by default within a single Eclipse project. You need to change the properties for each Eclipse project to enable different output folders for each source folder. Consult the Eclipse documentation for details.
◆ Related
■ 3.2—Create a separate source tree for test code
■ 3.9—Build tests using Ant
7 Select JUNIT_JAR from the list and then press Up repeat- edly until JUNIT_JAR comes directly after JRE_LIB, the Java Runtime Environment.
This step is optional, but it’s useful if your project includes extensions to JUnit that may conflict with classes in JUnit itself.
Extensions to JUnit should not attempt to change the JUnit framework, but if you need to use such an extension, this is the way to cope with that unfortunate situation.
8 Press OK. Eclipse rebuilds your project using the changes to the Java Build Path. You return to the workbench.
Table 3.1 Adding JUnit to an Eclipse project’s Java Build Path (continued)
Action Result
102
Managing test suites
This chapter covers
■ Manually collecting tests into custom test suites
■ Automatically collecting tests into different kinds of test suites
■ Ordering and filtering tests in test suites
■ Using Parameterized Test Cases to build a data-driven test suite
103 Managing test suites
In JUnit, the smallest unit of “test execution” is the test suite. JUnit doesn’t actu- ally execute individual tests, but only executes test suites, so in order to execute your tests, you need to collect them into a test suite. The recipes in this chapter describe different ways to create and manage test suites.
The simplest test suite to create consists of all the tests in a test case class. This is so simple that JUnit does it for you. See recipe 4.1, “Let JUnit build your test suite.” If you need to create your test suites by hand, go to recipe 4.2, “Collect a specific set of tests.” If you have data-driven tests and don’t want to write by hand a bunch of test methods that simply use your test data, see recipe 4.8, “Build a data- driven test suite.” After that you’ll probably want to move your test data outside the code. For that, see recipe 4.9, “Define a test suite in XML.”
Building a test suite from a single test case class is just the beginning. The real power of JUnit comes from its ability to build arbitrarily complex test suites. Start with recipe 4.3, “Collect all the tests in a package,” and then move on to recipe 4.4, “Col- lect all the tests for your entire system” so that you can execute all your tests at once.
After a while, though, you’ll want to build these large test suites automatically.
See recipe 4.5, “Scan the file system for tests.” You may even want to categorize your tests and run the tests in a given category as one suite. For that, see recipe 4.6,
“Separate the different kinds of test suites.”
Finally there are times when you need some control over the tests in your test suite, but you don’t want the burden of keeping track of every single test. In that case, see recipe 4.7, “Control the order of some of your tests” to find out how to gain just the control that you need.
In this chapter we concentrate on building the test suites without discussing exactly how to run them. This topic is complex enough without test runners get- ting in the way. We will assume that the goal is to build a single test suite so that even the simplest test runners can execute it. We will talk more about how to exe- cute your tests in Chapter 6, “Running JUnit Tests.”