java junit api_Junit task API

看到一个很全的Junit task API

http://ant.apache.org/manual/Tasks/junit.html

Description

This task runs tests from the JUnit testing framework. The

latest version of the framework can be found at http://www.junit.org. This task has been

tested with JUnit 3.0 up to JUnit 3.8.2; it won't work with

versions prior to JUnit 3.0. It also works with JUnit 4.0,

including "pure" JUnit 4 tests using only annotations and no

JUnit4TestAdapter.

Note: This task depends on external libraries

not included in the Apache Ant distribution. See Library

Dependencies for more information.

Note: You must have junit.jar

available. You can do one of:

Put both junit.jar and ant-junit.jar

in ANT_HOME/lib.

Do not put either in ANT_HOME/lib, and instead

include their locations in your CLASSPATH environment

variable.

Add both JARs to your classpath using -lib.

Specify the locations of both JARs using a element in a in the

build file.

Leave ant-junit.jar in its default location in

ANT_HOME/lib but include junit.jar in the

passed to . (since Ant 1.7)

See the FAQ for details.

Tests are defined by nested test or

batchtest tags (see nested

elements).

Parameters

Attribute

Description

Required

printsummary

Print one-line statistics for each testcase. Can

take the values on, off, and

withOutAndErr. withOutAndErr is the same

as on but also includes the output of the test as

written to System.out and

System.err.

No; default is

off.

fork

Run the tests in a separate VM.

No; default is

off.

forkmode

Controls how many Java Virtual Machines get

created if you want to fork some tests. Possible values are

"perTest" (the default), "perBatch" and "once". "once" creates only

a single Java VM for all tests while "perTest" creates a new VM for

each TestCase class. "perBatch" creates a VM for each nested and

one collecting all nested s. Note that only tests with the same

settings of filtertrace, haltonerror,

haltonfailure, errorproperty and

failureproperty can share a VM, so even if you set

forkmode to "once", Ant may have to create more than a

single Java VM. This attribute is ignored for tests that don't get

forked into a new Java VM. since Ant 1.6.2

No; default is

perTest.

haltonerror

Stop the build process if an error occurs during

the test run.

No; default is

off.

errorproperty

The name of a property to set in the event of an

error.

No

haltonfailure

Stop the build process if a test fails (errors are

considered failures as well).

No; default is

off.

failureproperty

The name of a property to set in the event of a

failure (errors are considered failures as well).

No.

filtertrace

Filter out Junit and Ant stack frames from error

and failure stack traces.

No; default is

on.

timeout

Cancel the individual tests if they don't finish

in the given time (measured in milliseconds). Ignored if

fork is disabled. When running multiple tests inside

the same Java VM (see forkMode), timeout applies to the time that

all tests use together, not to an individual test.

No

maxmemory

Maximum amount of memory to allocate to the forked

VM. Ignored if fork is disabled.

Note: If you get java.lang.OutOfMemoryError:

Java heap space in some of your tests then you need to raise

the size like maxmemory="128m"

No

jvm

The command used to invoke the Java Virtual

Machine, default is 'java'. The command is resolved by

java.lang.Runtime.exec(). Ignored if fork

is disabled.

No; default is

java.

dir

The directory in which to invoke the VM. Ignored

if fork is disabled.

No

newenvironment

Do not propagate the old environment when new

environment variables are specified. Ignored if fork

is disabled.

No; default is

false.

includeantruntime

Implicitly add the Ant classes required to run the

tests and JUnit to the classpath in forked mode.

No; default is

true.

showoutput

Send any output generated by tests to Ant's

logging system as well as to the formatters. By default only the

formatters receive the output.

No

outputtoformatters

Since Ant 1.7.0.

Send any output generated by tests to the test formatters. This is

"true" by default.

No

tempdir

Where Ant should place temporary files. Since

Ant 1.6.

No; default is the project's base

directory.

reloading

Whether or not a new classloader should be

instantiated for each test case.

Ignore if fork is set to true. Since Ant

1.6.

No; default is

true.

clonevm

If set to true true, then all system properties

and the bootclasspath of the forked Java Virtual Machine will be

the same as those of the Java VM running Ant. Default is "false"

(ignored if fork is disabled). since Ant 1.7

No

logfailedtests

When Ant executes multiple tests and doesn't stop

on errors or failures it will log a "FAILED" message for each

failing test to its logging system. If you set this option to

false, the message will not be logged and you have to rely on the

formatter output to find the failing tests. since Ant

1.8.0

No

enableTestListenerEvents

Whether Ant should send fine grained information

about the running tests to Ant's logging system at the verbose

level. Such events may be used by custom test listeners to show the

progress of tests.

Defaults to false.

Can be overridden by a magic property.

since Ant 1.8.2 - Ant 1.7.0 to 1.8.1 behave as if

this attribute was true by default.

No

By using the errorproperty and

failureproperty attributes, it is possible to perform

setup work (such as starting an external server), execute the test,

clean up, and still fail the build in the event of a failure.

The filtertrace attribute condenses error and

failure stack traces before reporting them. It works with both the

plain and XML formatters. It filters out any lines that begin with

the following string patterns:

"junit.framework.TestCase"

"junit.framework.TestResult"

"junit.framework.TestSuite"

"junit.framework.Assert."

"junit.swingui.TestRunner"

"junit.awtui.TestRunner"

"junit.textui.TestRunner"

"java.lang.reflect.Method.invoke("

"sun.reflect."

"org.apache.tools.ant."

"org.junit."

"junit.framework.JUnit4TestAdapter"

" more"

The task supports a nested element that represents a PATH like

structure.

As of Ant 1.7, this classpath may be used to refer to

junit.jar as well as your tests and the tested

code.

jvmarg

If fork is enabled, additional parameters may be

passed to the new VM via nested elements. For example:

...

would run the test in a VM without JIT.

allows all attributes described in Command-line

Arguments.

sysproperty

Use nested elements to specify system properties required by the

class. These properties will be made available to the VM during the

execution of the test (either ANT's VM or the forked VM, if

fork is enabled). The attributes for this element are

the same as for environment

variables.

...

would run the test in ANT's VM and make the basedir

property available to the test.

syspropertyset

You can specify a set of properties to be used as system

properties with syspropertysets.

since Ant 1.6.

env

It is possible to specify environment variables to pass to the

forked VM via nested elements. For a description of the element's

attributes, see the description in the exec

task.

Settings will be ignored if fork is disabled.

bootclasspath

The location of bootstrap class files can be specified using

this PATH

like structure - will be ignored if fork is not

true or the target VM doesn't support it (i.e. Java

1.1).

since Ant 1.6.

permissions

Security permissions can be revoked and granted during the

execution of the class via a nested permissions element. For

more information please see permissions

Settings will be ignored if fork is enabled.

since Ant 1.6.

assertions

You can control enablement of Java 1.4 assertions with an

subelement.

Assertion statements are currently ignored in non-forked

mode.

since Ant 1.6.

formatter

The results of the tests can be printed in different formats.

Output will always be sent to a file, unless you set the

usefile attribute to false. The name of

the file is determined by the name of the test and can be set by

the outfile attribute of .

There are four predefined formatters - one prints the test

results in XML format, the other emits plain text. The formatter

named brief will only print detailed information for

testcases that failed, while plain gives a little

statistics line for all test cases. Custom formatters that need to

implement

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

can be specified.

If you use the XML formatter, it may not include the same output

that your tests have written as some characters are illegal in XML

documents and will be dropped.

The fourth formatter named failure (since Ant

1.8.0) collects all failing testXXX() methods and

creates a new TestCase which delegates only these

failing methods. The name and the location can be specified via

Java System property or Ant property

ant.junit.failureCollector. The value has to point to

the directory and the name of the resulting class (without suffix).

It defaults to java-tmp-dir/FailedTests.

Attribute

Description

Required

type

Use a predefined formatter (either

xml, plain, brief or

failure).

Exactly one of these.

classname

Name of a custom formatter class.

extension

Extension to append to the output filename.

Yes, if classname has been

used.

usefile

Boolean that determines whether output should be

sent to a file.

No; default is true.

if

No; default is true.

unless

No; default is true.

test

Defines a single test class.

Attribute

Description

Required

name

Name of the test class.

Yes

methods

Comma-separated list of names of test case methods

to execute. Since 1.8.2

The methods attribute can be useful in the

following scenarios:

A test method has failed and you want to re-run the test method

to test a fix or re-run the test under the Java debugger without

having to wait for the other (possibly long running) test methods

to complete.

One or more test methods are running slower than expected and

you want to re-run them under a Java profiler (without the overhead

of running the profiler whilst other test methods are being

executed).

If the methods attribute is used but no test method

is specified, then no test method from the suite will be

executed.

No; default is to run all test methods in the

suite.

fork

Run the tests in a separate VM. Overrides value

set in .

No

haltonerror

Stop the build process if an error occurs during

the test run. Overrides value set in .

No

errorproperty

The name of a property to set in the event of an

error. Overrides value set in .

No

haltonfailure

Stop the build process if a test fails (errors are

considered failures as well). Overrides value set in .

No

failureproperty

The name of a property to set in the event of a

failure (errors are considered failures as well). Overrides value

set in .

No

filtertrace

Filter out Junit and Ant stack frames from error

and failure stack traces. Overrides value set in .

No; default is

on.

todir

Directory to write the reports to.

No; default is the current

directory.

outfile

Base name of the test result. The full filename is

determined by this attribute and the extension of

formatter.

No; default is

TEST-name, where name is the name of

the test specified in the name attribute.

Tests can define their own formatters via nested elements.

batchtest

Define a number of tests based on pattern matching.

batchtest collects the included resources

from any number of nested Resource

Collections. It then generates a test class name for each

resource that ends in .java or

.class.

Any type of Resource Collection is supported as a nested

element, prior to Ant 1.7 only has been supported.

Attribute

Description

Required

fork

Run the tests in a separate VM. Overrides value

set in .

No

haltonerror

Stop the build process if an error occurs during

the test run. Overrides value set in .

No

errorproperty

The name of a property to set in the event of an

error. Overrides value set in .

No

haltonfailure

Stop the build process if a test fails (errors are

considered failures as well). Overrides value set in .

No

failureproperty

The name of a property to set in the event of a

failure (errors are considered failures as well). Overrides value

set in

No

filtertrace

Filter out Junit and Ant stack frames from error

and failure stack traces. Overrides value set in .

No; default is

on.

todir

Directory to write the reports to.

No; default is the current

directory.

Batchtests can define their own formatters via nested

elements.

Forked tests and tearDown

If a forked test runs into a timeout, Ant will terminate the

Java VM process it has created, which probably means the test's

tearDown method will never be called. The same is true

if the forked VM crashes for some other reason.

Starting with Ant 1.8.0, a special formatter is distributed with

Ant that tries to load the testcase that was in the forked VM and

invoke that class' tearDown method. This formatter has

the following limitations:

It runs in the same Java VM as Ant itself, this is a different

Java VM than the one that was executing the test and it may see a

different classloader (and thus may be unable to load the tast

class).

It cannot determine which test was run when the timeout/crash

occurred if the forked VM was running multiple test. I.e. the

formatter cannot work with any forkMode other than

perTest and it won't do anything if the test class

contains a suite() method.

If the formatter recognizes an incompatible

forkMode or a suite method or fails to

load the test class it will silently do nothing.

The formatter doesn't have any effect on tests that were not

forked or didn't cause timeouts or VM crashes.

To enable the formatter, add a formatter like

to your junit task.

Since Ant 1.8.2 the

enableTestListenerEvents attribute of the task

controls whether fine grained logging messages will be sent to the

task's verbose log. In addition to this attribute Ant will consult

the property ant.junit.enabletestlistenerevents and

the value of the property overrides the setting of the

attribute.

This property exists so that containers running Ant that depend

on the additional logging events can ensure they will be generated

even if the build file disables them.

Examples

Runs the test defined in my.test.TestCase in the

same VM. No output will be generated unless the test fails.

Runs the test defined in my.test.TestCase in a

separate VM. At the end of the test, a one-line summary will be

printed. A detailed report of the test can be found in

TEST-my.test.TestCase.txt. The build process will be

stopped if the test fails.

Runs my.test.TestCase in the same VM, ignoring the

given CLASSPATH; only a warning is printed if this test fails. In

addition to the plain text test results, for this test a XML result

will be output to result.xml. Then, for each matching

file in the directory defined for ${src.tests} a test

is run in a separate VM. If a test fails, the build process is

aborted. Results are collected in files named

TEST-name.txt and written to

${reports.tests}.

On the first run all tests are collected via the element. Its

plain formatter shows the output on the console. The

failure formatter creates a java source file in

${build.dir}/failingTests/FailedTests.java which

extends junit.framework.TestCase and returns from a

suite() method a test suite for the failing

tests.

On a second run the collector class exists and instead of the the

single will run. So only the failing test cases are re-run. The two

nested formatters are for displaying (for the user) and for

updating the collector class.