diff --git a/WHATSNEW b/WHATSNEW index 25d2d6540..c1fafc065 100644 --- a/WHATSNEW +++ b/WHATSNEW @@ -26,6 +26,16 @@ Changes that could break older environments: might lead to blocking or other undefined behavior. Bugzilla Report 56149 + * BuildFileTest and BaseSelectorTest have both been deprecated in + favour of BuildFileRule and BaseSelectorRule respectively, and the + tests that previously extended these base tests have been converted to + JUnit 4 tests using the new "rule"s. Any external test that sub-classed + a test in the Ant workspace, rather than BuildFileTest, will need + changed to either use JUnit4's annotations, or be modified to + extend BuildFileTest directly. This will not affect any tests that are + being executed by Ant's junit or batchtest tasks that are not specifically + testing Ant's code. + Fixed bugs: ----------- diff --git a/manual/Types/selectors-program.html b/manual/Types/selectors-program.html index 8e16b0338..074a54263 100644 --- a/manual/Types/selectors-program.html +++ b/manual/Types/selectors-program.html @@ -140,78 +140,58 @@

For a robust component (and selectors are (Project)Components) tests are necessary. For testing Tasks we use JUnit TestCases - more specific - org.apache.tools.ant.BuildFileTest extends junit.framework.TestCase. + org.apache.tools.ant.BuildFileRule extends org.junit.rules.ExternalResource. Some of its features like configure the (test) project by reading its buildfile and - execute targets we need for selector tests also. Therefore we use that BuildFileTest. + execute targets we need for selector tests also. Therefore we use that BuildFileRule. But testing selectors requires some more work: having a set of files, instantiate and configure the selector, check the selection work and more. Because we usually extend BaseExtendSelector its features have to be tested also (e.g. setError()).

-

That's why we have a base class for doing our selector tests: - org.apache.tools.ant.types.selectors.BaseSelectorTest.

+

That's why we have a test rule for doing our selector tests: + org.apache.tools.ant.types.selectors.BaseSelectorRule.

-

This class extends TestCase and therefore can included in the set of Ant's - unit tests. It holds an instance of preconfigured BuildFileTest. Configuration - is done by parsing the src/etc/testcases/types/selectors.xml. BaseSelectorTest +

This class extends ExternalResource and therefore can included in the set of Ant's + unit tests. It holds an instance of preconfigured BuildFileRule. Configuration + is done by parsing the src/etc/testcases/types/selectors.xml. BaseSelectorRule then gives us helper methods for handling multiple selections.

Because the term "testcase" or "testenvironment" are so often used, this - special testenvironment got a new name: bed. Like you initialize the - test environment by calling setUp() and cleaning by calling tearDown() (or like - to make your bed before go sleeping) you have to do that work with your - bed by calling makeBed() respective cleanupBed().

+ special testenvironment got a new name: bed. The setup and cleanup of + the bed is all handled by the BaseSelectorRule so any test only has to handle + the actual test scenarios

-

A usual test scenario is

    -
  1. make the bed
    2. +

    A usual test scenario is:

    +
    1. instantiate the selector
    2. configure the selector
    3. let the selector do some work
    4. verify the work
      5. -
    5. clean the bed
      6. -
    -

    +
+ -

For common way of instantiation you have to override the getInstance() - simply by returning a new object of your selector. For easier "selection and verification work" - BaseSelectorTest provides the method performTests() which - iterates over all files (and directories) in the String array filenames - and checks whether the given selector returns the expected result. If an error - occurred (especially the selector does not return the expected result) the test - fails and the failing filenames are logged.

An example test would be:

 package org.apache.tools.ant.types.selectors;
 
-public class MySelectorTest extends BaseSelectorTest {
-
-    public MySelectorTest(String name) {
-        super(name);
-    }
+public class MySelectorTest {
 
-    public BaseSelector getInstance() {
-        return new MySelector();
-    }
+    @Rule
+    public final BaseSelectorRule selectorRule = new BaseSelectorRule();
 
+    @Test
     public void testCase1() {
-        try {
-            // initialize test environment 'bed'
-            makeBed();
-
-            // Configure the selector
-            MySelector s = (MySelector)getSelector();
-            s.addParam("key1", "value1");
-            s.addParam("key2", "value2");
-            s.setXX(true);
-            s.setYY("a value");
-
-            // do the tests
-            performTests(s, "FTTTTTTTTTTT");  // First is not selected - rest is
-
-        } finally {
-            // cleanup the environment
-            cleanupBed();
-        }
+
+
+        // Configure the selector
+        MySelector s = new MySelector();
+        s.addParam("key1", "value1");
+        s.addParam("key2", "value2");
+        s.setXX(true);
+        s.setYY("a value");
+
+        // do the tests
+        assertEquals("FTTTTTTTT", selectorRule.selectionString(s));
     }
 }
diff --git a/manual/tutorial-tasks-filesets-properties.html b/manual/tutorial-tasks-filesets-properties.html index 5ba08f6ef..fdbe1be5b 100644 --- a/manual/tutorial-tasks-filesets-properties.html +++ b/manual/tutorial-tasks-filesets-properties.html @@ -135,20 +135,28 @@ to them, sorry :-)

we can call that from our testcase: 
-import org.apache.tools.ant.BuildFileTest;
+import org.junit.Rule;
+import org.junit.Test;
+import org.junit.Before;
+import org.junit.Assert;
+import org.apache.tools.ant.BuildFileRule;
 
-public class FindTest extends BuildFileTest {
 
-    public FindTest(String name) {
-        super(name);
-    }
+public class FindTest {
+
+    @Rule
+    public final BuildFileRule buildRule = new BuildFileRule();
 
+
+    @Before
     public void setUp() {
         configureProject("build.xml");
     }
 
+    @Test
     public void testSimple() {
-        expectLog("use.simple", "test-value");
+        buildRule.executeTarget("useSimgle");
+        Assert.assertEquals("test-value", buildRule.getLog());
     }
 }
@@ -211,10 +219,14 @@ Maybe you find some more testcases. But this is enough for now.
For each of these points we create a testXX method.

-public class FindTest extends BuildFileTest {
+public class FindTest {
+
+    @Rule
+    public final BuildFileRule buildRule = new BuildFileRule();
 
     ... // constructor, setUp as above
 
+    @Test
     public void testMissingFile() {
         Find find = new Find();
         try {
@@ -227,6 +239,7 @@ public class FindTest extends BuildFileTest {
         }
     }
 
+    @Test
     public void testMissingLocation() {
         Find find = new Find();
         find.setFile("ant.jar");
@@ -238,6 +251,7 @@ public class FindTest extends BuildFileTest {
         }
     }
 
+    @Test
     public void testMissingFileset() {
         Find find = new Find();
         find.setFile("ant.jar");
@@ -250,15 +264,17 @@ public class FindTest extends BuildFileTest {
         }
     }
 
+    @Test
     public void testFileNotPresent() {
-        executeTarget("testFileNotPresent");
-        String result = getProject().getProperty("location.ant-jar");
+        buildRule.executeTarget("testFileNotPresent");
+        String result = buildRule.getProject().getProperty("location.ant-jar");
         assertNull("Property set to wrong value.", result);
     }
 
+    @Test
     public void testFilePresent() {
-        executeTarget("testFilePresent");
-        String result = getProject().getProperty("location.ant-jar");
+        buildRule.executeTarget("testFilePresent");
+        String result = buildRule.getProject().getProperty("location.ant-jar");
         assertNotNull("Property not set.", result);
         assertTrue("Wrong file found.", result.endsWith("ant.jar"));
     }
@@ -906,7 +922,7 @@ entry. For both we need some information:

 
 
   attachments
-  all files needed to apply the path
+  all files needed to apply the path
   Archive containing a patch with the new and modified resources
 
 
diff --git a/manual/tutorial-writing-tasks.html b/manual/tutorial-writing-tasks.html
index c4881e949..c3b8a6a82 100644
--- a/manual/tutorial-writing-tasks.html
+++ b/manual/tutorial-writing-tasks.html
@@ -17,8 +17,7 @@
 
 
   Tutorial: Writing Tasks
-  
-  
+  
 
 
 
Tutorial: Writing Tasks

@@ -596,12 +595,9 @@ Next step: test ...
 
Test the Task

 
We have written a test already: the use.* tasks in the buildfile. But its
 difficult to test that automatically. Common (and in Ant) used is JUnit for
-that. For testing tasks Ant provides a baseclass org.apache.tools.ant.BuildFileTest.
-This class extends junit.framework.TestCase and can therefore be integrated
-into the unit tests. But this class provides some for testing tasks useful methods:
-initialize Ant, load a buildfile, execute targets,
-expecting BuildExceptions with a specified text, expect a special text
-in the output log ... 

+that. For testing tasks Ant provides a JUnit Rule org.apache.tools.ant.BuildFileRule.
+This class provides some for testing tasks useful methods:
+initialize Ant, load a buildfile, execute targets, capturing debug and run logs ...

 
 
In Ant it is usual that the testcase has the same name as the task with a prepending
 Test, therefore we will create a file HelloWorldTest.java. Because we
@@ -677,49 +673,68 @@ and <junitreport>. So we add to the buildfile:

 ...
-

Back to the src/HelloWorldTest.java. We create a class extending -BuildFileTest with String-constructor (JUnit-standard), a setUp() -method initializing Ant and for each testcase (targets use.*) a testXX() -method invoking that target.

+

Back to the src/HelloWorldTest.java. We create a class with a public +BuildFileRule field annotated with JUnit's @Rule annotation. As per +conventional JUnit4 tests, this class should have no constructors, or a default no-args +constructor, setup methods should be annotated with @Before, tear down methods +annotated with @After and any test method annotated with @Test. 

-import org.apache.tools.ant.BuildFileTest;
+import org.apache.tools.ant.BuildFileRule;
+import org.junit.Assert;
+import org.junit.Test;
+import org.junit.Before;
+import org.junit.Rule;
+import org.apache.tools.ant.AntAssert;
+import org.apache.tools.ant.BuildException;
 
-public class HelloWorldTest extends BuildFileTest {
+public class HelloWorldTest {
 
-    public HelloWorldTest(String s) {
-        super(s);
-    }
+    @Rule
+    public final BuildFileRule buildRule = new BuildFileRule();
 
+    @Before
     public void setUp() {
         // initialize Ant
-        configureProject("build.xml");
+        buildRule.configureProject("build.xml");
     }
 
+    @Test
     public void testWithout() {
-        executeTarget("use.without");
-        assertEquals("Message was logged but should not.", getLog(), "");
+        buildRule.executeTarget("use.without");
+        assertEquals("Message was logged but should not.", buildRule.getLog(), "");
     }
 
     public void testMessage() {
         // execute target 'use.nestedText' and expect a message
         // 'attribute-text' in the log
-        expectLog("use.message", "attribute-text");
+        buildRule.executeTarget("use.message");
+        Assert.assertEquals("attribute-text", buildRule.getLog());
     }
 
+    @Test
     public void testFail() {
         // execute target 'use.fail' and expect a BuildException
         // with text 'Fail requested.'
-        expectBuildException("use.fail", "Fail requested.");
+        try {
+           buildRule.executeTarget("use.fail");
+           fail("BuildException should have been thrown as task was set to fail");
+        } catch (BuildException ex) {
+            Assert.assertEquals("fail requested", ex.getMessage());
+        }
+
     }
 
+    @Test
     public void testNestedText() {
-        expectLog("use.nestedText", "nested-text");
+        buildRule.executeTarget("use.nestedText");
+        Assert.assertEquals("nested-text", buildRule.getLog());
     }
 
+    @Test
     public void testNestedElement() {
-        executeTarget("use.nestedElement");
-        assertLogContaining("Nested Element 1");
-        assertLogContaining("Nested Element 2");
+        buildRule.executeTarget("use.nestedElement");
+        AntAssert.assertContains("Nested Element 1", buildRule.getLog());
+        AntAssert.assertContains("Nested Element 2", buildRule.getLog());
     }
 }
@@ -790,14 +805,14 @@ The ZIP provided there contains