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

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

# Class Funtest

java.lang.Object
org.apache.tools.ant.ProjectComponent
org.apache.tools.ant.Task
org.apache.tools.ant.taskdefs.optional.testing.Funtest

All Implemented Interfaces:
  `Cloneable`

public class Funtest extends Task
Task to provide functional testing under Ant, with a fairly complex workflow of:

- Conditional execution
- Application to start
- A probe to "waitfor" before running tests
- A tests sequence
- A reporting sequence that runs after the tests have finished
- A "teardown" clause that runs after the rest.
- Automated termination of the program it executes, if a timeout is not met
- Checking of a failure property and automatic raising of a fault (with the text in failureText) if test shutdown and reporting succeeded

The task is designed to be framework neutral; it will work with JUnit, TestNG and other test frameworks That can be executed from Ant. It bears a resemblance to the FunctionalTest task from SmartFrog, as the attribute names were chosen to make migration easier. However, this task benefits from the ability to tweak Ant's internals, and so simplify the workflow, and from the experience of using the SmartFrog task. No code has been shared.

Since:
  Ant 1.8

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `APPLICATION_EXCEPTION`
  Application exception : "Application Exception"
  `static final String`
  `APPLICATION_FORCIBLY_SHUT_DOWN`
  "Application forcibly shut down"
  `static final String`
  `SHUTDOWN_INTERRUPTED`
  "Shutdown interrupted"
  `static final String`
  `SKIPPING_TESTS`
  "Condition failed -skipping tests"
  `static final String`
  `TEARDOWN_EXCEPTION`
  Teardown exception : "Teardown Exception"
  `static final String`
  `WARN_OVERRIDING`
  "Overriding previous definition of "

  ### Fields inherited from class org.apache.tools.ant.Task

  `target, taskName, taskType, wrapper`

  ### Fields inherited from class org.apache.tools.ant.ProjectComponent

  `description, location, project`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Funtest()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addApplication(Sequential sequence)`
  Add an application.
  `void`
  `addBlock(BlockFor sequence)`
  Add a block.
  `void`
  `addReporting(Sequential sequence)`
  set reporting sequence of tasks.
  `void`
  `addSetup(Sequential sequence)`
  Add a setup sequence.
  `void`
  `addTeardown(Sequential sequence)`
  set teardown sequence of tasks.
  `void`
  `addTests(Sequential sequence)`
  add tests.
  `ConditionBase`
  `createCondition()`
  Add a condition element.
  `void`
  `execute()`
  Run the functional test sequence.
  `BuildException`
  `getApplicationException()`
  Get the application exception.
  `BuildException`
  `getTaskException()`
  Get the task exception.
  `BuildException`
  `getTeardownException()`
  Get the teardown exception.
  `BuildException`
  `getTestException()`
  Get the test exception.
  `protected void`
  `ignoringThrowable(String type, Throwable thrown)`
  log that we are ignoring something rather than rethrowing it.
  `protected void`
  `processExceptions()`
  Now faults are analysed.
  `void`
  `setFailOnTeardownErrors(boolean failOnTeardownErrors)`
  Set the failOnTeardownErrors attribute.
  `void`
  `setFailureMessage(String failureMessage)`
  Set the failureMessage attribute.
  `void`
  `setFailureProperty(String failureProperty)`
  Set the failureProperty attribute.
  `void`
  `setShutdownTime(long shutdownTime)`
  Set the shutdownTime attribute.
  `void`
  `setShutdownUnit(WaitFor.Unit unit)`
  Set the shutdownunit attribute.
  `void`
  `setTimeout(long timeout)`
  Set the timeout attribute.
  `void`
  `setTimeoutUnit(WaitFor.Unit unit)`
  Set the timeoutunit attribute.

  ### Methods inherited from class org.apache.tools.ant.Task

  `bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskName, getTaskType, getWrapper, handleErrorFlush, handleErrorOutput, handleFlush, handleInput, handleOutput, init, isInvalid, log, log, log, log, maybeConfigure, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType`

  ### Methods inherited from class org.apache.tools.ant.ProjectComponent

  `clone, getDescription, getLocation, getProject, setDescription, setLocation, setProject`

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

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

- ## Field Details

  - ### WARN_OVERRIDING

    public static final String WARN_OVERRIDING
    "Overriding previous definition of "
    See Also:
      - Constant Field Values

  - ### APPLICATION_FORCIBLY_SHUT_DOWN

    public static final String APPLICATION_FORCIBLY_SHUT_DOWN
    "Application forcibly shut down"
    See Also:
      - Constant Field Values

  - ### SHUTDOWN_INTERRUPTED

    public static final String SHUTDOWN_INTERRUPTED
    "Shutdown interrupted"
    See Also:
      - Constant Field Values

  - ### SKIPPING_TESTS

    public static final String SKIPPING_TESTS
    "Condition failed -skipping tests"
    See Also:
      - Constant Field Values

  - ### APPLICATION_EXCEPTION

    public static final String APPLICATION_EXCEPTION
    Application exception : "Application Exception"
    See Also:
      - Constant Field Values

  - ### TEARDOWN_EXCEPTION

    public static final String TEARDOWN_EXCEPTION
    Teardown exception : "Teardown Exception"
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### Funtest

    public Funtest()

- ## Method Details

  - ### createCondition

    public ConditionBase createCondition()
    Add a condition element.
    Returns:
      `ConditionBase`.
    Since:
      Ant 1.6.2

  - ### addApplication

    public void addApplication(Sequential sequence)
    Add an application.
    Parameters:
      `sequence` - the application to add.

  - ### addSetup

    public void addSetup(Sequential sequence)
    Add a setup sequence.
    Parameters:
      `sequence` - the setup sequence to add.

  - ### addBlock

    public void addBlock(BlockFor sequence)
    Add a block.
    Parameters:
      `sequence` - the block for to add.

  - ### addTests

    public void addTests(Sequential sequence)
    add tests.
    Parameters:
      `sequence` - a sequence to add.

  - ### addReporting

    public void addReporting(Sequential sequence)
    set reporting sequence of tasks.
    Parameters:
      `sequence` - a reporting sequence to use.

  - ### addTeardown

    public void addTeardown(Sequential sequence)
    set teardown sequence of tasks.
    Parameters:
      `sequence` - a teardown sequence to use.

  - ### setFailOnTeardownErrors

    public void setFailOnTeardownErrors(boolean failOnTeardownErrors)
    Set the failOnTeardownErrors attribute.
    Parameters:
      `failOnTeardownErrors` - the value to use.

  - ### setFailureMessage

    public void setFailureMessage(String failureMessage)
    Set the failureMessage attribute.
    Parameters:
      `failureMessage` - the value to use.

  - ### setFailureProperty

    public void setFailureProperty(String failureProperty)
    Set the failureProperty attribute.
    Parameters:
      `failureProperty` - the value to use.

  - ### setShutdownTime

    public void setShutdownTime(long shutdownTime)
    Set the shutdownTime attribute.
    Parameters:
      `shutdownTime` - the value to use.

  - ### setTimeout

    public void setTimeout(long timeout)
    Set the timeout attribute.
    Parameters:
      `timeout` - the value to use.

  - ### setTimeoutUnit

    public void setTimeoutUnit(WaitFor.Unit unit)
    Set the timeoutunit attribute.
    Parameters:
      `unit` - the value to use.

  - ### setShutdownUnit

    public void setShutdownUnit(WaitFor.Unit unit)
    Set the shutdownunit attribute.
    Parameters:
      `unit` - the value to use.

  - ### getApplicationException

    public BuildException getApplicationException()
    Get the application exception.
    Returns:
      the application exception.

  - ### getTeardownException

    public BuildException getTeardownException()
    Get the teardown exception.
    Returns:
      the teardown exception.

  - ### getTestException

    public BuildException getTestException()
    Get the test exception.
    Returns:
      the test exception.

  - ### getTaskException

    public BuildException getTaskException()
    Get the task exception.
    Returns:
      the task exception.

  - ### execute

    public void execute() throws BuildException
    Run the functional test sequence.

    This is a fairly complex workflow -what is going on is that we try to clean up no matter how the run ended, and to retain the innermost exception that got thrown during cleanup. That is, if teardown fails after the tests themselves failed, it is the test failing that is more important.

    Overrides:
      `execute` in class `Task`
    Throws:
      `BuildException` - if something was caught during the run or teardown.

  - ### processExceptions

    protected void processExceptions()
    Now faults are analysed.

    The priority is

    1. testexceptions, except those indicating a build timeout when the application itself failed. (Because often it is the application fault that is more interesting than the probe failure, which is usually triggered by the application not starting.)
    2. Application exceptions (above test timeout exceptions)
    3. Teardown exceptions -except when they are being ignored
    4. Test failures as indicated by the failure property

  - ### ignoringThrowable

    protected void ignoringThrowable(String type, Throwable thrown)
    log that we are ignoring something rather than rethrowing it.
    Parameters:
      `type` - name of exception
      `thrown` - what was thrown