Author: bdaw Date: 2008-01-28 11:34:41 -0500 (Mon, 28 Jan 2008) New Revision: 9623 Added: modules/test/trunk/docs/user-guide/en/modules/tooling.xml Modified: modules/test/trunk/docs/user-guide/en/master.xml modules/test/trunk/docs/user-guide/en/modules/pojotesting.xml Log: initial draft of tooling documentation Modified: modules/test/trunk/docs/user-guide/en/master.xml =================================================================== --- modules/test/trunk/docs/user-guide/en/master.xml 2008-01-28 15:00:37 UTC (rev 9622) +++ modules/test/trunk/docs/user-guide/en/master.xml 2008-01-28 16:34:41 UTC (rev 9623) @@ -3,6 +3,7 @@ "../../docbook-support/support/docbook-dtd/docbookx.dtd" [ <!ENTITY introduction SYSTEM "modules/introduction.xml"> <!ENTITY pojotesting SYSTEM "modules/pojotesting.xml"> + <!ENTITY tooling SYSTEM "modules/tooling.xml"> ]> <book lang="en"> <bookinfo> @@ -18,5 +19,6 @@ <toc/> <!-- Introduction --> &introduction; <!-- POJO Testing --> &pojotesting; + <!-- Tools support --> &tooling; </book> Modified: modules/test/trunk/docs/user-guide/en/modules/pojotesting.xml =================================================================== --- modules/test/trunk/docs/user-guide/en/modules/pojotesting.xml 2008-01-28 15:00:37 UTC (rev 9622) +++ modules/test/trunk/docs/user-guide/en/modules/pojotesting.xml 2008-01-28 16:34:41 UTC (rev 9623) @@ -19,7 +19,7 @@ that the test failed.</para> <para>A class containing a serie of test cases is considered as a test suite.</para> <example> - <programlisting><![CDATA[ + ka <programlisting><![CDATA[ import org.jboss.unit.api.pojo.annotations.Test; public class MyTest Added: modules/test/trunk/docs/user-guide/en/modules/tooling.xml =================================================================== --- modules/test/trunk/docs/user-guide/en/modules/tooling.xml (rev 0) +++ modules/test/trunk/docs/user-guide/en/modules/tooling.xml 2008-01-28 16:34:41 UTC (rev 9623) @@ -0,0 +1,1306 @@ +<?xml version="1.0" encoding="UTF-8"?> +<chapter id="tooling"> + <chapterinfo> + <author> + <firstname>Boleslaw</firstname> + <surname>Dawidowicz</surname> + <email&gt;boleslaw.dawidowicz(a)redhat.com&lt;/email&gt; + </author> + </chapterinfo> + <title>Tools support</title> + <para>JBoss Unit framework provide 3 methods to invoke tests: + + </para> + <itemizedlist> + <listitem>Commandline</listitem> + <listitem>Ant task</listitem> + <listitem>Maven plugin</listitem> + </itemizedlist> + <sect1> + <title>Required dependencies</title> + <para>TODO: Which jars are exactly needed</para> + </sect1> + + <sect1> + <title>Commandline</title> + <para>JBoss Unit can be run directly from the command line. This is main and low level way to control testsuite + execution. In both ant and maven support all the configuration defined in build files is converted to proper + commandline java call.</para> + <example> + <programlisting> + <![CDATA[ +# java [class_path] org.jboss.unit.tools.Main --config=config/jboss-unit.xml \ + --ids=testOne,testTwo,testThree \ + --keywords=APITests,TCK \ + --property.name=value \ + --property.name2=value2 \ + --properties=[name3=value1,name3,value2] \ + --parameter.name=[value1,value2,value3] \ + --parameter.name2=value \ + --parameters=[a=b,a=b2,c=d] \ + ]]> + </programlisting> + </example> + <sect2> + <title>--config</title> + <para>JBoss Unit configuration file</para> + <example> + <programlisting> + <![CDATA[ +# java [class_path] org.jboss.unit.tools.Main --config=config/jboss-unit.xml \ + ]]> + </programlisting> + </example> + </sect2> + + <sect2> + <title>--id</title> + <para>Id of testcase to invoke</para> + <example> + <programlisting> + <![CDATA[ +# java [class_path] org.jboss.unit.tools.Main --config=config/jboss-unit.xml --id=testOne + ]]> + </programlisting> + </example> + </sect2> + <sect2> + <title>--ids</title> + <para>Coma separated list of testcase ids that should be executed</para> + <example> + <programlisting> + <![CDATA[ +# java [class_path] org.jboss.unit.tools.Main --config=config/jboss-unit.xml --ids=testOne,testTwo,testThree + + ]]> + </programlisting> + </example> + </sect2> + <sect2> + <title>--keywords</title> + <para>Coma separated list of testcase keywords that should be executed</para> + <example> + <programlisting> + <![CDATA[ +# java [class_path] org.jboss.unit.tools.Main --config=config/jboss-unit.xml --keywords=APITests,TCK + ]]> + </programlisting> + </example> + </sect2> + <sect2> + <title>--ex_id</title> + <para>Id of testcase that should be excluded from execution</para> + <example> + <programlisting> + <![CDATA[ +# java [class_path] org.jboss.unit.tools.Main --config=config/jboss-unit.xml --ex_id=testOne + ]]> + </programlisting> + </example> + </sect2> + <sect2> + <title>--ex_ids</title> + <para>Coma separated list of testcase ids that should be excluded from execution</para> + <example> + <programlisting> + <![CDATA[ +# java [class_path] org.jboss.unit.tools.Main --config=config/jboss-unit.xml --ex_ids=testOne,testTwo,testThree + ]]> + </programlisting> + </example> + </sect2> + <sect2> + <title>--ex_keywords</title> + <para>Coma separated list of testcase keywords that should be excluded from execution</para> + <example> + <programlisting> + <![CDATA[ +# java [class_path] org.jboss.unit.tools.Main --config=config/jboss-unit.xml --ex_keywords=APITests,TCK + ]]> + </programlisting> + </example> + </sect2> + <sect2> + <title>--suite_name</title> + <para>Testsuite name. It will be used in reports generation</para> + <example> + <programlisting> + <![CDATA[ +# java [class_path] org.jboss.unit.tools.Main --config=config/jboss-unit.xml --suite_name=myTests + + ]]> + </programlisting> + </example> + </sect2> + <sect2> + <title>--no_console</title> + <para>Output won't be present on the console</para> + <example> + <programlisting> + <![CDATA[ +# java [class_path] org.jboss.unit.tools.Main --config=config/jboss-unit.xml --no_console + ]]> + </programlisting> + </example> + </sect2> + <sect2> + <title>--xml_report_dir</title> + <para>Directory to which xml reports should be generated. Xml reports will be in JUnit format</para> + <example> + <programlisting> + <![CDATA[ +# java [class_path] org.jboss.unit.tools.Main --config=config/jboss-unit.xml --xml_report_dir=output/reports/xml + ]]> + </programlisting> + </example> + </sect2> + <sect2> + <title>--html_report_dir</title> + <para>Directory to which html reports should be generated.</para> + <example> + <programlisting> + <![CDATA[ +# java [class_path] org.jboss.unit.tools.Main --config=config/jboss-unit.xml --html_report_dir=output/reports/html + ]]> + </programlisting> + </example> + </sect2> + <sect2> + <title>--property</title> + <para>Single property value</para> + <example> + <programlisting> + <![CDATA[ +# java [class_path] org.jboss.unit.tools.Main --config=config/jboss-unit.xml --property.name=value --property.name2=value2 + ]]> + </programlisting> + </example> + </sect2> + <sect2> + <title>--properties</title> + <para>Several name=value pairs for properties</para> + <example> + <programlisting> + <![CDATA[ +# java [class_path] org.jboss.unit.tools.Main --config=config/jboss-unit.xml --properties=[name3=value1,name3,value2] + ]]> + </programlisting> + </example> + </sect2> + <sect2> + <title>--parameter</title> + <para>Single parameter values</para> + <example> + <programlisting> + <![CDATA[ +# java [class_path] org.jboss.unit.tools.Main --config=config/jboss-unit.xml + --parameter.name=[value1,value2,value3] \ + --parameter.name2=value + ]]> + </programlisting> + </example> + </sect2> + <sect2> + <title>--parameters</title> + <para>Several name=value paris for parameters. If single name is specified few times, sum of all provided values will be passed</para> + <example> + <programlisting> + <![CDATA[ +# java [class_path] org.jboss.unit.tools.Main --config=config/jboss-unit.xml --parameters=[a=b,a=b2,c=d] + ]]> + </programlisting> + </example> + </sect2> + <sect2> + <title>--failonerror</title> + <para></para> + <example> + <programlisting> + <![CDATA[ +# java [class_path] org.jboss.unit.tools.Main --config=config/jboss-unit.xml --failonerror + ]]> + </programlisting> + </example> + </sect2> + </sect1> + <sect1> + <title>Maven</title> + <para> + To use JBoss Unit maven plugin you need to configure JBoss maven repositories in your pom file: + </para> + <example> + <caption>JBoss maven repositories configuration</caption> + <programlisting> + <![CDATA[ +<pluginRepositories> + <pluginRepository> + <id>repository.jboss.org</id> + <name>JBoss Repository</name> + <layout>default</layout> + <url>http://repository.jboss.org/maven2/</url> + <snapshots> + <enabled>false</enabled> + </snapshots> + </pluginRepository> + <pluginRepository> + <id>snapshots.jboss.org</id> + <name>JBoss Snapshots Repository</name> + <layout>default</layout> + <url>http://snapshots.jboss.org/maven2/</url> + <snapshots> + <enabled>true</enabled> + </snapshots> + <releases> + <enabled>false</enabled> + </releases> + </pluginRepository> +</pluginRepositories> + + ]]> + </programlisting> + </example> + <para> + JBoss Unit artifacts have <emphasis>org.jboss.unit</emphasis> maven groupId. The plugin has + <emphasis>jboss-unit-tooling-maven2</emphasis> maven artifactId. The simplest configuration requires only to + specify a single testsuite with a configuration file. + </para> + <example> + <caption> + <para>Simplest maven plugin configuration</para> + </caption> + <programlisting> + <![CDATA[ +<plugin> + <groupId>org.jboss.unit</groupId> + <artifactId>jboss-unit-tooling-maven2</artifactId> + <executions> + <execution> + <phase>test</phase> + <goals> + <goal>execute</goal> + </goals> + </execution> + </executions> + <configuration> + <testsuites> + <testsuite> + <config>local-jboss-unit.xml</config> + </testsuite> + </testsuites> + </configuration> +</plugin> + ]]> + </programlisting> + + </example> + + <para>In maven plugin you specify <emphasis>testsuites</emphasis>. Each <emphasis>testsuite</emphasis> has single configuration file + and is eqivalent to signle JBoss Unit run. <emphasis>Testsuites</emphasis> are controled with additional constraints applied with + <emphasis>includes</emphasis> and <emphasis>excludes</emphasis>. In each you can describe testcase to include or exclude + from execution by specifying its <emphasis>id</emphasis> or <emphasis>keyword</emphasis>. Maven plugin also support + parameters and properties mechanisms. Reports generation can be configured either globally or per single testsuite</para> + + <example> + <caption> + <para>Custom maven plugin configuration</para> + </caption> + <programlisting> + <![CDATA[ +<plugin> + <groupId>org.jboss.unit</groupId> + <artifactId>jboss-unit-tooling-maven2</artifactId> + <executions> + <execution> + <phase>test</phase> + <goals> + <goal>execute</goal> + </goals> + </execution> + </executions> + <configuration> + <jpda>false</jpda> + <jpdaPort>9000</jpdaPort> + <jpdaSuspend>true</jpdaSuspend> + <failOnError>false</failOnError> + <assertions>true</assertions> + + <testsuites> + <testsuite> + <config>local-jboss-unit.xml</config> + <includes> + <include> + <ids> + <id>testOne</id> + <id>testTwo</id> + </ids> + <keywords> + <keyword>keyword1</keyword> + <keyword>keyword2</keyword> + </keywords> + </include> + </includes> + <excludes> + <exclude> + <ids> + <id>otherTestOne</id> + <id>otherTestTwo</id> + </ids> + <keywords> + <keyword>otherKeyword1</keyword> + <keyword>otherKeyword2</keyword> + </keywords> + </exclude> + </excludes> + <parameters> + <parameter> + <name>parameter1</name> + <values> + <value>value1</value> + <value>value2</value> + </values> + </parameter> + <parameter> + <name>parameter2</name> + <values> + <value>value3</value> + <value>value4</value> + </values> + </parameter> + </parameters> + <properties> + <property> + <name>sampleProperty</name> + <value>propertyValue</value> + </property> + </properties> + <reports> + <xml>target/tests1/reports/xml</xml> + <html>target/tests1/reports/html</html> + </reports> + </testsuite> + <testsuite> + <config>local-jboss-unit2.xml</config> + </testsuite> + </testsuites> + <reports> + <xml>target/tests/reports/xml</xml> + <html>target/tests/reports/html</html> + </reports> + </configuration> +</plugin> + ]]> + </programlisting> + + </example> + + <sect2> + <title>configuration</title> + <table frame="all"> + <title>&lt;configuration&gt; element</title> + <para>Main configuration element of maven plugin</para> + <tgroup cols="3" align="left" colsep="1" rowset="1"> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <thead> + <row> + <entry align="center">Element</entry> + <entry align="center">Default</entry> + <entry align="left">Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>&lt;testsuites&gt;</entry> + <entry/> + <entry></entry> + </row> + <row> + <entry>&lt;reports&gt;</entry> + <entry/> + <entry>Global reports configuration. It can be overwritten in single testsuite configuration</entry> + </row> + <row> + <entry>&lt;jpda&gt;</entry> + <entry>false</entry> + <entry>Remote debugging support (Java Platform Debugger Architecture)</entry> + </row> + <row> + <entry>&lt;jpdaPort&gt;</entry> + <entry>9000</entry> + <entry>JPDA port</entry> + </row> + <row> + <entry>&lt;jpdaSuspend&gt;</entry> + <entry>true</entry> + <entry>Remote debbugging (JPDA) suspend mode. If true it will suspend the VM and wait for the connection + </entry> + </row> + <row> + <entry>&lt;assertions&gt;</entry> + <entry>true</entry> + <entry>Enables Java Assertions</entry> + </row> + <row> + <entry>&lt;failOnError&gt;</entry> + <entry>fail</entry> + <entry>Any testcase failure will make the maven build fail</entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + <sect2> + <title>testsuite</title> + <table frame="all"> + <title>&lt;testsuite&gt; element</title> + <para>Configures single JBoss Unit run</para> + <tgroup cols="2" align="left" colsep="1" rowset="1"> + <colspec colname='c1'/> + <colspec colname='c2'/> + <thead> + <row> + <entry align="center">Element</entry> + <entry align="center">Mandatory</entry> + <entry align="left">Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>&lt;config&gt;</entry> + <entry>Yes</entry> + <entry>JBoss Unit configuration file</entry> + </row> + <row> + <entry>&lt;includes&gt;</entry> + <entry>No</entry> + <entry>Test cases that will be included in testsuite execution. If defined only those tests will be + executed. Excludes check takes precedence.</entry> + </row> + <row> + <entry>&lt;excludes&gt;</entry> + <entry>No</entry> + <entry>Test cases that will be excluded from testsuite execution. If defined all testcases besides + specified will be executed. Excludes check takes precedence before includes.</entry> + </row> + <row> + <entry>&lt;parameters&gt;</entry> + <entry>No</entry> + <entry>Parameters that will be passed to testsuite run</entry> + </row> + <row> + <entry>&lt;properties&gt;</entry> + <entry>No</entry> + <entry>Properties that will be passed to testsuite run</entry> + </row> + <row> + <entry>&lt;reports&gt;</entry> + <entry>No</entry> + <entry>Reports generation configuration valid for single testsuite</entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + <sect2> + <title>include and exclude</title> + <para>Defines testcases to include or exclude from testsuite run</para> + <example> + <programlisting> + <![CDATA[ +<includes> + <include> + <ids> + <id>testOne</id> + <id>testTwo</id> + </ids> + <keywords> + <keyword>keyword1</keyword> + <keyword>keyword2</keyword> + </keywords> + </include> +</includes> +<excludes> + <exclude> + <ids> + <id>otherTestOne</id> + <id>otherTestTwo</id> + </ids> + <keywords> + <keyword>otherKeyword1</keyword> + <keyword>otherKeyword2</keyword> + </keywords> + </exclude> +</excludes> + ]]> + </programlisting> + </example> + <table frame="all"> + <title>&lt;include&gt; and &lt;exclude&gt; elements</title> + <tgroup cols="2" align="left" colsep="1" rowset="1"> + <colspec colname='c1'/> + <colspec colname='c2'/> + <thead> + <row> + <entry align="center">Element</entry> + <entry align="left">Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>&lt;ids&gt;</entry> + <entry>List of testcase ids</entry> + </row> + <row> + <entry>&lt;keywords&gt;</entry> + <entry>List of testcase keywords</entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + <sect2> + <title>id</title> + <para>Testcase id</para> + </sect2> + <sect2> + <title>keyword</title> + <para>Testcase keyword</para> + </sect2> + <sect2> + <title>parameter</title> + <para> + Multi value parameter that will be passed to testsuite execution + </para> + <example> + <programlisting> + <![CDATA[ +<parameters> + <parameter> + <name>parameter1</name> + <values> + <value>value1</value> + <value>value2</value> + </values> + </parameter> + <parameter> + <name>parameter2</name> + <values> + <value>value3</value> + <value>value4</value> + </values> + </parameter> +</parameters> + ]]> + </programlisting> + </example> + <table frame="all"> + <title>&lt;parameter&gt; element</title> + <tgroup cols="2" align="left" colsep="1" rowset="1"> + <colspec colname='c1'/> + <colspec colname='c2'/> + <thead> + <row> + <entry align="center">Element</entry> + <entry align="left">Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>&lt;name&gt;</entry> + <entry>Parameter name</entry> + </row> + <row> + <entry>&lt;values&gt;</entry> + <entry>List of parameter values</entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + <sect2> + <title>property</title> + <para> + Single value property that will be passed to testsuite execution + </para> + <example> + <programlisting> + <![CDATA[ +<properties> + <property> + <name>sampleProperty</name> + <value>propertyValue</value> + </property> + <property> + <name>sampleSecondProperty</name> + <value>propertyValue</value> + </property> +</properties> + + ]]> + </programlisting> + </example> + <table frame="all"> + <title>&lt;property&gt; element</title> + <tgroup cols="2" align="left" colsep="1" rowset="1"> + <colspec colname='c1'/> + <colspec colname='c2'/> + <thead> + <row> + <entry align="center">Element</entry> + <entry align="left">Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>&lt;name&gt;</entry> + <entry>Property name</entry> + </row> + <row> + <entry>&lt;value&gt;</entry> + <entry>Property value</entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + <sect2> + <title>reports</title> + <para>Reports genration</para> + <example> + <programlisting> + <![CDATA[ +<reports> + <xml>target/tests/reports/xml</xml> + <html>target/tests/reports/html</html> +</reports> + ]]> + </programlisting> + </example> + <table frame="all"> + <title>&lt;reports&gt; element</title> + <tgroup cols="3" align="left" colsep="1" rowset="1"> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <thead> + <row> + <entry align="center">Element</entry> + <entry align="center">Mandatory</entry> + <entry align="left">Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>&lt;xml&gt;</entry> + <entry>No</entry> + <entry>Directory to store xml reports in JUnit format</entry> + </row> + <row> + <entry>&lt;html&gt;</entry> + <entry>No</entry> + <entry>Directory to store html reports</entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + + + </sect1> + <sect1> + <title>Ant</title> + <para>To use JBoss Unit in ant proper task need to be defined</para> + <example> + <caption> + <para>JBoss Unit ant task definition</para> + </caption> + <programlisting> + <![CDATA[ +<path id="jboss.unit.tooling.test.classpath"> + <pathelement location="jboss-unit-tooling-ant.jar"/> + <pathelement location="jboss-unit-tooling-core.jar"/> + <!-- ? --> +</path> +<taskdef name="jboss-unit" classname="org.jboss.unit.tooling.ant.JBossUnitTask" classpathref="jboss.unit.tooling.test.classpath"/> + + ]]> + </programlisting> + + </example> + <para>The simplest configuration requires only to specify a single testsuite with a configuration file. You should + provide proper classpath to all jars that will be needed by the testsuite. If you leverage microcontainer or remoting + support additional jars will be needed.</para> + <example> + <caption> + <para>Simplest ant task configuration</para> + </caption> + <programlisting> + <![CDATA[ +<jboss-unit> + <tests config="./jboss-unit.xml"/> + <classpath> + <pathelement location="jboss-unit.jar"/> + <path refid="all.other.needed.dependencies.classpath"/> + </classpath> +</jboss-unit> + ]]> + </programlisting> + + </example> + <para> + In ant task you specify <emphasis>tests</emphasis>. Each <emphasis>test</emphasis> has single configuration file + and is eqivalent to signle JBoss Unit run. <emphasis>Tests</emphasis> are controled with additional constraints applied with + <emphasis>include</emphasis> and <emphasis>exclude</emphasis> elements. In each you can describe testcase to include or exclude + from execution by specifying its <emphasis>ids</emphasis> or <emphasis>keywords</emphasis>. Ant task also support + parameters and properties mechanisms. Reports generation can be configured either globally or per single testsuite + </para> + + <example> + <caption> + <para>Custom ant task configuration</para> + </caption> + <programlisting> + <![CDATA[ +<jboss-unit> + + <tests config="./jboss-unit.xml" suiteName="MyTests" jpda="false" jpdaPort="9000" jpdaSuspend="true" failOnError="false"> + + <!-- executed tests will be based on sum of all applied filters --> + <!-- exclude filters will take precedence during conditions check --> + + <include ids="test1,test2,test3" keywords="key1,key2,key3"/> + <include id="test55" /> + + <exclude ids="biltoTest,oldTest,loloTest" keywords="outdated,examples"/> + <exclude id="excludeId" /> + + <property name="propertyOne" value="propertyOneValue"/> + <property name="propertyTwo" value="propertyTwoValue"/> + + <parameter name="parameterOne> + <value>valueOne</value> + <value>valueTwo</value> + </parameter> + <parameter name="parameterTwo> + <value>valueOne</value> + <value>valueTwo</value> + </parameter> + + <!-- reports specified for specific <tests> override global --> + <reports noconsole="true"> + <html dir=""> + </reports> + </tests> + <tests config="./jboss-unit2.xml"/> + <reports> + <xml toDir="./tests/xml"/> + <html toDir="./tests/html"/> + </reports> + <classpath> + <path refid="all.other.needed.dependencies.classpath"/> + </classpath> +</jboss-unit> + ]]> + </programlisting> + + </example> + + <sect2> + <title>jboss-unit</title> + <table frame="all"> + <title>&lt;jboss-unit&gt; element</title> + <tgroup cols="5" align="left" colsep="1" rowset="1"> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <colspec colname='c4'/> + <colspec colname='c5'/> + <thead> + <row> + <entry align="center">Element</entry> + <entry align="center">Mandatory</entry> + <entry align="left">Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>&lt;tests&gt;</entry> + <entry>Yes</entry> + <entry></entry> + </row> + <row> + <entry>&lt;reports&gt;</entry> + <entry>No</entry> + <entry>Global reports configuration. It can be overwritten in single testsuite configuration</entry> + </row> + <row> + <entry>&lt;classpath&gt;</entry> + <entry>No</entry> + <entry>Ant classpath. All jars needed to run the tests.</entry> + </row> + + </tbody> + </tgroup> + </table> + </sect2> + + <sect2> + <title>tests</title> + <para>Single testsuite definition.</para> + <table frame="all"> + <title>&lt;tests&gt; element</title> + <tgroup cols="5" align="left" colsep="1" rowset="1"> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <colspec colname='c4'/> + <colspec colname='c5'/> + <thead> + <row> + <entry align="center">Element</entry> + <entry align="center">Attribute</entry> + <entry align="center">Mandatory</entry> + <entry align="center">Default</entry> + <entry align="left">Description</entry> + </row> + </thead> + <tbody> + <row> + <entry/> + <entry>config</entry> + <entry>Yes</entry> + <entry></entry> + <entry>JBoss Unit configuration file</entry> + </row> + <row> + <entry/> + <entry>suiteName</entry> + <entry>No</entry> + <entry></entry> + <entry>Testsuite name - this will be used in report generation</entry> + </row> + <row> + <entry/> + <entry>jpda</entry> + <entry>No</entry> + <entry>false</entry> + <entry>Remote debugging support (Java Platform Debugger Architecture)</entry> + </row> + <row> + <entry/> + <entry>jpdaPort</entry> + <entry>No</entry> + <entry>9000</entry> + <entry>JPDA port</entry> + </row> + <row> + <entry/> + <entry>jpdaSuspend</entry> + <entry>No</entry> + <entry>true</entry> + <entry>Remote debbugging (JPDA) suspend mode. If true it will suspend the VM and wait for the connection</entry> + </row> + <row> + <entry/> + <entry>failOnError</entry> + <entry>No</entry> + <entry>false</entry> + <entry>Any testcase failure will make the ant build fail</entry> + </row> + <row> + <entry>&lt;include&gt;</entry> + <entry/> + <entry>No</entry> + <entry></entry> + <entry>Testcases that will be included in testsuite execution. If defined only those tests will be executed. Excludes check takes precedence.</entry> + </row> + <row> + <entry>&lt;exclude&gt;</entry> + <entry/> + <entry>No</entry> + <entry></entry> + <entry>Testcases that will be excluded from testsuite execution. If defined all testcases besides specified will be executed. Excludes check takes precedence before includes.</entry> + </row> + <row> + <entry>&lt;parameter&gt;</entry> + <entry/> + <entry>No</entry> + <entry></entry> + <entry>Parameters that will be passed to testsuite run</entry> + </row> + <row> + <entry>&lt;property&gt;</entry> + <entry/> + <entry>No</entry> + <entry>Properties that will be passed to testsuite run</entry> + </row> + <row> + <entry>&lt;reports&gt;</entry> + <entry/> + <entry>No</entry> + <entry></entry> + <entry>Reports generation configuration valid for single testsuite</entry> + </row> + + </tbody> + </tgroup> + </table> + </sect2> + <sect2> + <title>include and exclude</title> + <para>Defines testcases to include or exclude from testsuite run</para> + <example> + <programlisting> + <![CDATA[ +<include ids="test1,test2,test3" keywords="key1,key2,key3"/> +<include id="test55" /> + +<exclude ids="biltoTest,oldTest,loloTest" keywords="outdated,examples"/> +<exclude id="excludeId" /> + ]]> + </programlisting> + </example> + <table frame="all"> + <title>&lt;include&gt; and &lt;exclude&gt; elements</title> + <tgroup cols="3" align="left" colsep="1" rowset="1"> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <thead> + <row> + <entry align="center">Attribute</entry> + <entry align="center">Mandatory</entry> + <entry align="left">Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>id</entry> + <entry>No. Either &lt;ids&gt; or &lt;id&gt; can be used</entry> + <entry>Testcase id</entry> + </row> + <row> + <entry>ids</entry> + <entry>No. Either &lt;ids&gt; or &lt;id&gt; can be used</entry> + <entry>Coma separated list of testcase ids</entry> + </row> + <row> + <entry>keywords</entry> + <entry>No</entry> + <entry>Coma separated list of testscase keywords</entry> + </row> + + + </tbody> + </tgroup> + </table> + </sect2> + <sect2> + <title>property</title> + <para>Single value property that will be passed to testsuite execution</para> + <example> + <programlisting> + <![CDATA[ +<property name="propertyOne" value="propertyOneValue"/> +<property name="propertyTwo" value="propertyTwoValue"/> + + ]]> + </programlisting> + </example> + <table frame="all"> + <title>&lt;property&gt; element</title> + <tgroup cols="3" align="left" colsep="1" rowset="1"> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <thead> + <row> + <entry align="center">Attribute</entry> + <entry align="center">Mandatory</entry> + <entry align="left">Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>name</entry> + <entry>Yes</entry> + <entry>Property name</entry> + </row> + <row> + <entry>value</entry> + <entry>Yes</entry> + <entry>Property value</entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + <sect2> + <title>parameter</title> + <para>Multi value parameter that will be passed to testsuite execution</para> + <example> + <programlisting> + <![CDATA[ +<parameter name="parameterOne> + <value>valueOne</value> + <value>valueTwo</value> +</parameter> + +<parameter name="parameterTwo> + <value>valueOne</value> + <value>valueTwo</value> +</parameter> + ]]> + </programlisting> + </example> + + <table frame="all"> + <title>&lt;parameter&gt; element</title> + <tgroup cols="4" align="left" colsep="1" rowset="1"> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <colspec colname='c4'/> + <thead> + <row> + <entry align="center">Element</entry> + <entry align="center">Attribute</entry> + <entry align="center">Mandatory</entry> + <entry align="left">Description</entry> + </row> + </thead> + <tbody> + <row> + <entry/> + <entry>name</entry> + <entry>Yes</entry> + <entry>Parameter name</entry> + </row> + <row> + <entry>value</entry> + <entry/> + <entry>Yes</entry> + <entry>Parameter value</entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + <sect2> + <title>reports</title> + <para></para> + <example> + <programlisting> + <![CDATA[ +<!-- reports specified for specific <tests> override global --> +<reports noconsole="true"> + <html dir=""> +</reports> + ]]> + </programlisting> + </example> + + <table frame="all"> + <title>&lt;reports&gt; element</title> + <tgroup cols="4" align="left" colsep="1" rowset="1"> + <colspec colname='c1'/> + <colspec colname='c2'/> + <colspec colname='c3'/> + <colspec colname='c4'/> + <thead> + <row> + <entry align="center">Element</entry> + <entry align="center">Attribute</entry> + <entry align="center">Mandatory</entry> + <entry align="left">Description</entry> + </row> + </thead> + <tbody> + <row> + <entry/> + <entry>noconsole</entry> + <entry>No</entry> + <entry>Disables console output</entry> + </row> + <row> + <entry>html</entry> + <entry/> + <entry>No</entry> + <entry>Directory to store html reports</entry> + </row> + <row> + <entry>xml</entry> + <entry/> + <entry>No</entry> + <entry>Directory to store xml reports in JUnit format</entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + + + </sect1> + <sect1> + <title>Common Ant and Maven options</title> + <para> + In both ant and maven builds you can force configuration changes from commandline. It is very usefull in situations + when you need to run specific tests cases or enable JPDA support just for a single testsuite run without modification + in pom.xml or build.xml files. + </para> + <para> + With this approach you can alter JBoss Unit configuration on three levels: + <itemizedlist> + <listitem><emphasis>jboss-unit.xml</emphasis> configuration file</listitem> + <listitem>build file configuration (<emphasis>build.xml</emphasis> or <emphasis>pom.xml</emphasis>)</listitem> + <listitem>build framework commanline invocation</listitem> + </itemizedlist> + </para> + <sect2> + <title>jboss.unit.tests</title> + <para>Execute only specified testcases. Coma separated list of testcase ids should be used as an argument</para> + <example> + <programlisting> + <![CDATA[ +# ant -Djboss.unit.tests=testOne,testTwo + +# mvn -Djboss.unit.tests=testCaseThree + ]]> + </programlisting> + </example> + </sect2> + <sect2> + <title>jboss.unit.jpda</title> + <para>Enable or disable JPDA support</para> + <example> + <programlisting> + <![CDATA[ +# ant -Djboss.unit.jpda=true + +# mvn -Djboss.unit.jpda=false + ]]> + </programlisting> + </example> + </sect2> + <sect2> + <title>jboss.unit.jpda.port</title> + <para>Specify port for JPDA connection</para> + <example> + <programlisting> + <![CDATA[ +# ant -Djboss.unit.jpda.port=9999 + +# mvn -Djboss.unit.jpda.port=8888 + ]]> + </programlisting> + </example> + </sect2> + <sect2> + <title>jboss.unit.jpda.suspend</title> + <para>JPDA suspend mode</para> + <example> + <programlisting> + <![CDATA[ +# ant -Djboss.unit.suspend=true + +# mvn -Djboss.unit.suspend=false + ]]> + </programlisting> + </example> + </sect2> + <sect2> + <title>jboss.unit.assertions</title> + <para>Enable or disable Java Assertions</para> + <example> + <programlisting> + <![CDATA[ +# ant -Djboss.unit.assertions=true + +# mvn -Djboss.unit.assertions=false + ]]> + </programlisting> + </example> + </sect2> + <sect2> + <title>jboss.unit.failonerror</title> + <para>Configure if build should fail on testcase failure</para> + <example> + <programlisting> + <![CDATA[ +# ant -Djboss.unit.failonerror=true + +# mvn -Djboss.unit.failonerror=false + ]]> + </programlisting> + </example> + </sect2> + <sect2> + <title>jboss.unit.property</title> + <para>Single property value</para> + <example> + <programlisting> + <![CDATA[ +# ant -Djboss.unit.property.name1=value + +# mvn -Djboss.unit.property.name2=value2 + ]]> + </programlisting> + </example> + </sect2> + <sect2> + <title>jboss.unit.properties</title> + <para>Several name=value pairs for properties</para> + <example> + <programlisting> + <![CDATA[ + +# ant -Djboss.unit.properties=[name1=value1,name2=value2] + +# mvn -Djboss.unit.properties=[name1=value1] + + ]]> + </programlisting> + </example> + </sect2> + <sect2> + <title>jboss.unit.parameter</title> + <para>Single parameter values</para> + <example> + <programlisting> + <![CDATA[ +# ant -Djboss.unit.parameter.a=[b,c,d] + +# mvn -Djboss.unit.parameter.e=f + ]]> + </programlisting> + </example> + </sect2> + <sect2> + <title>jboss.unit.parameters</title> + <para>Several name=value paris for parameters. If single name is specified few times, sum of all + provided values will be passed</para> + <example> + <programlisting> + <![CDATA[ +# ant -Djboss.unit.parameters=[name=value1,name=value2,name2=value] + +# mvn -Djboss.unit.parameters=[name3=value1] + ]]> + </programlisting> + </example> + <para></para> + </sect2> + + <!--<sect2>--> + <!--<title>jboss.unit.logging</title>--> + <!--<para></para>--> + <!--</sect2>--> + + </sect1> + + + + + +</chapter>