5.2.1 Ant, indispensable Ant

Transcription

1 5.2.1 Ant, indispensale Ant Apahe s Ant produt ( is a uild tool that lets you easily ompile and test appliations (among other things). It is the de fato standard for uilding Java appliations. One reason for Ant s popularity is that it is more than a tool: Ant is a framework for running tools. In addition to using Ant to onfigure and launh a Java ompiler, you an use it to generate ode, invoke JDBC queries, and, as you will see, run JUnit test suites. Like many modern projets, Ant is onfigured through an XML doument. This doument is referred to as the uildfile and is named uild.xml y default. The Ant uildfile desries eah task that you want to apply on your projet. A task might e ompiling Java soure ode, generating Javados, transferring files, querying dataases, or running tests. A uildfile an have several targets, or entry points, so that you an run a single task or hain several together. Let s look at using Ant to automatially run tests as part of the uild proess. If (gasp!) you don t have Ant installed, see the following sidears. For full details, onsult the Ant manual ( Installing Ant on Windows To install Ant on Windows, follow these steps: 1 Unzip the Zip distriution file to a diretory on your omputer system (for example, C:\Ant). 2 Under this diretory, Unzip reates a sudiretory for the Ant distriution you downloaded for example, C:\Ant\jakarta-ant Add an ANT_HOME variale to your environment with this diretory as the value. For example: Variale Name: ANT_HOME Variale Value: C:\Ant\jakarta-ant Edit your system s PATH environment variale to inlude the ANT_HOME\in folder: Variale Name: PATH Variale Value: %ANT_HOME%\in;

2 92 CHAPTER 5 Automating JUnit Installing Ant on Windows (ontinued) 4 We reommend that you also speify the loation of your Java Developer s Kit (JDK) as the JAVA_HOME environment variale: Variale Name: JAVA_HOME Variale Value: C:\j2sdk1.4.2 This value, like the others, may vary depending on where you installed the JDK on your system. 5 To enale Ant s JUnit task, you must put junit.jar in the ANT_HOME\li folder. Installing Ant on UNIX (ash) To install Ant on UNIX (or Linux), follow these steps: 1 Untar the Ant tarall to a diretory on your omputer system (for example, /opt/ant). 2 Under this diretory, tar reates a sudiretory for the Ant distriution you downloaded for example, /opt/ant/jakarta-ant Add this sudiretory to your environment as ANT_HOME. For example: export ANT_HOME=/opt/ant/jakarta-ant Add the ANT_HOME/in folder to your system s ommand path: export PATH=${PATH}:${ANT_HOME}/in 4 We reommend that you also speify the loation of your JDK as the JAVA_HOME environment variale: export JAVA_HOME=/usr/java/j2sdk To enale Ant s JUnit task, you must put junit.jar in the ANT_HOME/ li folder Ant targets, projets, properties, and tasks When you uild a software projet, you are often interested in more than just inary ode. For a final distriution, you may want to generate Javados along with the inary lasses. For an interim ompile during development, you may skip that step. Sometimes, you want to run a lean uild from srath. Other times, you want to uild the lasses that have hanged. To help you manage the uild proess, Ant lets you reate a uildfile for eah of your projets. The uildfile may have several targets, enapsulating the different

3 Running tests from Ant 93 tasks needed to reate your appliation and related resoures. To make the uildfiles easier to onfigure and reuse, Ant lets you define dynami property elements. These Ant essentials are as follows: Buildfile Eah uildfile is usually assoiated with a partiular development projet. Ant uses the projet XML tag as the outermost element in uild.xml. The projet element defines a projet. It also lets you speify a default target, so you an run Ant without any parameters. Target When you run Ant, you an speify one or more targets for it to uild. Targets an also delare that they depend on other targets. If you ask Ant to run one target, the uildfile might run several others first. This lets you reate a distriution target that depends on other targets like lean, ompile, javado, and war. Property elements Many of the targets within a projet will share the same settings. Ant lets you reate property elements to enapsulate speifi settings and reuse them throughout your uildfile. If a uildfile is arefully written, the property elements an make it easy to adapt the uildfile to a new environment. To refer to a property within a uildfile, you plae the property within a speial notation: ${property}. To refer to the property named target.dir, you would write ${target.dir}. As mentioned, Ant is not so muh a tool as a framework for running tools. You an use property elements to set the parameters a tool needs and a task to run the tool. A great numer of tasks ome undled with Ant, and you an also write your own. For more aout developing with Ant, we highly reommend Java Development with Ant. 2 Listing 5.1 shows the top of the uildfile for the sampling projet from hapter 3. This segment of the uildfile sets the default target and the properties your tasks will use. Listing 5.1 The Ant uildfile projet and property elements <projet name="sampling" default="test"> <property file="uild.properties"/> <property name="sr.dir" loation="sr"/> <property name="sr.java.dir" loation="${sr.dir}/java"/> d 2 Erik Hather and Steve Loughran, Java Development with Ant (Greenwih, CT: Manning, 2003);

4 94 CHAPTER 5 Automating JUnit <property name="sr.test.dir" loation="${sr.dir}/test"/> <property name="target.dir" loation="target"/> <property name="target.lasses.java.dir" loation="${target.dir}/lasses/java"/> <property name="target.lasses.test.dir" loation="${target.dir}/lasses/test"/> [...] e d e Give the projet the name sampling and set the default target to test. (The test target appears in listing 5.3.) You inlude a uild.properties file. This file ontains Ant properties that may need to e hanged on a user s system eause they depend on the exeuting environment. For example, these properties an inlude the loations of redistriutale jars. Beause programmers may store jars in different loations, it is good pratie to use a uild.properties file to define them. Many open soure projets provide a uild.properties.sample file you an opy as uild.properties and then edit to math your environment. For this projet, you won t need to define any properties in it. As you will see, your targets need to know the loation of your prodution and test soure ode. You use the Ant property task to define these values so that they an e reused and easily hanged. At d, you define properties related to the soure tree; at e, you define those related to the output tree (where the uild-generated files will go). Notie that you use different properties to define where the ompiled prodution and tests lasses will e put. Putting them in different diretories is a good pratie eause it allows you to easily pakage the prodution lasses in a jar without mixing test lasses. An interesting thing aout Ant properties is that they are immutale one they are set, they annot e modified. For example, if any properties are redefined after the uild.properties file is loaded, the new value is ignored. The first definition always wins The java task For simple jos, running the Java Compiler (java) from the ommand line is easy enough. But for multipakage produts, the are and feeding of java and your lasspath eomes a Herulean task. Ant s java task tames the ompiler and its lasspath, making uilding projets effortless and automati.

5 Running tests from Ant 95 The Ant java task is usually employed from within a target with a name like ompile. Before and after running the java task, you an perform any needed file management as part of the target. The java task lets you set any of the standard options, inluding the destination diretory. You an also supply a list of paths for your soure files. The latter is handy for projets with tests, eause you may tend to keep prodution lasses in one folder and test lasses in another. Listing 5.2 shows the ompile targets that all the Java Compiler for the sampling projet, oth for the prodution ode and for the test ode. Listing 5.2 The uildfile ompile targets <target name="ompile.java"> <mkdir dir="${target.lasses.java.dir}"/> <java destdir="${target.lasses.java.dir}"> <sr path="${sr.java.dir}"/> </java> <target name="ompile.test" depends="ompile.java"> <mkdir dir="${target.lasses.test.dir}"/> <java destdir="${target.lasses.test.dir}"> <sr path="${sr.test.dir}"/> <lasspath> <pathelement loation="${target.lasses.java.dir}"/> </lasspath> </java> d e <target name="ompile" depends="ompile.java,ompile.test"/> f g h d e f Delare the target to ompile the java prodution soures, naming it ompile.java. Ensure that the diretory where you will generate your prodution lass files exists. Ant resolves the property you set at the top of the uildfile (see listing 5.1) and inserts it in plae of the variale notation ${target.lasses.java.dir}. If the diretory already exists, Ant quietly ontinues. Call the Java Compiler (java) and pass it the destination diretory to use. Tell the java task what soures to ompile. Compile the test soures exatly the same way you just did for the prodution soures. Your ompile.test target has a dependeny on the ompile.java target, so you must add a depends element to that ompile.test target definition (depends="ompile.java"). You may have notied that you don t expliitly add the JUnit jar to the lasspath. Rememer that when you installed Ant, you put the JUnit

6 96 CHAPTER 5 Automating JUnit g h jar in ANT_HOME/li (this is neessary in order to use the junit Ant task). As a onsequene, junit.jar is already on your lasspath, and you don t need to speify it in the java task to properly ompile your tests. You need to add a nested lasspath element in order to add the prodution lasses you just ompiled to the lasspath. This is eause test lasses all prodution lasses. Create a ompile target that automatially alls the ompile.java and ompile.test targets The JUnit task In hapter 3, you ran the DefaultController tests y hand. That meant etween any hanges, you had to Compile the soure ode Run the TestDefaultController test ase against the ompiled lasses You an get Ant to perform oth these steps as part of the same uild target. Listing 5.3 shows the test target for the sampling uildfile. Listing 5.3 The uildfile test target <target name="test" depends="ompile"> <junit printsummary="yes" haltonerror="yes" haltonfailure="yes" fork="yes"> <formatter type="plain" usefile="false"/> d <test name="junitook.sampling.testdefaultcontroller"/> e <lasspath> f <pathelement loation="${target.lasses.java.dir}"/> <pathelement loation="${target.lasses.test.dir}"/> </lasspath> </junit> </projet> Give the target a name and delare that it relies on the ompile target. If you ask Ant to run the test target, it will run the ompile target efore running test. Here you get into the JUnit-speifi attriutes. The printsummary attriute says to render a one-line summary at the end of the test. By setting fork to yes, you fore Ant to use a separate Java Virtual Mahine (JVM) for eah test. This is always a good pratie as it avoids interferenes etween test ases. The haltonfailure and haltonerror attriutes say that the uild should stop if any test returns a

7 Running tests from Ant 97 d e f failure or an error (an error is an unexpeted error, whereas a failure happens if one of the test asserts does not pass). Configure the junit task formatter to use plain text and output the test result to the onsole. Provide the lass name of the test you want to run. Extend the lasspath to use for this task to inlude the lasses you just ompiled Putting Ant to the task Now that you ve assemled the uildfile, you an run it from the ommand line y hanging to your projet diretory and entering ant. Figure 5.1 shows what Ant renders in response. You an now uild and test the sampling projet all at the same time. If any of the tests fail, the haltonfailure/haltonerror settings will stop the uild, ringing the failure to your attention. Figure 5.1 Running the uildfile from the ommand line

8 98 CHAPTER 5 Automating JUnit Running optional tasks The junit task is one of several omponents undled in Ant s optional.jar. The optional.jar file should already e in your ANT_HOME/li diretory. Ant does not undle a opy of JUnit, so you must e sure that junit.jar is on your system lasspath or in the ANT_HOME/li diretory. (The optional.jar file is for tasks that depend on another pakage, like JUnit.) For more aout installing Ant, see the sidears on pages If you have any troule running the Ant uildfiles presented in this hapter, make sure the Ant optional.jar is in the ANT_HOME/li folder and junit.jar is either on your system lasspath or also in the ANT_HOME/li folder. The empty lasspath Given a tool like Ant, many developers don t other with a system lasspath anymore: You an let Ant take are of all that. Ant s lasspath element makes it easy to uild the lasspath you need when you need it. The only lind spot is the jars you need in order to run one of the optional Ant tasks, like junit. To provide the flexiility you need for other irumstanes, Ant uses Sun s delegation model to reate whatever lasspath you need at runtime. In the ase of the optional tasks, there s a ootstrap issue. To employ a task, whatever liraries a task needs must e on the same lasspath as the ode for the task. This means you need to load junit.jar in the same plae you load optional.jar. Meanwhile, you also need to load the task (and any external liraries) efore you an use the task in your uildfile. In short, you an t speify the path to junit.jar as part of the junit task. The simplest solution is to move junit.jar to ANT_HOME/li. There are alternative onfigurations, ut they are usually more troule than they are worth. 3 So, to keep a lean lasspath and use optional tasks like JUnit, you should move the jar for the external lirary to ANT_HOME/li. Ant will then automatially load optional.jar and the external liraries together, enaling use of the optional tasks in your uildfiles. Just rememer to update junit.jar in ANT_HOME/li whenever you install a new version of either Ant or JUnit Pretty printing with JUnitReport A report like the one in figure 5.1 is fine when you are running tests interatively. But what if you want to run a test suite and review the results later? For 3 Ant 1.6 will let you put optional task jars in plaes other than ANT_HOME/li.

9 Running tests from Ant 99 Figure 5.2 Output of the junitreport Ant task example, the tests might e run automatially every day y a ron jo (whether you liked it or not!). Another optional Ant task, junitreport, is designed to output the result of the tests as XML. To finish the jo, junitreport renders the XML into HTML using an XSL stylesheet. The result is an attrative and funtional report that you (or your oss) an peruse with any rowser. A junitreport page for the sampling projet is shown in figure 5.2. Listing 5.4 shows the hanges (in old) neessary in the uildfile to generate this report. To exeute the sript, type ant report on the ommand line in the sampling projet. Listing 5.4 Adding a JUnitReport task to the uildfile <projet name="sampling" default="test"> [...] <property name="target.report.dir" loation="${target.dir}/report"/> [...] <target name="test" depends="ompile"> <mkdir dir="${target.report.dir}"/> <junit printsummary="yes" haltonerror="yes" haltonfailure="yes" fork="yes"> <formatter type="plain" usefile="false"/> <formatter type="xml"/> d <test name="junitook.sampling.testdefaultcontroller"

10 100 CHAPTER 5 Automating JUnit todir="${target.report.dir}"/> <lasspath> <pathelement loation="${target.lasses.java.dir}"/> <pathelement loation="${target.lasses.test.dir}"/> </lasspath> </junit> <target name="report" depends="test"> <mkdir dir="${target.report.dir}/html"/> <junitreport todir="${target.report.dir}"> <fileset dir="${target.report.dir}"> <inlude name="test-*.xml"/> </fileset> <report todir="${target.report.dir}/html"/> </junitreport> </projet> e i f g h j d e f g h i j Define a property holding the target loation where your reports will e generated. Create that diretory. You need to modify the junit task so that it outputs the test results as XML. The junitreport task works y transforming the XML test result into an HTML report. Tell the junit task to reate a report file in the ${target.report.dir} diretory. Introdue a new report target that generates the HTML report. You egin y reating the diretory where the HTML will e generated. Call the junitreport task to reate the report. The junitreport task works y sanning the list of XML test results you speify as an Ant fileset. Tell the junitreport task where to generate the HTML report Automatially finding the tests to run The uildfile you have written is using the test element of the junit task to tell JUnit what test to exeute. Although this is fine when there are only a few test ases, it eomes tiresome when your test suite grows. The iggest issue then eomes ensuring that you haven t forgotten to inlude a test in the uildfile. Fortunately, the junit task has a onvenient athtest element that lets you speify test ases using wildards. Listing 5.5 shows how to use it (hanges from listing 5.4 are shown in old).

11 Running tests from Ant 101 Listing 5.5 A etter uildfile using athtest <projet name="sampling" default="test"> [...] <target name="test" depends="ompile"> <mkdir dir="${target.report.dir}"/> <property name="tests" value="test*"/> <junit printsummary="yes" haltonerror="yes" haltonfailure="yes" fork="yes"> <formatter type="plain" usefile="false"/> <formatter type="xml"/> <athtest todir="${target.report.dir}"> <fileset dir="${sr.test.dir}"> <inlude name="**/${tests}.java"/> <exlude name="**/test*all.java"/> </fileset> </athtest> <lasspath> <pathelement loation="${target.lasses.java.dir}"/> <pathelement loation="${target.lasses.test.dir}"/> </lasspath> </junit> [...] <target name="lean"> <delete dir="${target.dir}"/> d </projet> You may wonder why you define a property here when you ould have put the wildards diretly into the fileset element at. Using this trik, you an define the tests property on the ommand line and run a single test (or a speifi set of tests) instead. This is an easy way to run a test against the lass you are working on right now. Of ourse, one it s working, you still run the full test suite to e sure everyone is on the same page. Here is an example that only exeutes the TestDefaultController test ase: d ant Dtests=TestDefaultController test You improve the uildfile y making the test target more flexile. Whereas efore you had to expliitly name the different tests you wanted to exeute, here you leverage the junit task s nested athtest element. With athtest, you an speify the test to run as a fileset, thus allowing the use of wildards. Add the always-useful lean target to remove all uild-generated files. Doing so lets you start with a fresh uild with no side effets from osolete lasses. Typially, a dist target that generates the projet distriutale depends on the lean target.

12 102 CHAPTER 5 Automating JUnit Are automated unit tests a panaea? Asolutely not! Automated tests an find a signifiant numer of ugs, ut manual testing is still required to find as many ugs as possile. In general, automated regression tests ath 15 30% of all ugs found; manual testing finds the other 70 85% ( Are you sure aout that? Some test-first design / unit testing enthusiasts are now reporting remarkaly low numers of ug ounts, on the order of one or two per month or fewer. But these results need to e sustantiated y formal studies and repliated y other teams. Your mileage will definitely vary.