ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bode...@apache.org
Subject svn commit: r424603 - in /ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit: AntUnit.java AntUnitListener.java AssertTask.java LogCapturer.java LogContains.java PlainAntUnitListener.java
Date Sat, 22 Jul 2006 16:56:02 GMT
Author: bodewig
Date: Sat Jul 22 09:56:01 2006
New Revision: 424603

URL: http://svn.apache.org/viewvc?rev=424603&view=rev
Log:
provide a bit more documentation

Modified:
    ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/AntUnit.java
    ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/AntUnitListener.java
    ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/AssertTask.java
    ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/LogCapturer.java
    ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/LogContains.java
    ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/PlainAntUnitListener.java

Modified: ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/AntUnit.java
URL: http://svn.apache.org/viewvc/ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/AntUnit.java?rev=424603&r1=424602&r2=424603&view=diff
==============================================================================
--- ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/AntUnit.java (original)
+++ ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/AntUnit.java Sat Jul 22 09:56:01
2006
@@ -1,5 +1,5 @@
 /*
- * Copyright 2005 The Apache Software Foundation
+ * Copyright 2005-2006 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -46,30 +46,75 @@
  */
 public class AntUnit extends Task {
 
+    /**
+     * name of the magic setUp target.
+     */
     private static final String SETUP = "setUp";
+    /**
+     * prefix that identifies test targets.
+     */
     private static final String TEST = "test";
+    /**
+     * name of the magic tearDown target.
+     */
     private static final String TEARDOWN = "tearDown";
 
+    /**
+     * The build files to process.
+     */
     private ArrayList filesets = new ArrayList();
+
+    /**
+     * project instance for the build file currently under test.
+     */
     private Project newProject;
 
+    /**
+     * listeners.
+     */
     private ArrayList listeners = new ArrayList();
 
+    /**
+     * has a failure occured?
+     */
     private int failures=0;
+    /**
+     * has an error occured?
+     */
     private int errors=0;
+    /**
+     * stop testing if an error or failure occurs?
+     */
     private boolean failOnError=true;
+
+    /**
+     * Message to print if an error or failure occured.
+     */
     public static final String ERROR_TESTS_FAILED = "Tests failed with ";
-    public static final String ERROR_NO_FILESET = "You must specify at least one nested"
-                            + " fileset.";
 
+    /**
+     * Message if no tests have been specified.
+     */
+    public static final String ERROR_NO_FILESET =
+        "You must specify at least one nested fileset.";
+
+    /**
+     * adds build files to run as tests.
+     */
     public void add(FileSet fs) {
         filesets.add(fs);
     }
 
+    /**
+     * Adds a test listener.
+     */
     public void add(AntUnitListener al) {
         listeners.add(al);
     }
 
+    /**
+     * stop testing if an error or failure occurs?
+     */
     public void setFailOnError(boolean failOnError) {
         this.failOnError = failOnError;
     }
@@ -90,6 +135,9 @@
         }
     }
 
+    /**
+     * Processes a fileset.
+     */
     private void doFileSet(FileSet fs) {
         DirectoryScanner ds = fs.getDirectoryScanner(getProject());
         File fromDir = fs.getDir(getProject());
@@ -99,7 +147,11 @@
         }
     }
 
+    /**
+     * Processes a single build file.
+     */
     private void doFile(File f) {
+        // setup project instance
         newProject = new Project();
         newProject.setDefaultInputStream(getProject().getDefaultInputStream());
         newProject.setJavaVersionProperty();
@@ -107,10 +159,16 @@
         getProject().initSubProject(newProject);
         newProject.setUserProperty("ant.file" , f.getAbsolutePath());
         attachListeners(f, newProject);
+
+        // read build file
         ProjectHelper.configureProject(newProject, f);
+
+        // find targets
         Map targets = newProject.getTargets();
         Target setUp = (Target) targets.get(SETUP);
         Target tearDown = (Target) targets.get(TEARDOWN);
+
+        // start test
         newProject.fireBuildStarted();
         Throwable caught = null;
         try {
@@ -131,6 +189,10 @@
                     } catch (BuildException e) {
                         BuildException orig = e;
                         boolean failed = false;
+
+                        // try to see whether the BuildException masks
+                        // an AssertionFailedException.  if so, treat
+                        // it as failure instead of error.
                         Throwable t = e.getCause();
                         while (t != null && t instanceof BuildException) {
                             if (t instanceof AssertionFailedException) {
@@ -140,10 +202,12 @@
                             }
                             t = ((BuildException) t).getCause();
                         }
+
                         if (!failed) {
                             fireError(name, e);
                         }
                     } finally {
+                        // clean up
                         if (tearDown != null) {
                             newProject.executeTarget(TEARDOWN);
                         }
@@ -158,6 +222,9 @@
         }
     }
         
+    /**
+     * Redirect output to new project instance.
+     */
     public void handleOutput(String outputToHandle) {
         if (newProject != null) {
             newProject.demuxOutput(outputToHandle, false);
@@ -166,6 +233,9 @@
         }
     }
 
+    /**
+     * Redirect input to new project instance.
+     */
     public int handleInput(byte[] buffer, int offset, int length)
         throws IOException {
         if (newProject != null) {
@@ -174,6 +244,9 @@
         return super.handleInput(buffer, offset, length);
     }
 
+    /**
+     * Redirect flush to new project instance.
+     */
     public void handleFlush(String toFlush) {
         if (newProject != null) {
             newProject.demuxFlush(toFlush, false);
@@ -182,6 +255,9 @@
         }
     }
 
+    /**
+     * Redirect error output to new project instance.
+     */
     public void handleErrorOutput(String errorOutputToHandle) {
         if (newProject != null) {
             newProject.demuxOutput(errorOutputToHandle, true);
@@ -190,6 +266,9 @@
         }
     }
 
+    /**
+     * Redirect error flush to new project instance.
+     */
     public void handleErrorFlush(String errorOutputToFlush) {
         if (newProject != null) {
             newProject.demuxFlush(errorOutputToFlush, true);
@@ -198,6 +277,10 @@
         }
     }
 
+    /**
+     * Wraps all registered test listeners in BuildListeners and
+     * attaches them to the new project instance.
+     */
     private void attachListeners(File buildFile, Project p) {
         Iterator it = listeners.iterator();
         while (it.hasNext()) {
@@ -208,6 +291,9 @@
         }
     }
 
+    /**
+     * invokes addFailure on all registered test listeners.
+     */
     private void fireFail(String targetName, AssertionFailedException ae) {
         failures++;
         Iterator it = listeners.iterator();
@@ -217,6 +303,9 @@
         }
     }
 
+    /**
+     * invokes addError on all registered test listeners.
+     */
     private void fireError(String targetName, Throwable t) {
         errors++;
         Iterator it = listeners.iterator();
@@ -226,14 +315,19 @@
         }
     }
 
+    /**
+     * Adapts AntUnitListener to BuildListener.
+     */
     private class BuildToAntUnitListener implements BuildListener {
         private String buildFile;
         private AntUnitListener a;
+
         BuildToAntUnitListener(String buildFile, AntUnitListener a) {
             this.buildFile = buildFile;
             this.a = a;
             a.setOutput(new LogOutputStream(AntUnit.this, Project.MSG_INFO));
         }
+
         public void buildStarted(BuildEvent event) {
             a.startTestSuite(buildFile);
         }

Modified: ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/AntUnitListener.java
URL: http://svn.apache.org/viewvc/ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/AntUnitListener.java?rev=424603&r1=424602&r2=424603&view=diff
==============================================================================
--- ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/AntUnitListener.java (original)
+++ ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/AntUnitListener.java Sat Jul
22 09:56:01 2006
@@ -1,5 +1,5 @@
 /*
- * Copyright 2005 The Apache Software Foundation
+ * Copyright 2005-2006 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -23,12 +23,36 @@
  * A test listener for <antunit>.
  */
 public interface AntUnitListener {
+    /**
+     * Sets the stream the listener shall write its output to.
+     *
+     * <p>Usually points to Ant's logging system.</p>
+     */
     void setOutput(OutputStream out);
 
+    /**
+     * Invoked once per build file, before any targets get executed.
+     */
     void startTestSuite(String buildFile);
+    /**
+     * Invoked once per build file, after all targets have been executed.
+     */
     void endTestSuite(String buildFile);
+    /**
+     * Invoked before a test target gets executed.
+     */
     void startTest(String target);
+    /**
+     * Invoked after a test target has been executed.
+     */
     void endTest(String target);
+    /**
+     * Invoked if an assert tasked caused an error during execution.
+     */
     void addFailure(String target, AssertionFailedException ae);
+    /**
+     * Invoked if any error other than a failed assertion occured
+     * during execution.
+     */
     void addError(String target, Throwable ae);
 }

Modified: ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/AssertTask.java
URL: http://svn.apache.org/viewvc/ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/AssertTask.java?rev=424603&r1=424602&r2=424603&view=diff
==============================================================================
--- ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/AssertTask.java (original)
+++ ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/AssertTask.java Sat Jul 22 09:56:01
2006
@@ -1,5 +1,5 @@
 /*
- * Copyright  2005 The Apache Software Foundation
+ * Copyright 2005-2006 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -47,8 +47,14 @@
  */
 public class AssertTask extends ConditionBase {
 
+    /**
+     * Message to use when the assertion fails.
+     */
     private String message = AssertionFailedException.DEFAULT_MESSAGE;
 
+    /**
+     * Message to use when the assertion fails.
+     */
     public void setMessage(String value) {
         this.message = value;
     }

Modified: ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/LogCapturer.java
URL: http://svn.apache.org/viewvc/ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/LogCapturer.java?rev=424603&r1=424602&r2=424603&view=diff
==============================================================================
--- ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/LogCapturer.java (original)
+++ ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/LogCapturer.java Sat Jul 22
09:56:01 2006
@@ -23,9 +23,9 @@
 
 /**
  * Captures log messages generated during an antunit task run and
- * makes it available to tasks via a project reference.
+ * makes them available to tasks via a project reference.
  *
- * <p>This class captures all messaged generated during the build and
+ * <p>This class captures all messages generated during the build and
  * adds itself as project reference to the project using the id
  * <code>ant.antunit.log</code>.</p>
  */

Modified: ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/LogContains.java
URL: http://svn.apache.org/viewvc/ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/LogContains.java?rev=424603&r1=424602&r2=424603&view=diff
==============================================================================
--- ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/LogContains.java (original)
+++ ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/LogContains.java Sat Jul 22
09:56:01 2006
@@ -1,5 +1,5 @@
 /*
- * Copyright 2005 The Apache Software Foundation
+ * Copyright 2005-2006 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -26,16 +26,25 @@
 /**
  * A condition that tests the log output of the current project for a
  * given string.
+ *
+ * <p>Works in conjunction with {@link LogCapturer LogCapturer} and
+ * needs the context provided by AntUnit.</p>
  */
 public class LogContains extends ProjectComponent implements Condition {
 
     private String text;
     private int logLevel = Project.MSG_INFO;
 
+    /**
+     * Test the log shall contain.
+     */
     public void setText(String t) {
         text = t;
     }
 
+    /**
+     * minimal log priority to consult.
+     */
     public void setLevel(Echo.EchoLevel echoLevel) {
         logLevel = echoLevel.getLevel();
     }

Modified: ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/PlainAntUnitListener.java
URL: http://svn.apache.org/viewvc/ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/PlainAntUnitListener.java?rev=424603&r1=424602&r2=424603&view=diff
==============================================================================
--- ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/PlainAntUnitListener.java (original)
+++ ant/antlibs/antunit/trunk/src/main/org/apache/ant/antunit/PlainAntUnitListener.java Sat
Jul 22 09:56:01 2006
@@ -26,7 +26,8 @@
 import org.apache.tools.ant.BuildException;
 
 /**
- * A test listener for &lt;antunit&gt;.
+ * A test listener for &lt;antunit&gt; modeled aftern the Plain JUnit
+ * test listener that is part of Ant.
  */
 public class PlainAntUnitListener implements AntUnitListener {
     /**
@@ -44,7 +45,13 @@
      */
     private PrintWriter wri;
 
+    /**
+     * keeps track of the numer of executed targets, the failures an errors.
+     */
     private int runCount, failureCount, errorCount;
+    /**
+     * time for the starts of the current test-suite and test-target.
+     */
     private long start, testStart;
 
     public void setOutput(OutputStream out) {
@@ -85,23 +92,6 @@
         sb.append(" sec");
         sb.append(newLine);
 
-//        // append the err and output streams to the log
-//        if (systemOutput != null && systemOutput.length() > 0) {
-//            sb.append("------------- Standard Output ---------------")
-//                .append(newLine)
-//                .append(systemOutput)
-//                .append("------------- ---------------- ---------------")
-//                .append(newLine);
-//        }
-//
-//        if (systemError != null && systemError.length() > 0) {
-//            sb.append("------------- Standard Error -----------------")
-//                .append(newLine)
-//                .append(systemError)
-//                .append("------------- ---------------- ---------------")
-//                .append(newLine);
-//        }
-
         if (out != null) {
             try {
                 out.write(sb.toString().getBytes());
@@ -131,6 +121,7 @@
         double seconds = (System.currentTimeMillis() - testStart) / 1000.0;
         wri.println(" took " + nf.format(seconds) + " sec");
     }
+
     public void addFailure(String target, AssertionFailedException ae) {
         failureCount++;
         formatError("\tFAILED", ae);



---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org


Mime
View raw message