JUnitTestRunner (Apache Ant API)
Description: declaration: package: org.apache.tools.ant.taskdefs.optional.junit, class: JUnitTestRunner

Package org.apache.tools.ant.taskdefs.optional.junit

# Class JUnitTestRunner

java.lang.Object
org.apache.tools.ant.taskdefs.optional.junit.JUnitTestRunner

All Implemented Interfaces:
  `junit.framework.TestListener`, `JUnitTaskMirror.JUnitTestRunnerMirror`

public class JUnitTestRunner extends Object implements junit.framework.TestListener, JUnitTaskMirror.JUnitTestRunnerMirror
Simple Testrunner for JUnit that runs all tests of a testsuite.

This TestRunner expects a name of a TestCase class as its argument. If this class provides a static suite() method it will be called and the resulting Test will be run. So, the signature should be

         public static junit.framework.Test suite()

If no such method exists, all public methods starting with "test" and taking no argument will be run.

Summary output is generated at the end.

Since:
  Ant 1.2

- ## Field Summary

  ### Fields inherited from interface org.apache.tools.ant.taskdefs.optional.junit.JUnitTaskMirror.JUnitTestRunnerMirror

  `ERRORS, FAILURES, IGNORED_FILE_NAME, SUCCESS`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `JUnitTestRunner(JUnitTest test, boolean haltOnError, boolean filtertrace, boolean haltOnFailure)`
  Constructor for fork=true or when the user hasn't specified a classpath.
  `JUnitTestRunner(JUnitTest test, boolean haltOnError, boolean filtertrace, boolean haltOnFailure, boolean showOutput)`
  Constructor for fork=true or when the user hasn't specified a classpath.
  `JUnitTestRunner(JUnitTest test, boolean haltOnError, boolean filtertrace, boolean haltOnFailure, boolean showOutput, boolean logTestListenerEvents)`
  Constructor for fork=true or when the user hasn't specified a classpath.
  `JUnitTestRunner(JUnitTest test, boolean haltOnError, boolean filtertrace, boolean haltOnFailure, boolean showOutput, boolean logTestListenerEvents, ClassLoader loader)`
  Constructor to use when the user has specified a classpath.
  `JUnitTestRunner(JUnitTest test, boolean haltOnError, boolean filtertrace, boolean haltOnFailure, boolean showOutput, ClassLoader loader)`
  Constructor to use when the user has specified a classpath.
  `JUnitTestRunner(JUnitTest test, boolean haltOnError, boolean filtertrace, boolean haltOnFailure, ClassLoader loader)`
  Constructor to use when the user has specified a classpath.
  `JUnitTestRunner(JUnitTest test, String[] methods, boolean haltOnError, boolean filtertrace, boolean haltOnFailure, boolean showOutput, boolean logTestListenerEvents)`
  Constructor for fork=true or when the user hasn't specified a classpath.
  `JUnitTestRunner(JUnitTest test, String[] methods, boolean haltOnError, boolean filtertrace, boolean haltOnFailure, boolean showOutput, boolean logTestListenerEvents, ClassLoader loader)`
  Constructor to use when the user has specified a classpath.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addError(junit.framework.Test test, Throwable t)`
  Interface TestListener.
  `void`
  `addFailure(junit.framework.Test test, Throwable t)`
  Interface TestListener for JUnit <= 3.4.
  `void`
  `addFailure(junit.framework.Test test, junit.framework.AssertionFailedError t)`
  Interface TestListener for JUnit > 3.4.
  `void`
  `addFormatter(JUnitResultFormatter f)`
  Add a formatter.
  `void`
  `addFormatter(JUnitTaskMirror.JUnitResultFormatterMirror f)`
  Add a formatter to the test.
  `void`
  `endTest(junit.framework.Test test)`
  Interface TestListener.
  `static String`
  `filterStack(String stack)`
  Filters stack frames from internal JUnit and Ant classes
  `static String`
  `getFilteredTrace(Throwable t)`
  Returns a filtered stack trace.
  `int`
  `getRetCode()`
  Returns what System.exit() would return in the standalone version.
  `void`
  `handleErrorFlush(String output)`
  Handle output sent to System.err.
  `void`
  `handleErrorOutput(String output)`
  Handle output sent to System.err.
  `void`
  `handleFlush(String output)`
  Handle output sent to System.out.
  `int`
  `handleInput(byte[] buffer, int offset, int length)`
  Handle input.
  `void`
  `handleOutput(String output)`
  Handle a string destined for standard output.
  `static void`
  `main(String[] args)`
  Entry point for standalone (forked) mode.
  `void`
  `run()`
  Run the test.
  `void`
  `setPermissions(Permissions permissions)`
  Permissions for the test run.
  `void`
  `startTest(junit.framework.Test t)`
  Interface TestListener.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### JUnitTestRunner

    public JUnitTestRunner(JUnitTest test, boolean haltOnError, boolean filtertrace, boolean haltOnFailure)
    Constructor for fork=true or when the user hasn't specified a classpath.
    Parameters:
      `test` - the test to run.
      `haltOnError` - whether to stop the run if an error is found.
      `filtertrace` - whether to filter junit.*.* stack frames out of exceptions
      `haltOnFailure` - whether to stop the run if failure is found.

  - ### JUnitTestRunner

    public JUnitTestRunner(JUnitTest test, boolean haltOnError, boolean filtertrace, boolean haltOnFailure, boolean showOutput)
    Constructor for fork=true or when the user hasn't specified a classpath.
    Parameters:
      `test` - the test to run.
      `haltOnError` - whether to stop the run if an error is found.
      `filtertrace` - whether to filter junit.*.* stack frames out of exceptions
      `haltOnFailure` - whether to stop the run if failure is found.
      `showOutput` - whether to send output to System.out/.err as well as formatters.

  - ### JUnitTestRunner

    public JUnitTestRunner(JUnitTest test, boolean haltOnError, boolean filtertrace, boolean haltOnFailure, boolean showOutput, boolean logTestListenerEvents)
    Constructor for fork=true or when the user hasn't specified a classpath.
    Parameters:
      `test` - the test to run.
      `haltOnError` - whether to stop the run if an error is found.
      `filtertrace` - whether to filter junit.*.* stack frames out of exceptions
      `haltOnFailure` - whether to stop the run if failure is found.
      `showOutput` - whether to send output to System.out/.err as well as formatters.
      `logTestListenerEvents` - whether to print TestListener events.
    Since:
      Ant 1.7

  - ### JUnitTestRunner

    public JUnitTestRunner(JUnitTest test, String[] methods, boolean haltOnError, boolean filtertrace, boolean haltOnFailure, boolean showOutput, boolean logTestListenerEvents)
    Constructor for fork=true or when the user hasn't specified a classpath.
    Parameters:
      `test` - the test to run.
      `methods` - names of methods of the test to be executed.
      `haltOnError` - whether to stop the run if an error is found.
      `filtertrace` - whether to filter junit.*.* stack frames out of exceptions
      `haltOnFailure` - whether to stop the run if failure is found.
      `showOutput` - whether to send output to System.out/.err as well as formatters.
      `logTestListenerEvents` - whether to print TestListener events.
    Since:
      1.8.2

  - ### JUnitTestRunner

    public JUnitTestRunner(JUnitTest test, boolean haltOnError, boolean filtertrace, boolean haltOnFailure, ClassLoader loader)
    Constructor to use when the user has specified a classpath.
    Parameters:
      `test` - the test to run.
      `haltOnError` - whether to stop the run if an error is found.
      `filtertrace` - whether to filter junit.*.* stack frames out of exceptions
      `haltOnFailure` - whether to stop the run if failure is found.
      `loader` - the classloader to use running the test.

  - ### JUnitTestRunner

    public JUnitTestRunner(JUnitTest test, boolean haltOnError, boolean filtertrace, boolean haltOnFailure, boolean showOutput, ClassLoader loader)
    Constructor to use when the user has specified a classpath.
    Parameters:
      `test` - the test to run.
      `haltOnError` - whether to stop the run if an error is found.
      `filtertrace` - whether to filter junit.*.* stack frames out of exceptions
      `haltOnFailure` - whether to stop the run if failure is found.
      `showOutput` - whether to send output to System.out/.err as well as formatters.
      `loader` - the classloader to use running the test.

  - ### JUnitTestRunner

    public JUnitTestRunner(JUnitTest test, boolean haltOnError, boolean filtertrace, boolean haltOnFailure, boolean showOutput, boolean logTestListenerEvents, ClassLoader loader)
    Constructor to use when the user has specified a classpath.
    Parameters:
      `test` - the test to run.
      `haltOnError` - whether to stop the run if an error is found.
      `filtertrace` - whether to filter junit.*.* stack frames out of exceptions
      `haltOnFailure` - whether to stop the run if failure is found.
      `showOutput` - whether to send output to System.out/.err as well as formatters.
      `logTestListenerEvents` - whether to print TestListener events.
      `loader` - the classloader to use running the test.
    Since:
      Ant 1.7

  - ### JUnitTestRunner

    public JUnitTestRunner(JUnitTest test, String[] methods, boolean haltOnError, boolean filtertrace, boolean haltOnFailure, boolean showOutput, boolean logTestListenerEvents, ClassLoader loader)
    Constructor to use when the user has specified a classpath.
    Parameters:
      `test` - JUnitTest
      `methods` - String[]
      `haltOnError` - boolean
      `filtertrace` - boolean
      `haltOnFailure` - boolean
      `showOutput` - boolean
      `logTestListenerEvents` - boolean
      `loader` - ClassLoader
    Since:
      1.8.2

- ## Method Details

  - ### run

    public void run()
    Run the test.
    Specified by:
      `run` in interface `JUnitTaskMirror.JUnitTestRunnerMirror`

  - ### getRetCode

    public int getRetCode()
    Returns what System.exit() would return in the standalone version.
    Specified by:
      `getRetCode` in interface `JUnitTaskMirror.JUnitTestRunnerMirror`
    Returns:
      2 if errors occurred, 1 if tests failed else 0.

  - ### startTest

    public void startTest(junit.framework.Test t)
    Interface TestListener.

    A new Test is started.

    Specified by:
      `startTest` in interface `junit.framework.TestListener`
    Parameters:
      `t` - the test.

  - ### endTest

    public void endTest(junit.framework.Test test)
    Interface TestListener.

    A Test is finished.

    Specified by:
      `endTest` in interface `junit.framework.TestListener`
    Parameters:
      `test` - the test.

  - ### addFailure

    public void addFailure(junit.framework.Test test, Throwable t)
    Interface TestListener for JUnit <= 3.4.

    A Test failed.

    Parameters:
      `test` - the test.
      `t` - the exception thrown by the test.

  - ### addFailure

    public void addFailure(junit.framework.Test test, junit.framework.AssertionFailedError t)
    Interface TestListener for JUnit > 3.4.

    A Test failed.

    Specified by:
      `addFailure` in interface `junit.framework.TestListener`
    Parameters:
      `test` - the test.
      `t` - the assertion thrown by the test.

  - ### addError

    public void addError(junit.framework.Test test, Throwable t)
    Interface TestListener.

    An error occurred while running the test.

    Specified by:
      `addError` in interface `junit.framework.TestListener`
    Parameters:
      `test` - the test.
      `t` - the error thrown by the test.

  - ### setPermissions

    public void setPermissions(Permissions permissions)
    Permissions for the test run.
    Specified by:
      `setPermissions` in interface `JUnitTaskMirror.JUnitTestRunnerMirror`
    Parameters:
      `permissions` - the permissions to use.
    Since:
      Ant 1.6

  - ### handleOutput

    public void handleOutput(String output)
    Handle a string destined for standard output.
    Specified by:
      `handleOutput` in interface `JUnitTaskMirror.JUnitTestRunnerMirror`
    Parameters:
      `output` - the string to output

  - ### handleInput

    public int handleInput(byte[] buffer, int offset, int length) throws IOException
    Handle input.
    Specified by:
      `handleInput` in interface `JUnitTaskMirror.JUnitTestRunnerMirror`
    Parameters:
      `buffer` - not used.
      `offset` - not used.
      `length` - not used.
    Returns:
      -1 always.
    Throws:
      `IOException` - never.
    Since:
      Ant 1.6
    See Also:
      - `Task.handleInput(byte[], int, int)`

  - ### handleErrorOutput

    public void handleErrorOutput(String output)
    Handle output sent to System.err..
    Specified by:
      `handleErrorOutput` in interface `JUnitTaskMirror.JUnitTestRunnerMirror`
    Parameters:
      `output` - output for System.err

  - ### handleFlush

    public void handleFlush(String output)
    Handle output sent to System.out..
    Specified by:
      `handleFlush` in interface `JUnitTaskMirror.JUnitTestRunnerMirror`
    Parameters:
      `output` - output for System.out.

  - ### handleErrorFlush

    public void handleErrorFlush(String output)
    Handle output sent to System.err..
    Specified by:
      `handleErrorFlush` in interface `JUnitTaskMirror.JUnitTestRunnerMirror`
    Parameters:
      `output` - coming from System.err

  - ### addFormatter

    public void addFormatter(JUnitResultFormatter f)
    Add a formatter.
    Parameters:
      `f` - the formatter to add.

  - ### addFormatter

    public void addFormatter(JUnitTaskMirror.JUnitResultFormatterMirror f)
    Add a formatter to the test..
    Specified by:
      `addFormatter` in interface `JUnitTaskMirror.JUnitTestRunnerMirror`
    Parameters:
      `f` - the formatter to use.

  - ### main

    public static void main(String[] args) throws IOException
    Entry point for standalone (forked) mode.

    Parameters: testcaseclassname plus parameters in the format key=value, none of which is required.

    Test runner attributes
    key | description | default value
    --- | --- | ---
    haltOnError | halt test on errors? | false
    haltOnFailure | halt test on failures? | false
    formatter | A JUnitResultFormatter given as classname,filename. If filename is omitted, System.out is assumed. | none
    showoutput | send output to System.err/.out as well as to the formatters? | false
    logtestlistenerevents | log TestListener events to System.out. | false
    methods | Comma-separated list of names of individual test methods to execute. | null

    Parameters:
      `args` - the command line arguments.
    Throws:
      `IOException` - on error.

  - ### getFilteredTrace

    public static String getFilteredTrace(Throwable t)
    Returns a filtered stack trace. This is ripped out of junit.runner.BaseTestRunner.
    Parameters:
      `t` - the exception to filter.
    Returns:
      the filtered stack trace.

  - ### filterStack

    public static String filterStack(String stack)
    Filters stack frames from internal JUnit and Ant classes
    Parameters:
      `stack` - the stack trace to filter.
    Returns:
      the filtered stack.