[webbeans-commits] Webbeans SVN: r3204 - tck/trunk/doc/reference/en-US.

Author: pete.muir(a)jboss.org Date: 2009-07-24 15:04:31 -0400 (Fri, 24 Jul 2009) New Revision: 3204 Modified: tck/trunk/doc/reference/en-US/eclipse-running.xml Log: ws Modified: tck/trunk/doc/reference/en-US/eclipse-running.xml =================================================================== --- tck/trunk/doc/reference/en-US/eclipse-running.xml 2009-07-24 18:57:25 UTC (rev 3203) +++ tck/trunk/doc/reference/en-US/eclipse-running.xml 2009-07-24 19:04:31 UTC (rev 3204) @@ -1,19 +1,55 @@ <?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> <chapter id="eclipse-running"> - <title>Running Tests in Eclipse</title> - <para>This chapter explains how to run individual tests using the Eclipse TestNG plugin. It covers running non-integration tests in standalone mode and integration tests (as well as non-integration tests) in in-container mode. You should be able to use the lessons learned here to debug tests in an alternate IDE.</para> - <section> - <title>Leveraging Eclipse&apos;s plugin ecosystem</title> - <para>The primary motivation for building the test harness on top of an existing testing framework is to allow the tests to be executed and debugged in an Integrated Development Environment (IDE) using availalbe plugins. It&apos;s also the easiest way to execute a test class in isolation.</para> - <para>The TCK can be executed in any IDE for which there is a TestNG plugin available. Running a test in Eclipse is almost as simple as running the test with the Eclipse TestNG plugin. You can also use the plugin to debug a test, which is described in the next chapter.</para> - <para>Before running a test from the TCK test suite in Eclipse, you must have the Eclipse <ulink url="http://testng.org">TestNG plugin</ulink> and the m2eclipse plugin installed. Refer to section 2.2.2 for more information on these plugins.</para> - <para>With the m2eclipse plugin installed, Eclipse should recognize the JSR-299 TCK projects as valid Eclipse projects (or any Web Beans project for that matter). Import them into the Eclipse workspace at this time. You should also import the JSR-299 RI projects if you want to debug into that code, which is covered later.</para> - </section> - <section> - <title>Readying the Eclipse workspace</title> - <para>When setting up your Ecilpse workspace, I recommend creating three workings sets: one for the JSR-299 RI (Web Beans), one for the JSR-299 TCK and one for the JBoss TCK Runner. The dependencies between the projects will be established automatically by the m2eclipse plugin based on the dependency information in the pom.xml files. Your workspace should appear as follows:</para> - <programlisting>JSR-299 RI + <title>Running Tests in Eclipse</title> + <para> + This chapter explains how to run individual tests using the Eclipse + TestNG plugin. It covers running non-integration tests in standalone mode + and integration tests (as well as non-integration tests) in in-container + mode. You should be able to use the lessons learned here to debug tests in + an alternate IDE. + </para> + <section> + <title>Leveraging Eclipse's plugin ecosystem</title> + <para> + The primary motivation for building the test harness on top of an + existing testing framework is to allow the tests to be executed and + debugged in an Integrated Development Environment (IDE) using available + plugins. It's also the easiest way to execute a test class in + isolation. + </para> + <para> + The TCK can be executed in any IDE for which there is a TestNG + plugin available. Running a test in Eclipse is almost as simple as + running the test with the Eclipse TestNG plugin. You can also use the + plugin to debug a test, which is described in the next chapter. + </para> + <para> + Before running a test from the TCK test suite in Eclipse, you must have + the Eclipse + <ulink url="http://testng.org">TestNG plugin</ulink> + and the m2eclipse plugin installed. Refer to section 2.2.2 for more + information on these plugins. + </para> + <para> + With the m2eclipse plugin installed, Eclipse should recognize the + JSR-299 TCK projects as valid Eclipse projects (or any Web Beans + project for that matter). Import them into the Eclipse workspace at + this time. You should also import the JSR-299 RI projects if you want + to debug into that code, which is covered later. + </para> + </section> + <section> + <title>Readying the Eclipse workspace</title> + <para> + When setting up your Ecilpse workspace, I recommend creating three + workings sets: one for the JSR-299 RI (Web Beans), one for the JSR-299 + TCK and one for the JBoss TCK Runner. The dependencies between the + projects will be established automatically by the m2eclipse plugin + based on the dependency information in the pom.xml files. Your + workspace should appear as follows: + </para> + <programlisting>JSR-299 RI jsr299-api webbeans-api webbeans-core @@ -29,126 +65,299 @@ Web Beans JBoss TCK Runner webbeans-jboss-tck-runner webbeans-porting-package</programlisting> - <para>The tests in the TCK test suite are located in the jsr299-tck-impl project. You&apos;ll be working within this project in Eclipse when you are developing tests. However, you learned earlier, there are no references to a JSR-299 implementation in the TCK. So how can you execute an individual test in Eclipse? The secret is that you need to establish a link in Eclipse (not in Maven) between the jsr299-tck-impl project and your TCK runner project, which in this case is webbeans-jboss-tck-runner. Here are the steps to establish the link:</para> - <orderedlist> - <listitem> - <para>Right click on the jsr299-tck-impl project</para> - </listitem> - <listitem> - <para>Select Build Path &gt; Configure Build Path...</para> - </listitem> - <listitem> - <para>Click on the Projects tab</para> - </listitem> - <listitem> - <para>Click the Add... button on the right</para> - </listitem> - <listitem> - <para>Check the TCK runner project (e.g., webbeans-jboss-tck-runner)</para> - </listitem> - <listitem> - <para>Click the OK button on the Required Project Selection dialog window</para> - </listitem> - <listitem> - <para>Click the OK button on the Java Build Path window</para> - </listitem> - </orderedlist> - <para>The TCK runner project should pull in the JSR-299 implementation, the TCK porting package and any additional properties that must be defined to execute the TCK test suite.</para> - </section> - <section> - <title>Running a test in standalone mode</title> - <para>Your now ready to execute an individual test class (a class which extends AbstractJSR299Test and is annotated with @Artifact). Select a test class that is <emphasis role="italic">not</emphasis> annotated with <literal>@IntegrationTest</literal> and open it in the Eclipse editor. Right click in the editor view and select TestNG &gt; Run as test. The TestNG view should pop out and you should see all the tests pass (hopefully).</para> - <note> - <para>If the TCK complains that there is a property missing, close all the projects, open them again, and rebuild. The m2eclipse plugin can be finicky getting everything built correctly the first time.</para> - </note> - <para>So far you have executed a test in standalone mode. That&apos;s not sufficient to pass the TCK. The test must be executed in in-container mode. Using in-container mode also the only way to execute a test annotated with <literal>@IntegrationTest</literal> as it requires container resources. So let&apos;s see what has to be done to execute an integration test. This will result in the artifact being deployed to the container, which is JBoss AS 5.1 if you are using the JBoss TCK runner.</para> - </section> - <section> - <title>Running integration tests</title> - <para>As you have learned, the JBoss test harness determines how to behave based on the values of numerous system properties or properties defined in META-INF/jboss-test-harness.properties classpath resources. If the property named <literal>org.jboss.testharness.standalone</literal> is not defined, the harness assumes that the test is to be run in standalone mode. In order to run the tests in the container, you need to add a properties file to the classpath that sets the standalone property to false and provides values for other properties required to run an in-container test.</para> - <para>The JBoss TCK runner project conveniently provides the properties file src/test/debug-resources/META-INF/jboss-test-harness.properties that contains all of the necessary properties. You may have to tune the <literal>org.jboss.testharness.container.extraConfigurationDir</literal> and <literal>org.jboss.testharness.libraryDirectory</literal> properties to point to the relative location of the related projects. The properties should be defined as follows:</para> - <itemizedlist> - <listitem> - <para><literal>org.jboss.testharness.container.extraConfigurationDir</literal> - the relative path from the jboss-tck-impl project to a directory that contains a build.properties or local.build.properties file defining the location of a JBoss AS 5.1 installation in the <literal>jboss.home</literal> property</para> - </listitem> - <listitem> - <para><literal>org.jboss.testharness.libraryDirectory</literal> - the relative path from the jboss-tck-impl project to the target/dependency/lib directory in the TCK runner project.</para> - </listitem> - </itemizedlist> - <para>The other properties in that file are defined as follows:</para> - <programlisting>org.jboss.testharness.standalone=false + <para> + The tests in the TCK test suite are located in the jsr299-tck-impl + project. You'll be working within this project in Eclipse when you are + developing tests. However, you learned earlier, there are no references + to a JSR-299 implementation in the TCK. So how can you execute an + individual test in Eclipse? The secret is that you need to establish a + link in Eclipse (not in Maven) between the jsr299-tck-impl project and + your TCK runner project, which in this case is + webbeans-jboss-tck-runner. Here are the steps to establish the link: + </para> + <orderedlist> + <listitem> + <para> + Right click on the jsr299-tck-impl project + </para> + </listitem> + <listitem> + <para> + Select Build Path &gt; Configure Build Path... + </para> + </listitem> + <listitem> + <para> + Click on the Projects tab + </para> + </listitem> + <listitem> + <para> + Click the Add... button on the right + </para> + </listitem> + <listitem> + <para> + Check the TCK runner project (e.g., webbeans-jboss-tck-runner) + </para> + </listitem> + <listitem> + <para> + Click the OK button on the Required Project Selection dialog + window + </para> + </listitem> + <listitem> + <para> + Click the OK button on the Java Build Path window + </para> + </listitem> + </orderedlist> + <para> + The TCK runner project should pull in the JSR-299 implementation, + the TCK porting package and any additional properties that must be + defined to execute the TCK test suite. + </para> + </section> + <section> + <title>Running a test in standalone mode</title> + <para> + Your now ready to execute an individual test class (a class which + extends AbstractJSR299Test and is annotated with @Artifact). Select a + test class that is + <emphasis role="italic">not</emphasis> + annotated with + <literal>@IntegrationTest</literal> + and open it in the Eclipse editor. Right click in the editor view and + select TestNG &gt; Run as test. The TestNG view should pop out and you + should see all the tests pass (hopefully). + </para> + <note> + <para> + If the TCK complains that there is a property missing, close all + the projects, open them again, and rebuild. The m2eclipse plugin can + be finicky getting everything built correctly the first time. + </para> + </note> + <para> + So far you have executed a test in standalone mode. That's not + sufficient to pass the TCK. The test must be executed in in-container + mode. Using in-container mode also the only way to execute a test + annotated with + <literal>@IntegrationTest</literal> + as it requires container resources. So let's see what has to be done to + execute an integration test. This will result in the artifact being + deployed to the container, which is JBoss AS 5.1 if you are using the + JBoss TCK runner. + </para> + </section> + <section> + <title>Running integration tests</title> + <para> + As you have learned, the JBoss test harness determines how to behave + based on the values of numerous system properties or properties defined + in META-INF/jboss-test-harness.properties classpath resources. If the + property named + <literal>org.jboss.testharness.standalone</literal> + is not defined, the harness assumes that the test is to be run in + standalone mode. In order to run the tests in the container, you need + to add a properties file to the classpath that sets the standalone + property to false and provides values for other properties required to + run an in-container test. + </para> + <para> + The JBoss TCK runner project conveniently provides the properties file + src/test/debug-resources/META-INF/jboss-test-harness.properties that + contains all of the necessary properties. You may have to tune the + <literal>org.jboss.testharness.container.extraConfigurationDir + </literal> + and + <literal>org.jboss.testharness.libraryDirectory</literal> + properties to point to the relative location of the related projects. + The properties should be defined as follows: + </para> + <itemizedlist> + <listitem> + <para> + <literal>org.jboss.testharness.container.extraConfigurationDir + </literal> + - the relative path from the jboss-tck-impl project to a + directory that contains a build.properties or + local.build.properties file defining the location of a JBoss AS + 5.1 installation in the + <literal>jboss.home</literal> + property + </para> + </listitem> + <listitem> + <para> + <literal>org.jboss.testharness.libraryDirectory</literal> + - the relative path from the jboss-tck-impl project to the + target/dependency/lib directory in the TCK runner project. + </para> + </listitem> + </itemizedlist> + <para> + The other properties in that file are defined as follows: + </para> + <programlisting>org.jboss.testharness.standalone=false orjboss.testharness.container.forceRestart=false orjboss.testharness.runIntegrationTests=true</programlisting> - <para>You&apos;re now ready to execute an integration test. Select an integration test (a class that extends <literal>AbstractJSR299Test</literal> and is annotated with both <literal>@Artifact</literal> and <literal>@IntegrationTest</literal>) and open it in your Eclipse editor. Follow these steps to execute the class with the TestNG plugin:</para> - <orderedlist> - <listitem> - <para>Right click in the editor view and select TestNG &gt; Run as test</para> - </listitem> - <listitem> - <para>Observe the test fail because of missing dependencies</para> - </listitem> - <listitem> - <para>Select the Run &gt; Run Configurations... menu from the main menubar</para> - </listitem> - <listitem> - <para>Select the name of the test class under the TestNG category</para> - </listitem> - <listitem> - <para>Select the Classpath tab</para> - </listitem> - <listitem> - <para>Select User Entries in the tree</para> - </listitem> - <listitem> - <para>Click the Advanced... button on the right</para> - </listitem> - <listitem> - <para>Select Add Folders and click the OK button</para> - </listitem> - <listitem> - <para>Select the webbeans-jboss-tck-runner/src/test/debug-resources folder</para> - </listitem> - <listitem> - <para>Click the OK button on the Folder Selection dialog window</para> - </listitem> - <listitem> - <para>Click on the webbeans-jboss-tck-runner entry</para> - </listitem> - <listitem> - <para>Move the webbeans-jboss-tck-runner to the first entry using the Up button</para> - </listitem> - <listitem> - <para>Click the Run button on the Run Configurations dialog window</para> - </listitem> - </orderedlist> - <para>When you run the test this time, it should pass. If you get a failure that the container (e.g., JBoss AS 5.1) must be run with assertions enabled, you need to stop the container and start it with the -ea flag (or just leave it stopped and the test will start it appropriately). </para> - <para>You can simply right click and select TestNG &gt; Run as test for all subsequent runs for the reason cited earlier, the run configuration for a class is retained indefinitely.</para> - <para>Alternatively, you can configure TestNG to execute all tests in-container by default by adding the properties file in the debug-resources folder to the project&apos;s classpath as follows:</para> - <orderedlist> - <listitem> - <para>Right click on the jsr299-tck-impl project</para> - </listitem> - <listitem> - <para>Select Build Path &gt; Configure Build Path...</para> - </listitem> - <listitem> - <para>Click on the Libraries tab</para> - </listitem> - <listitem> - <para>Click the Add Class Folder... button on the right</para> - </listitem> - <listitem> - <para>Check the webbeans-jboss-tck-runner/src/test/debug-resources folder</para> - </listitem> - <listitem> - <para>Click the OK button on the Class Folder Selection dialog window</para> - </listitem> - <listitem> - <para>Click the OK button on the Java Build Path window</para> - </listitem> - </orderedlist> - <para>Now you don&apos;t have to do any special configuration for each test class.</para> - <para>You can stop the individual tests from running in-container by reversing the steps above to remove the debug-resources folder from the Eclipse classpath. </para> - <para>You have now mastered running the JSR-299 TCK against the JSR-299 RI using both Maven 2 and within Eclipse. Now you&apos;re likely interested in how to debug a test so that you can efficiently investigate test failures.</para> - </section> + <para> + You're + now ready to execute an integration test. Select an integration + test (a + class that extends + <literal>AbstractJSR299Test</literal> + and is annotated with both + <literal>@Artifact</literal> + and + <literal>@IntegrationTest</literal> + ) and open it in your Eclipse editor. Follow these steps to execute the + class with the TestNG plugin: + </para> + <orderedlist> + <listitem> + <para> + Right click in the editor view and select TestNG &gt; Run as + test + </para> + </listitem> + <listitem> + <para> + Observe the test fail because of missing dependencies + </para> + </listitem> + <listitem> + <para> + Select the Run &gt; Run Configurations... menu from the main + menubar + </para> + </listitem> + <listitem> + <para> + Select the name of the test class under the TestNG category + </para> + </listitem> + <listitem> + <para> + Select the Classpath tab + </para> + </listitem> + <listitem> + <para> + Select User Entries in the tree + </para> + </listitem> + <listitem> + <para> + Click the Advanced... button on the right + </para> + </listitem> + <listitem> + <para> + Select Add Folders and click the OK button + </para> + </listitem> + <listitem> + <para> + Select the webbeans-jboss-tck-runner/src/test/debug-resources + folder + </para> + </listitem> + <listitem> + <para> + Click the OK button on the Folder Selection dialog window + </para> + </listitem> + <listitem> + <para> + Click on the webbeans-jboss-tck-runner entry + </para> + </listitem> + <listitem> + <para> + Move the webbeans-jboss-tck-runner to the first entry using + the Up button + </para> + </listitem> + <listitem> + <para> + Click the Run button on the Run Configurations dialog window + </para> + </listitem> + </orderedlist> + <para> + When you run the test this time, it should pass. If you get a + failure that the container (e.g., JBoss AS 5.1) must be run with + assertions enabled, you need to stop the container and start it with + the -ea flag (or just leave it stopped and the test will start it + appropriately). + </para> + <para> + You can simply right click and select TestNG &gt; Run as test for + all subsequent runs for the reason cited earlier, the run configuration + for a class is retained indefinitely. + </para> + <para> + Alternatively, you can configure TestNG to execute all tests + in-container by default by adding the properties file in the + debug-resources folder to the project's classpath as follows: + </para> + <orderedlist> + <listitem> + <para> + Right click on the jsr299-tck-impl project + </para> + </listitem> + <listitem> + <para> + Select Build Path &gt; Configure Build Path... + </para> + </listitem> + <listitem> + <para> + Click on the Libraries tab + </para> + </listitem> + <listitem> + <para> + Click the Add Class Folder... button on the right + </para> + </listitem> + <listitem> + <para> + Check the webbeans-jboss-tck-runner/src/test/debug-resources + folder + </para> + </listitem> + <listitem> + <para> + Click the OK button on the Class Folder Selection dialog + window + </para> + </listitem> + <listitem> + <para> + Click the OK button on the Java Build Path window + </para> + </listitem> + </orderedlist> + <para> + Now you don't have to do any special configuration for each + test + class. + </para> + <para> + You can stop the individual tests from running in-container by + reversing the steps above to remove the debug-resources folder from the + Eclipse classpath. + </para> + <para> + You have now mastered running the JSR-299 TCK against the JSR-299 RI + using both Maven 2 and within Eclipse. Now you're likely interested in + how to debug a test so that you can efficiently investigate test + failures. + </para> + </section> </chapter>