MoMEUnit

Description

This task is intended to run tests from the MoMEUnit testing framework. It runs tests from specified (via appjar attribute) built J2ME application or builds test application on behalf of the user.

It creates the list of test cases to run from classes of specified J2ME application or classes and/or java source files specified via tests descriptions. Test cases included are classes and/or java source files that implement momeunit.framework.Test interface and/or match specified pattern. There is no need to specify tests explicitly. The format of pattern resembles ant path pattern. Instead of slash ('/'), dot ('.') is used. It looks like ant package pattern. ( e.g. "**.*Test" matches any class that ends with Test at any package, "test.**.*" matches any class below test package, "**.*" matches all classes).

Tests can be described by using <testdir>, <tesjar> nested tags. As <momeunit> task is an implicit test, test cases to run can be described using testdir, testtype and testjar attributes.

Results of tests run can be formatted by predefined or custom formatters (like in <junit> task). There are two predefined formatters "brief" and "xml". These formatters fully resemble their junit analogs. xml formatter produces report files of the same format as it's <junit> analog. Because of this, it is possible to use <junitreport> task to further process report files.

Users can handle infinite loops or tests that execute too long by use of timeout attribute. It's behavior is a bit different from that of <junit>. Duration of tests execution is measured from first test start not from emulator start. All tests executed before offended one are reported normally. The test interrupted by timeout will be reported as it threw an exception with the message "Tests execution timeouts after timeout". No tests will be executed after timeout. Such behavior gives developer more possibilities to detect offending test.

Users can specify attributes of JAD descriptor (and manifest, in a case <momeunit> builds test application) via nested <jad> tags. If J2ME application is specified by appjar attribute JAD descriptor is based on manifest of given application.

If <momeunit> builds J2ME test application, users can specify to preverify application classes by setting preverify attribute to on.

Users can specify to preverify J2ME application jar file by setting preverify attribute to appJar. In this case whole application jar file is preverified.

Users can specify and configure predefined or custom emulator and/or preverifier to use (classes to run emulator and/or preverify tools) via nested <emulator>, <preverify> nested tags respectively.

For details on specifying custom artifacts see Extending MoMEUnit Task.

If MoMEUnit task builds J2ME application, users can specify external libraries to be included via <libdir> and/or <libjar> nested tags. Files designated by these tags are not scanned for test cases.

Note: User shouldn't specify classes of MoMEUnit framework and classes used by test runners to be included. MoMEUnit task includes them automatically.

Note: MoMEUnit task does not depend on antenna project. Users don't need it to run this task.

Attributes

Attribute	Description	Required
appdir	Directory where `momeunit` builds J2ME application. The default is in temporary directory under `tmpdir`. Since version 1.1	No
appjar	Jar file of J2ME application to test. If set `momeunit` will not build J2ME application. Since version 1.1	No
appname	Name of application to build. momeunit will use It as the basename of midlet jar and jad descriptor files. Defaults to `name` attribute. Since version 1.1	No
classpath	Classpath to use. The default is `ant-momeunit.jar`, `midp[version]` and `cldc[version]` libraries. Specified classpath is added to the default one. Since version 1.1	No
config	CLDC version to use. Note: The least version `<momeunit>` supports now is `"1.1"` (the default one). Since version 1.1	No; default is `"1.1"`
defpatten	Pattern to be used as default for nested `<testdir>`, `<testjar>` tags and implicit test. The default is to allow all classes. Since version 1.1	No; default is `"*."`
delonexit	Whether to delete built J2ME application (jar and jad files created) after tests run. The default is `on`, unless `appdir` attribute is set. Since version 1.1	No
errorproperty	The name of a property to set on the event of an error. Since version 1.1	No
failureproperty	The name of a property to set on the event of a failure (errors are considered failures as well). Since version 1.1	No
filtertrace	Filter out `momeunit` and `mome` stack frames from error and failure stack traces. Since version 1.1	No; default is `on`.
haltonerror	Stop the build process if an error occurs during the tests run. Can take the values `on`, `off`, and `withCease`. If set to `on` - stop build process, but not cease tests execution (all test are executed). `off` - don't stop build process. `withCease` - stop build process and cease tests execution. Since version 1.1 Changed in version 1.1.2	No; default is `off`.
haltonfailure	Stop the build process if some test fails (errors are considered failures as well). Can take the values `on`, `off`, and `withCease`. If set to `on` - stop build process, but not cease tests execution (all test are executed). `off` - don't stop build process. `withCease` - stop build process and cease tests execution. Since version 1.1 Changed in version 1.1.2	No; default is `off`.
listenonerr	Whether to listen for test events at standard error output. By default `<momeunit>` listens on both std err and std out and that is the most suitable and preferred way. Users are strongly encouraged to specify this attribute only on extra situations like troubleshooting. Since version 1.1	`No; default is on.`
listenonout	Whether to listen for test events at standard output. By default `<momeunit>` listens on both std err and std out and that is the most suitable and preferred way. Users are strongly encouraged to specify this attribute only on extra situations like troubleshooting. Since version 1.1	No; default is `on`.
name	Name of test suite. Value of this attribute Is used in runners and formatters. The default value is `"app"` Since version 1.1	No; default is `"app"`
onlyTests	Include in tests list classes specified by implicit test or `appjar` only if they implement `momeunit.framework.Test` interface. Since version 1.1	No; default is `on`.
pattern	Pattern to refine list of test cases of implicit test. The format of this pattern resembles Ant path pattern. Instead of slash (`'/'`), dot (`'.'`) is used. It looks like ant package pattern. ( e.g. `"*.Test"` matches any class that ends with Test at any package, `"test.*."` matches any class below test package, `"*."` matches all classes). The default value is specified by `defpattern` attribute of `<momeunit>`. Note: Only files implementing `momeunit.framework.Test` interface are enlisted (depends on `onlyTests` attribute). Since version 1.1	No
preverify	Whether to preverify built or specified J2ME application. Can take the values `on`, `off`, and `appJar`. If set to `on` - `<momeunit>` will preverify classes of J2ME test application, if it is used to build it. `off` - `<momeunit>` will not preverify J2ME test application. `appJar` - `<momeunit>` will preverify whole application jar file. Since version 1.1 Changed in version 1.1.2	No; default is `on`.
printsummary	Print one-line statistics for each test case. 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`. Since version 1.1	No; default is `off`.
profile	MIDP version to use. Note: The least version `<momeunit>` supports now is `"2.0"` (the default one). Since version 1.1	No; default is `"2.0"`
reportdir	Directory where to put report files produced by formatters. Defaults to `basedir`. Since version 1.1	No
reportfile	Base name of report files produced by formatters. The default value is `"tests-"name`. Since version 1.1	No
runner	Runner to use. Either `"ant"` or `"midlet"`. `ant` runner sends all test events to formatters. `midlet` displays results at emulator only. Note: `midlet` runner ignores specified `<formatter>` nested tags ant `haltonerror, errorproperty, haltonfailure, failureproperty` and `printsummary` attributes. Since version 1.1	No; default is `ant`.
showoutput	Whether to send any output generated by tests and emulator to Ant's logging system as well as to the formatters. By default only the formatters receive the output. Since version 1.1	No
testdir	Root directory of files to be scanned for test cases. All files below this directory will be added to J2ME application. Note: If `testtype` is `src` `testdir` designates root directory of source java files. Java files will be compiled and included with non-java classes in J2ME application. Since version 1.1	Either one of them or `appjar` or nested `<testdir>` or `<testjar>` tags.
testjar	Jar file to be scanned for test cases. All files in this archive will be included in J2ME application. Since version 1.1
testtype	Type of files specified by `testdir` attribute. Either `"class"` or "src". `class` indicates that `testdir` specifies classes root directory. `src` indicates that testdir specifies sources root directory. Note: Can be used only in conjunction with `testdir` attribute. Since version 1.1	No; default is `"class"`
timeout	Maximum duration of tests execution measured from first test start (not from emulator start). After that amount of time tests execution stops, if it is not already finished. It takes the format `<DoubleLiteral>[<UnitSuffix>]` `DoubleLiteral` is double number string representation as specified by `Double.valueOf(String)`. `UnitSuffix` is an optional case insensitive specification of unit of time. It can be one of the following `h` - for hours; `m` - for minutes; `s` - for seconds; `ms` - for milliseconds. If suffix is omitted milliseconds are implied. To be valid this attribute must specify duration >= 1ms. By default tests are executed without time boundaries. Since version 1.1.1	No
tmpdir	Directory where `<momeunit>` should place temporary files. By default uses `"tmp.dir"` ant property. If not set uses `"java.io.tmpdir"` java system property. Since version 1.1	No
wtkhome	Home directory of WTK used. If not set uses `"wtk.home"` ant property. If not set uses `WTK_HOME` environment variable. Since version 1.1	No

Nested Elements of momeunit

classpath

The location of class files and resources to be used at executing this task specified as PATH like structure.

Since version 1.1

compiler

Configures compiler that compiles java source files, if there are some. Users can specify only one nested <compiler> tag. This tag extends <javac> task, All attributes and nested tags of <javac> except forbidden in compiler can be specified.

compiler forbids following attributes:

classpath, classpathref – classpath of momeunit is used instead;
src, sourcepath, sourcepathref - sources specified by testdir tags and testdir attribute of momeunit are used instead;

and nested tags:

classpath – classpath of momeunit is used instead;
src, sourcepath - sources specified by testdir tags and testdir attribute of momeunit are used instead;

Note: target attribute is preset to 1.1 and source attribute is preset to 1.3.

Additional attributes defined in comiper:

Attribute

Description

Required

destdir

Directory where to place compiled classes. Defaults to temporary directory under tempdir.

Since version 1.1

delonexit

Delete compiled classes after tests run. Default is on, unless destdir is set.

Note: Users should be careful with specifying this attribute. if destdir is set and delonexit is set to true destdir will be deleted with it's content after tests run.

Since version 1.1

formatter

The results of the tests can be printed in different formats. Output will always be sent to a file, unless user set the usefile attribute to false. The location of the file is determined by the reportdir and reportfile attributes of <momeunit>.

Users can specify predefined and custom formatters. There are two predefined formatters - "xml" and "brief".

xml prints the test results in xml format. This formatter fully resembles it's <junit> analog. It produces reports of the same format. Users can use <junitreport> task to process outputs of this formatter.
brief only prints detailed information for test cases that failed.

Users can define custom formatters. that need to extend org.momeunit.ant.formatter.UnitResultFormatter and specify them via classname attribute. See Developing Custom Formatter for details.

Note: 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.

Attributes

Attribute	Description	Required
type	Use a predefined formatter (either `xml` or `brief`). Since version 1.1	Exactly one of these.
classname	Name of a custom formatter class. Since version 1.1	Exactly one of these.
extension	Extension to append to the filename of report file. Defaults to `"xml"` for `xml` formatter and `"txt"` for `brief` formatter. Since version 1.1	Yes, if `classname` has been used.
encoding	Charset to use for writing report files Since version 1.1	No; default is `UTF-8`.
usefile	Whether output should be sent to a file. Since version 1.1	No; default is `on`.
filtertrace	Filter out `momeunit` and `mome` stack frames from error and failure stack traces. Overrides value set in `<momeunit>`. Since version 1.1	No; default is `on`.
if	Only use formatter if the named property is set. Since version 1.1	No
unless	Only use formatter if the named property is not set. Since version 1.1	No

Since version 1.1

emulator

Specifies and configures an emulator that runs J2ME application. Users can specify predefined or custom emulator.

Now there is one predefined emulator "sun". sun emulator runs Sun WTK emulator tool. See Emulators for details about usage.

Users can specify custom emulator that needs to extend org.momeunit.ant.emulator.Emulator via classname attribute. See Developing Custom Emulator for details.

Attributes

Attribute	Description	Required
type	Type of predefined emulator. Now only `"sun"` (the default) can be used. Since version 1.1	No; default is `"sun"`
classname	Class name of emulator implementation. Since version 1.1	No
home	Emulator home directory. Defaults to `wtkhome` attribute of `<momeunit>` or `"wtk.home"` ant property if not set or `WTK_HOME` environment variable if not set. Since version 1.1	No
device	Device to use for emulating. Since version 1.1	No
classpath	classpath used when running emulator. Since version 1.1	No
classpathref	Reference to classpath used when running emulator. Since version 1.1	No

Nested tags of emulator

property

Configures emulator's behavior. See Emulators for a list of supported properties.

Attribute

Description

Required

name

Name of property.

Since version 1.1

Yes

value

value of property.

Since version 1.1

classpath

Represents a PATH like structure – classpath used when running emulator.

Since version 1.1

jad

Defines a JAD descriptor and manifest of built J2ME application. This tag can be specified more than once.

Attribute	Description	Required
datasize	Specifies `MIDlet-Data-Size` midlet attribute. Since version 1.1	No
deleteconfirm	Specifies `MIDlet-Delete-Confirm` midlet attribute. Since version 1.1	No
deletenotify	Specifies `MIDlet-Delete-Notify` midlet attribute. Since version 1.1	No
encoding	Charset to use for writing JAD descriptor. The default is `"UTF-8"`. It is recommended to leave this attribute unset. Since version 1.1	No; default is `"UTF-8"`
file	JAD file to be appended. Since version 1.1	No
infourl	Specifies `MIDlet-Info-URL` midlet attribute. Since version 1.1	No
installnotify	Specifies `MIDlet-Install-Notify` midlet attribute. Since version 1.1	No
name	Specifies `MIDlet-Name` midlet attribute. The default is `appname` of `<momeunit>`. Since version 1.1	No
perm	Specifies `MIDlet-Permissions` midlet attribute. Since version 1.1	No
permopt	Specifies `MIDlet-Permissions-Opt` midlet attribute. Since version 1.1	No
vendor	Specifies `MIDlet-Vendor` midlet attribute. The default is `appname"vendor"`. Since version 1.1	No
version	Specifies `MIDlet-Version` midlet attribute. The default is `"0.0.1"` Since version 1.1	No
if	Only use this tag if the named property is set. Since version 1.1	No
unless	Only use this tag if the named property is not set. Since version 1.1	No

Nested tags of jad

appprop

Defines an attribute to be added to jad descriptor and manifest of built J2ME application.

Attribute

Description

Required

name

Name of attribute.

Since version 1.1

Yes

value

value of attribute.

Since version 1.1

Yes

midlet

Defines a midlet to be specified in jad descriptor and manifest of built J2ME application.

Note: Users don't need to include midlet of runner. It is included by momeunit.

Attribute	Description	Required
name	Name of the midlet. Since version 1.1	Yes
icon	icon of the midlet. Since version 1.1	No
class	classname of the midlet. Since version 1.1	Yes

push

Defines a push-info to be specified in jad descriptor or manifest of built J2ME application.

Attribute	Description	Required
conurl	Connection url. Since version 1.1	Yes
class	MIDlet class name. Since version 1.1	Yes
allowedsender	Allowedsender specification. Since version 1.1	No; default is `"*"`

Since version 1.1

libdir

Defines files to be included in built J2ME application. This tag extends fileset. All attributes and nested tags of fileset are allowed. Files specified by this tag are not scanned for test cases.

Additional attributes

Attribute

Description

Required

Only use this library if the named property is set.

Since version 1.1

unless

Only use this library if the named property is not set.

Since version 1.1

libjar

Defines files to be included in built J2ME application. This tag extends zipfileset. All attributes and nested tags of zipfileset are allowed. Files specified by this tag are not scanned for test cases.

Additional attributes

Attribute

Description

Required

Only use this library if the named property is set.

Since version 1.1

unless

Only use this library if the named property is not set.

Since version 1.1

preverify

Specifies and configures preverifier that preverifies J2ME application. Users can specify predefined or custom preverifier.

Now there is only one predefined preverifier "sun". sun preverifier runs Sun WTK preverify tool. See Preverifiers for details on usage.

Users can specify custom preverifier that needs to extend org.momeunit.ant.preverifier.Preverifier via classname attribute. See Specifying Custom Preverifier for details.

Attributes

Attribute	Description	Required
type	Type of predefined preverifier. Now only `"sun"` (the default) can be used. Since version 1.1	No
classname	Classname of preverifier implementation. Since version 1.1	No
home	Preverifier home directory. Defaults to `wtkhome` attribute of `<momeunit>` or `"wtk.home"` ant property if not set or `WTK_HOME` environment variable if not set. Since version 1.1	No
config	CLDC version to be used. Since version 1.1	No; default is `"1.1"`

Nested tags of preverify.

property

Configures preverifier's behavior. See Preverifiers for a list of supported properties.

Attribute

Description

Required

name

Name of property.

Since version 1.1

Yes

value

value of property.

Since version 1.1

testdir

Defines files be scanned for tests cases. This tag extends fileset. All attributes and nested tags of fileset are allowed. Only files designated by this tag are scanned for test cases.

Attribute	Description	Required
dir	Directory of files to be scanned for test cases. Files below this directory will be compiled if necessary and added to J2ME application. Since version 1.1	Yes
type	Type of files under dir. Either `"src"` or `"class"`. The default value is `"class"`. Since version 1.1	No; default is `"class"`
pattern	Pattern to refine test cases enlisted. The format of this pattern resembles Ant path pattern. Instead of slash (`'/'`), dot (`'.'`) is used. It looks like ant package pattern. ( e.g. `"*.Test"` matches any class that ends with Test at any package, `"test.*."` matches any class below test package, `"*."` matches all classes). The default value is specified by `defpattern` attribute of `<momeunit>`. Note: Only files implementing `momeunit.framework.Test` interface are enlisted (depends on `onlyTests` attribute). Since version 1.1	No
onlyTests	Include only classes that implement `momeunit.framework.Test` interface in tests list. Since version 1.1	No
if	Only run tests if the named property is set. Since version 1.1	No
unless	Only run tests if the named property is not set. Since version 1.1	No

Note: There is difference in restricting set of files included in J2ME application using facilities of fileset for different types:

If type is class – only files designated will be included.
If type is src – only designated non-java files and all source java files under dir will compiled and included in built J2ME application.

Note: Users are encouraged to be careful in using facilities of fileset, if type is class, because momeunit relies on inheritance in designing test cases and excluding super class of test case leads to an error.

Since version 1.1

testjar

Defines classes to be scanned for tests cases. This tag extends zipfileset. All attributes and nested tags of zipfileset are allowed. Only files designated by this tag are scanned for test cases.

Attribute	Description	Required
src	Jar file to be scanned for test cases. Since version 1.1	Yes
pattern	Pattern to refine test cases enlisted. The format of this pattern resembles Ant path pattern. Instead of slash (`'/'`), dot (`'.'`) is used. It looks like ant package pattern. ( e.g. `"*.Test"` matches any class that ends with Test at any package, `"test.*."` matches any class below test package, `"*."` matches all classes). The default value is specified by `defpattern` attribute of `<momeunit>`. Note: Only files implementing `momeunit.framework.Test` interface are enlisted (depends on `onlyTests` attribute). Since version 1.1	No
onlyTests	Include only classes that implement `momeunit.framework.Test` interface in tests list. Since version 1.1	No
if	Only run tests if the named property is set. Since version 1.1	No
unless	Only run tests if the named property is not set. Since version 1.1	No

Note: Users are encouraged to be careful in using facilities of zipfileset element, because momeunit relies on inheritance in designing test cases and excluding super class of test case leads to an error.

Since version 1.1

Examples

  <momeunit appjar="res/myapp.jar" printsummary="on"/>

Runs test cases from myapp.jar application, and prints a short summary of results.

  <momeunit appjar="res/myapp.jar" printsummary="on" >
    <jad file="res/anotherapp.jad">
      <appprop name="My-Attribute" value"AndItsValue"/>
    </jad>
  <momeunit>

Does the same as previous example but adds specified application attribute and attributes from file res/anotherapp.jad to JAD descriptor of test application.

  <momeunit testdir="src" testtype="src" name="MyApp">
    <formatter type="brief"/>
  </momeunit>

Runs test cases specified by source java files in src directory and creates report file in plain text format in current directory with filename tests-MyApp.xml with test suite name of MyApp.

  <momeunit testdir="src" testtype="src" name="MyApp">
    <formatter type="brief"/>    
    <preverify>
      <property name="nofinalise"/>
    </preverify>
  </momeunit>

Does the same as previous example but configures preverify tool with -nofinalise option.

  <momeunit name="MyApp" timeout=".5m" reportdir="reports" reportfile="myapp-tets-results">
    <testdir dir="src" testtype="src"/>
    <formatter type="xml"/>
    <formatter type="brief"/>
  </momeunit>
  <junitreport todir="rep">
    <fileset dir="reports" includes="myapp-tets-results.xml" />
    <report styledir="stylesheets" todir="results" format="noframes" />
  </junitreport>

Runs test cases specified by source java files in src directory specified by <testdir> nested tag. Stops tests execution after 30 seconds, if it is not already finished. Creates report files in xml and plain text formats in reports directory with filenames of myapp-tests-results.xml and myapp-tests-results.txt with test suite name of MyApp. XML report file is further processed by <junitreport> task.

  <momeunit name="AllTests" reportdir="reports" reportfile="alltets-results" appdir="res">
    <testdir dir="bin"/>
    <formatter type="brief" extension="res"/>
  </momeunit>

Runs test cases specified by classes in bin directory specified by <testdir> nested tag and creates report file in plain text formats in reports directory with filename alltests-results.res with test suite name of AllTests. Built by <momeunit> task test application (jar and jad files) are left intact after tests run in res directory.

  <momeunit name="AllTests" reportdir="reports" reportfile="alltets-results" 
      appdir="res" showoutput="on" failureproperty="testFails">
    <testdir dir="bin" pattern="**.*Test"/>
    <formatter type="brief" extension="res" />
  </momeunit>

Does the same as previous example but list of tests to run includes only classes with name that ends with Test. Shows output of emulator and J2ME application at ant log. Sets property testFails in a case of failure (errors are considered failures as well).

  <momeunit name="AllTests" runner="midlet" appdir="res" showoutput="on">
    <testdir dir="bin" pattern="**.*Test"/>
  </momeunit>

Does the same as previous example but shows results of tests run in emulator instead of processing them by formatters.

  <momeunit name="AllTests" reportdir="reports" reportfile="alltets-results" 
      haltonerror="on" classpath="myclasses">
    <libjar src="lib/lib.jar"/>
    <testjar src="classes.jar"/>
    <formatter classname="MyFormatter" extension=".txt"/>
    <emulator classname="MyEmulator"/>
  </momeunit>

Adds external library lib/lib.jar to test application. Runs test cases specified by classes in classes.jar archive specified by <testjar> nested tag. Creates report file in plain text format in reports directory with filename of alltests-results.txt with test suite name of AllTests. Uses as formatter and emulator MyFormatter and MyEmulator classes respectively that reside in myclasses directory. Stops the build process if some test threw an error.