WLUnit

Description

This task runs tests from the JUnit testing framework against a running WebLogic server. It is meant to be compatible, in syntax and behavior, with the JUnit, wlrun, and wlstop tasks. The latest version of the JUnit framework can be found at http://www.junit.org. This task requires JUnit 3.0 or above. This task works for WebLogic 5.1 (6.0 support has not been carried over from wlrun and wlstop).

The task starts a WebLogic server process, then concurrently executes all specified JUnit tests in their own forked processes, and finally stops the server process and waits for it to exit. The task reports the results of the tests. Note that the server process is stopped no matter whether all the tests are actually run or whether the target reports failure.

Tests are defined by nested test or batchtest tags, see nested elements.

As a convenience, tests are given the JNDI system properties "java.naming.factory.initial" and "java.naming.provider.url", so that the test classes can create InitialContexts pointing to the started WebLogic server.

Parameters

Attribute Description Required
home Path of WebLogic's installation directory. Passed to the server JVM as the "weblogic.system.home" property. Yes
properties Path of the WebLogic server's global properties file. Relative to WebLogic home directory. Passed to server JVM as the "weblogic.system.propertiesFile" property. No, default is "weblogic.properties"
policy Path of the WebLogic server's security policy file. Relative to weblogic home directory. Passed to server JVM as the "java.security.policy" argument. No, default is "weblogic.policy"
url URL for the WebLogic server, e.g., "t3://localhost:7001" Yes
name Name of the WebLogic server within the WebLogic home which will be run. No, default is "myserver"
user Username for WebLogic admin account, e.g., "system". Admin account is used to shutdown the server. Yes
password Password for WebLogic admin account specified in the user parameter. Yes
startuppause Milliseconds to wait for WebLogic server to start before starting JUnit tests. No, default is 0
args Additional argument string passed to the Weblogic server. No
jvmargs Additional argument string passed to the WebLogic server JVM. No
printtestsummary Print one line statistics for each JUnit testcase. No, default is "off"
halttestsonerror Fail the target and abort further JUnit tests if any test has an error. No, default is "off"
halttestsonfailure Fail the target and abort further JUnit tests if any test fails (errors are considered failures as well). No, default is "off"
testtimeout Cancel the individual JUnit tests if they don't finish in the given time (measured in milliseconds). No
testsmaxmemory Max amount of memory to allocate to the JUnit test JVM(s). No
testsjvm Command used to invoke the JUnit test JVM(s). The command is resolved by java.lang.Runtime.exec(). No, default "java"
testsdir The directory in which the JUnit test JVM(s) will be executed. No

Nested Elements

wlunit supports the following nested classpath elements representing PATH like structures:

Typical targets will use all three classpaths, like this: 

<wlunit>
  <classpath path="/usr/local/weblogic/classes/boot"/>
  <wlclasspath>
    <pathelement location="/usr/local/weblogic/license"/>
    <pathelement location="/usr/local/weblogic/classes"/>
    <pathelement location="/usr/local/weblogic/lib/weblogicaux.jar"/>
  </wlclasspath>
  <testsclasspath>
    <pathelement path="${java.class.path}"/>
    <pathelement location="classes"/>
    <pathelement location="/usr/local/weblogic/classes"/>
    <pathelement location="/usr/local/weblogic/lib/weblogicaux.jar"/>
  </testsclasspath>
</wlunit>

testssysproperty

System properties may be passed to the JUnit test JVM(s) via nested <testssysproperty> attributes, for example:


<wlunit>
  <testssysproperty key="db.url" value="jdbc:oracle:thin:1521:@suki:testdb"/>
</wlunit>
would run the test with a "db.url" system property.

<testssysproperty> allows all attributes described in environment variables.

testsjvmarg

Additional parameters may be passed to the JUnit test JVM(s) via nested <testsjvmarg> attributes, for example:


<wlunit>
  <testsjvmarg value="-classic"/>
</wlunit>
would run the test in a JVM without Hot Spot.

<testsjvmarg> allows all attributes described in Command line arguments.

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 <test>.

There are two predefined formatters, one prints the test results in XML format, the other emits plain text. Custom formatters that need to implement org.apache.tools.ant.taskdefs.optional.junit.JUnitResultFormatter can be specified.

Attribute Description Required
type Use a predefined formatter (either "xml" or "plain"). 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 true.

test

Defines a single test class.

Attribute Description Required
name Name of the test class Yes
fork Deprecated. Run the tests in a separate VM. Overrides value set in <wlunit>. No
haltonerror Stop the build process if an error occurs during the test run. Overrides value set in <wlunit>. No
haltonfailure Stop the build process if a test fails (errors are considered failures as well). Overrides value set in <wlunit>. No
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 using the name attribute.
if Only run test if the named property is set. No
unless Only run test if the named property is not set. No

Tests can define their own formatters via nested <formatter> elements.

batchtest

Define a number of tests based on pattern matching.

batchtest collects the included files from any number of nested <fileset>s. It then generates a test class name for each file that ends in .java or .class.

Attribute Description Required
fork Deprecated. Run the tests in a separate VM. Overrides value set in <wlunit>. No
haltonerror Stop the build process if an error occurs during the test run. Overrides value set in <wlunit>. No
haltonfailure Stop the build process if a test fails (errors are considered failures as well). Overrides value set in <wlunit>. No
if Only run tests if the named property is set. No
unless Only run tests if the named property is not set. No

Batchtests can define their own formatters via nested <formatter> elements.

Examples


<wlunit>
  <test name="my.test.TestCase" />
</wlunit>

Runs the test defined in my.test.TestCase. No output will be generated unless the test fails.


<wlunit printtestsummary="yes" halttestsonfailure="yes">
  <formatter type="plain" />
  <test name="my.test.TestCase" />
</wlunit>

Runs the test defined in my.test.TestCase. At the end of the test a single 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.


<wlunit printtestsummary="yes" halttestsonfailure="yes">
  <formatter type="plain" />

  <test name="my.test.TestCase" haltonfailure="no" outfile="result" >
    <formatter type="xml" />
  </test>

  <batchtest>
    <fileset dir="${src.tests}">
      <include name="**/*Test*.java" />
      <exclude name="**/AllTests.java" /<
    </fileset>
  </batchtest>
</wlunit>

Runs my.test.TestCase, 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.

For each matching file in the directory ${src.tests} a test is run. If a test fails, the build process is aborted. Results are collected in files named TEST-name.txt.


<target name="test.server" depends="compile">
  <taskdef name="wlunit" classname="org.jdoyle.ant.taskdefs.optional.ejb.WLUnit"/>
  <wlunit home="/usr/local/weblogic"
          username="system"
          password="${weblogic.system.password}"
          url="t3://localhost:7001"
          startupPause="60000"
          haltTestsOnFailure="yes">
    <classpath path="/usr/local/weblogic/classes/boot"/>
    <wlclasspath>
      <pathelement location="/usr/local/weblogic/license"/>
      <pathelement location="/usr/local/weblogic/classes"/>
      <pathelement location="/usr/local/weblogic/lib/weblogicaux.jar"/>
    </wlclasspath>
    <testsclasspath>
      <pathelement path="${java.class.path}"/>
      <pathelement location="classes"/>
      <pathelement location="/usr/local/weblogic/classes"/>
      <pathelement location="/usr/local/weblogic/lib/weblogicaux.jar"/>
    </testsclasspath>
    <batchtest>
      <formatter type="plain" usefile="no"/>
      <fileset dir="src">
        <include name="*Test.java"/>
     </fileset>
    </batchtest>
  </wlunit>
</target>

Starts the default ("myserver") WebLogic server in /usr/local/weblogic, using the default properties ("weblogic.properties") and security policy ("weblogic.policy"). The basic WebLogic classpaths are used (classes/boot, license, classes, and lib/weblogicaux.jar). Waits 60 seconds for the server to start.

Then launches JUnit tests. Runs each test named "*Test.java" under the src directory. The tests are run in a separate JVM and have a classpath consisting of Ant's classpath, the local classes directory, and the WebLogic classes. Each test has its details printed to console, formatted as text. If any fail, the remaining tests will abort and the target will fail.

Finally shuts down the server (at t3://localhost:7001), using the "system" account and the password in property ${weblogic.system.password}.