[jboss-svn-commits] JBoss Common SVN: r4080 - in arquillian/trunk/doc/reference/src/main/docbook/en-US: images and 1 other directory.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Thu Mar 4 02:12:28 EST 2010
Author: dan.j.allen
Date: 2010-03-04 02:12:27 -0500 (Thu, 04 Mar 2010)
New Revision: 4080
Added:
arquillian/trunk/doc/reference/src/main/docbook/en-US/images/maven-properties-screen.png
arquillian/trunk/doc/reference/src/main/docbook/en-US/images/netbeans-green-bar.png
arquillian/trunk/doc/reference/src/main/docbook/en-US/images/netbeans-project-configuration.png
arquillian/trunk/doc/reference/src/main/docbook/en-US/images/spi-overview-small.png
Modified:
arquillian/trunk/doc/reference/src/main/docbook/en-US/containers.xml
arquillian/trunk/doc/reference/src/main/docbook/en-US/extend.xml
arquillian/trunk/doc/reference/src/main/docbook/en-US/gettingstarted.xml
arquillian/trunk/doc/reference/src/main/docbook/en-US/intro.xml
arquillian/trunk/doc/reference/src/main/docbook/en-US/master.xml
arquillian/trunk/doc/reference/src/main/docbook/en-US/preface.xml
Log:
ARQ-65
clarify the container types as defined in the mission statement
beef up getting started guide
show Maven configuration above supported container table
Modified: arquillian/trunk/doc/reference/src/main/docbook/en-US/containers.xml
===================================================================
--- arquillian/trunk/doc/reference/src/main/docbook/en-US/containers.xml 2010-03-01 14:44:20 UTC (rev 4079)
+++ arquillian/trunk/doc/reference/src/main/docbook/en-US/containers.xml 2010-03-04 07:12:27 UTC (rev 4080)
@@ -5,11 +5,11 @@
<title>Target containers</title>
<para>
- Arquillian's power is not only in its ease of use, but also in its flexibility. Good integration testing is not
- just about testing in <emphasis>any</emphasis> container, but rather testing in the container you are targeting.
- It's all too easy to kid ourselves by tweaking our components to run in a specialized testing container, only to
- realize that certain assumptions don't apply in the real environment and ultimately the components fail when it
- comes time to deploy for real.
+ Arquillian's forte is not only in its ease of use, but also in its flexibility. Good integration testing is not
+ just about testing in <emphasis>any</emphasis> container, but rather testing in the container
+ <emphasis>you</emphasis> are targeting. It's all too easy to kid ourselves by validating components in a
+ specialized testing container, only to realize that the small variations causes the components fail when it comes
+ time to deploy to the application for real. To make tests count, you want to execute them in the real container.
</para>
<para>
@@ -21,19 +21,33 @@
<title>Container varieties</title>
<para>
- There are three types of target containers that you can use to run your Arquillian tests:
+ There are two styles of containers that you can target in Arquillian:
</para>
<orderedlist>
<listitem>
- <para>A standalone (remote) container</para>
+ <para>remote — resides in a separate JVM from the test runner; its lifecycle may be managed by Arquillian,
+ or Arquillian may bind to a container that is already started</para>
</listitem>
<listitem>
- <para>An embedded container</para>
+ <para>embedded — resides in the same JVM as the test runner; its lifecycle is likely managed by Arquillian</para>
</listitem>
+ </orderedlist>
+
+ <para>
+ Containers can be further classified by their capabilities. There are three common catagories:
+ </para>
+
+ <orderedlist>
<listitem>
- <para>A Java SE bean container</para>
+ <para>A fully compliant Java EE application server (e.g., GlassFish, JBoss AS, Embedded GlassFish)</para>
</listitem>
+ <listitem>
+ <para>A Servlet container (e.g., Jetty, Tomcat)</para>
+ </listitem>
+ <listitem>
+ <para>A standalone bean container (e.g., Weld SE, Spring)</para>
+ </listitem>
</orderedlist>
<para>
@@ -49,9 +63,24 @@
<para>
The implementations provided so far are shown in the table below. Also listed is the artifactId of the JAR that
- provides the implementation.
+ provides the implementation. To execute your tests against a container, you must include the artifactId that
+ corresponds to that container on the classpath. Use the following Maven profile definition as a template to add
+ support for a container to your Maven build, replacing %artifactId% with the artifactId from the table. You
+ then activate the profile when executing the tests just as you did in the <xref linkend="gettingstarted"/>
+ chapter.
</para>
+ <programlisting role="XML"><![CDATA[<profile>
+ <id>%artifactId%</id>
+ <dependencies>
+ <dependency>
+ <groupId>org.jboss.arquillian</groupId>
+ <artifactId>arquillian-%artifactId%</artifactId>
+ <version>${arquillian.version}</version>
+ </dependency>
+ </dependencies>
+</profile>]]></programlisting>
+
<table frame="all">
<title>Target containers supported by Arquillian</title>
<tgroup cols="4">
@@ -70,31 +99,31 @@
<tbody>
<row>
<entry>JBoss AS 5.1</entry>
- <entry>standalone</entry>
+ <entry>remote</entry>
<entry>Java EE 5</entry>
<entry>arquillian-jboss-remote-51</entry>
</row>
<row>
<entry>JBoss AS 6.0 M1</entry>
- <entry>standalone container</entry>
+ <entry>remote</entry>
<entry>Java EE 6</entry>
<entry>arquillian-jboss-remote-60</entry>
</row>
<row>
<entry>JBoss Embedded AS</entry>
- <entry>embedded container</entry>
+ <entry>embedded</entry>
<entry>Java EE 6</entry>
<entry>arquillian-jboss-embedded</entry>
</row>
<row>
<entry>Embedded GlassFish V3</entry>
- <entry>embedded container</entry>
+ <entry>embedded</entry>
<entry>Java EE 6</entry>
<entry>arquillian-glassfish-embedded</entry>
</row>
<row>
<entry>Weld SE</entry>
- <entry>Java SE bean container</entry>
+ <entry>embedded</entry>
<entry>CDI</entry>
<entry>arquillian-weld-embedded</entry>
</row>
@@ -103,15 +132,13 @@
</table>
<para>
- Support for other containers is planned, including GlassFish V3, Tomcat and Jetty. We don't plan to provide
- implementations for Spring or Guice, but we welcome a contribution from the community, because it's certainly
- possible.
+ Support for other containers is planned, including GlassFish V3, Tomcat and Jetty. We don't have plans to
+ provide implementations for Spring or Guice at this time, but we welcome a contribution from the community,
+ because it's certainly possible.
</para>
</section>
- <!-- FIXME: this chapter may not be complete -->
-
<!--
vim:et:ts=3:sw=3:tw=120
-->
Modified: arquillian/trunk/doc/reference/src/main/docbook/en-US/extend.xml
===================================================================
--- arquillian/trunk/doc/reference/src/main/docbook/en-US/extend.xml 2010-03-01 14:44:20 UTC (rev 4079)
+++ arquillian/trunk/doc/reference/src/main/docbook/en-US/extend.xml 2010-03-04 07:12:27 UTC (rev 4080)
@@ -4,8 +4,28 @@
<chapter id="extend">
<title>Extending Arquillian</title>
- <!-- TODO -->
+ <para>
+ Arquillian is designed to be very extensible. This is accomplished through the use of Service Provider Interfaces
+ (SPIs). The following diagram shows how the various SPIs in Arquillian tie into the test execution.
+ </para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/spi-overview-small.png" format="PNG" align="center"/>
+ </imageobject>
+ <caption>
+ <para>Arquillian test execution and SPI overview</para>
+ </caption>
+ </mediaobject>
+
+ <para>
+ This chapter will identify each of the SPIs and the purpose it serves.
+ </para>
+
+ <para>
+ TODO: Finish me
+ </para>
+
<section id="extend.deployment">
<title>@Deployment</title>
<para></para>
Modified: arquillian/trunk/doc/reference/src/main/docbook/en-US/gettingstarted.xml
===================================================================
--- arquillian/trunk/doc/reference/src/main/docbook/en-US/gettingstarted.xml 2010-03-01 14:44:20 UTC (rev 4079)
+++ arquillian/trunk/doc/reference/src/main/docbook/en-US/gettingstarted.xml 2010-03-04 07:12:27 UTC (rev 4080)
@@ -8,23 +8,34 @@
<para>
We've promised you that integration testing with Arquillian is no more complicated than writing a unit test. Now
it's time to prove it to you. In this chapter, we'll look at what is required to setup Arquillian in your
- project, how to write an Arquillian test case, how to execute the test case and produce the test results, and
- finally how to debug an test. That sounds like a lot, but you'll be writing your own Arquillian tests in no time.
+ project, how to write an Arquillian test case, how to execute the test case and how the test results are
+ displayed. That sounds like a lot, but you'll be writing your own Arquillian tests in no time. (You'll also learn
+ about <xref linkend="debugging"/> in Chapter 7).
</para>
<section>
- <title>Setting up Arquillian in your Maven 2 project</title>
+ <title>Setting up Arquillian in a Maven project</title>
<para>
The quickest way to get started with Arquillian is to add it to an existing Maven 2 project. Regardless of
- whether you plan to use Maven 2 as your project build, we recommend that you take your first steps with
+ whether you plan to use Maven as your project build, we recommend that you take your first steps with
Arquillian this way so as to get to your first green bar with the least amount of distraction.
</para>
<para>
- You'll first need to decide whether you are going to write tests in JUnit 4.x or TestNG 5.x. Once you make that
+ The first thing you should do is define a Maven property for the version of Arquillian you are going to use.
+ This way, you only have to maintain the version in one place and can reference it using the Maven variable
+ syntax everywhere else in your build file.
+ </para>
+
+ <programlisting role="XML"><![CDATA[<properties>
+ <arquillian.version>1.0.0-Alpha1</arquillian.version>
+</properties>]]></programlisting>
+
+ <para>
+ Next, you'll need to decide whether you are going to write tests in JUnit 4.x or TestNG 5.x. Once you make that
decision (use TestNG if you're not sure), you'll need to add either the JUnit or TestNG library to your test
- build path and the corresponding Arquillian library.
+ build path as well as the corresponding Arquillian library.
</para>
<para>
@@ -42,12 +53,12 @@
<dependency>
<groupId>org.jboss.arquillian</groupId>
<artifactId>arquillian-junit</artifactId>
- <version>1.0.0-SNAPSHOT</version>
+ <version>${arquillian.version}</version>
<scope>test</scope>
</dependency>]]></programlisting>
<para>
- If you plan to use <emphasis>TestNG</emphasis>, add these two test-scoped dependencies instead:
+ If you plan to use <emphasis>TestNG</emphasis>, then add these two test-scoped dependencies instead:
</para>
<programlisting role="XML"><![CDATA[<dependency>
@@ -61,7 +72,7 @@
<dependency>
<groupId>org.jboss.arquillian</groupId>
<artifactId>arquillian-testng</artifactId>
- <version>1.0.0-SNAPSHOT</version>
+ <version>${arquillian.version}</version>
<scope>test</scope>
</dependency>]]></programlisting>
@@ -77,18 +88,23 @@
<para>
You're now going to write your first Arquillian test. But in order to write a test, we need to have something
- to test. So let's first create an stateless EJB session bean that we can invoke. Let's help out those Americans
- still trying to convert to the metric system by providing a Fahrenheit to Celsius converter. Although
- not required in Java EE 6, we'll include a local interface for the bean to ensure maximum portability.
+ to test. So let's first create a stateless EJB session bean that we can invoke.
</para>
+
+ <para>
+ We'll help out those Americans still trying to convert to the metric system by providing them a Fahrenheit to
+ Celcius converter. Although not required in Java EE 6, we'll include a local interface for the bean to ensure
+ maximum portability.
+ </para>
<para>
Here's our <literal>TemperatureConverter</literal> interface:
</para>
<programlisting role="JAVA"><![CDATA[public @Local interface TemperatureConverter {
- double convertToCelsius(double f);
+ double convertToCelcius(double f);
double convertToFarenheight(double c);
+ boolean isTransactional();
}]]></programlisting>
<para>
@@ -97,25 +113,41 @@
<programlisting role="JAVA"><![CDATA[public @Stateless class TemperatureConverterBean
implements TemperatureConverter {
- public double convertToCelsius(double f) {
+
+ private @Resource EJBContext ctx;
+
+ @Override
+ public double convertToCelcius(double f) {
return ((f - 32) * 5 / 9);
}
+ @Override
public double convertToFarenheight(double c) {
return ((c * 9 / 5) + 32);
}
+
+ @Override
+ public boolean isTransactional() {
+ ctx.setRollbackOnly();
+ return ctx.getRollbackOnly();
+ }
}]]></programlisting>
<para>
- Now we need to validate that this code runs. We'll create a test in the <literal>src/test/java</literal>
+ We've added an extra method to verify that we are in fact using a real EJB. The method uses the injected
+ <literal>EJBContext</literal> to ensure a container-managed transaction is present and functional.
+ </para>
+
+ <para>
+ Now we need to validate that this code runs. We'll be creating a test in the <literal>src/test/java</literal>
classpath of the project.
</para>
<para>
- In this trivial case, we could simply instantiate the implementation class in a unit test to test the
+ Granted, in this trivial case, we could simply instantiate the implementation class in a unit test to test the
calculations. However, let's assume that this bean is more complex, needing to access enterprise services. We
- want to test it as a full-blown EJB, not just as a simple bean instance. Therefore, we'll inject the EJB into
- the test class using the <literal>@EJB</literal> annotation.
+ want to test it as a full-blown EJB, a container-managed bean, not just as a simple class instance. Therefore,
+ we'll inject the EJB into the test class using the <literal>@EJB</literal> annotation.
</para>
<para>
@@ -147,7 +179,7 @@
<programlisting role="JAVA"><![CDATA[@Deployment
public static JavaArchive createTestArchive() {
return Archives.create("test.jar", JavaArchive.class)
- .addClasses(TemperatureConverter.class, TemperatureConverter.class);
+ .addClasses(TemperatureConverter.class, TemperatureConverterBean.class);
}]]></programlisting>
<para>
@@ -174,7 +206,7 @@
@Deployment
public static JavaArchive createTestArchive() {
return Archives.create("test.jar", JavaArchive.class)
- .addClasses(TemperatureConverter.class, TemperatureConverter.class);
+ .addClasses(TemperatureConverter.class, TemperatureConverterBean.class);
}
@Test
@@ -188,6 +220,11 @@
Assert.assertEquals(converter.convertToFarenheight(0d), 32d);
Assert.assertEquals(converter.convertToFarenheight(100d), 212d);
}
+
+ @Test
+ public void testIsTransactional() {
+ Assert.assertTrue(converter.isTransactional());
+ }
}]]></programlisting>
<para>
@@ -203,7 +240,7 @@
@Deployment
public static JavaArchive createTestArchive() {
return Archives.create("test.jar", JavaArchive.class)
- .addClasses(TemperatureConverter.class, TemperatureConverter.class);
+ .addClasses(TemperatureConverter.class, TemperatureConverterBean.class);
}
@Test
@@ -217,18 +254,25 @@
Assert.assertEquals(converter.convertToFarenheight(0d), 32d);
Assert.assertEquals(converter.convertToFarenheight(100d), 212d);
}
+
+ @Test
+ public void testIsTransactional() {
+ Assert.assertTrue(converter.isTransactional());
+ }
}]]></programlisting>
<para>
As you can see, we are not instantiating the bean implementation class directly, but rather using the EJB
- reference provided by the container, just as it would be used in the application. Now let's see if this baby
- passes!
+ reference provided by the container at the injection point, just as it would be used in the application. (If
+ the target container has CDI, you could replace the <literal>@EJB</literal> annotation with
+ <literal>@Inject</literal>, though you would also need to add beans.xml to the deployment manifest). Now let's
+ see if this baby passes!
</para>
</section>
<section>
- <title>Selecting a target container and running the test</title>
+ <title>Setting up and running the test in Maven</title>
<para>
As we've been emphasizing, this test is going to run inside of a container. That means you have to have a
@@ -266,7 +310,7 @@
<dependency>
<groupId>org.jboss.arquillian</groupId>
<artifactId>arquillian-jboss-remote-60</artifactId>
- <version>1.0.0-SNAPSHOT</version>
+ <version>${arquillian.version}</version>
</dependency>
</dependencies>
</profile>
@@ -274,7 +318,7 @@
<para>
You would setup a similar profile for each Arquillian-supported container in which you want your tests
- executed.
+ executed. <!-- reference to containers chapter for details -->
</para>
<para>
@@ -288,8 +332,122 @@
You should see that the two tests pass.
</para>
+ <programlisting><![CDATA[-------------------------------------------------------
+T E S T S
+-------------------------------------------------------
+Running TestSuite
+log4j:WARN No appenders could be found for logger (org.jnp.interfaces.TimedSocketFactory).
+log4j:WARN Please initialize the log4j system properly.
+Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.000 sec
+
+Results :
+
+Tests run: 3, Failures: 0, Errors: 0, Skipped: 0
+
+[INFO] ------------------------------------------------------------------------
+[INFO] BUILD SUCCESSFUL
+[INFO] ------------------------------------------------------------------------]]></programlisting>
+
+ <para>
+ The tests are passing, but we don't see a green bar. To get that visual, we need to run the tests in the IDE.
+ Arquillian tests can be executed using existing IDE plugins for JUnit and TestNG, respectively, or so you've
+ been told. It's once again time to prove it.
+ </para>
+
</section>
+ <section>
+ <title>Setting up and running the test in Eclipse</title>
+
+ <para>
+ Before running an Arquillian test in Eclipse, you must have the plugin for the unit testing framework you are
+ using installed. Eclipse ships with the JUnit plugin, so you are already setup if you selected JUnit. If you
+ are writing your tests with TestNG, you need the Eclipse <ulink url="http://testng.org">TestNG plugin</ulink>.
+ </para>
+
+ <para>
+ Since the example in this guide is based on a Maven 2 project, you will also need either the m2eclipse plugin
+ or an Eclipse project generated use the Maven 2 Eclipse plugin (<literal>maven-eclipse-plugin</literal>). The
+ m2eclipse plugin is your best bet because it provides native support for Maven 2 projects. Instructions for
+ using the m2eclipse update site to add the m2eclipse plugin to Eclipse are provided on the m2eclipse home page.
+ For more, read the m2eclipse <ulink url="http://www.sonatype.com/books/m2eclipse-book/reference">reference
+ guide</ulink>.
+ </para>
+
+ <para>
+ Once the plugins are installed, import your Maven project into the Eclipse workspace. Before executing the
+ test, you need to enable the profile for the target container, as you did in the previous section. We'll
+ go ahead and activate the profile globally for the project. Right click on the project and select Properties.
+ Select the Maven property sheet and in the first form field, enter <literal>jboss-remote-60</literal> as shown
+ here:
+ </para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/maven-properties-screen.png" format="PNG" align="center"/>
+ </imageobject>
+ <caption>
+ <para>Maven settings for project</para>
+ </caption>
+ </mediaobject>
+
+ <para>
+ Click OK and accept the project changes. Now you are ready to execute tests.
+ </para>
+
+ <para>
+ Right click on the TemperatureConverterTest.java file in the Package Explorer and select Run As... > JUnit Test
+ or Run As... > TestNG Test depending on which unit testing framework the test is using.
+ </para>
+
+ <para>TODO: screenshot</para>
+
+ </section>
+
+ <section>
+ <title>Setting up and running the test in NetBeans</title>
+
+ <para>
+ Things get even simpler when using NetBeans 6.8 or better. NetBeans ships with native Maven 2 support and,
+ rather than including a test plugin for each unit testing framework, it has a generic test plugin which
+ delegates to the Maven surefire plugin to execute the tests.
+ </para>
+
+ <para>
+ Import your Maven project into NetBeans. Then, look for a select menu in the main toolbar, which you can
+ use to set the active Maven profile. Select the <literal>jboss-remote-60</literal> profile as shown here:
+ </para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/netbeans-project-configuration.png" format="PNG" align="center"/>
+ </imageobject>
+ <caption>
+ <para>NetBeans project configuration</para>
+ </caption>
+ </mediaobject>
+
+ <para>
+ Now you are ready to test. Simply right click on the TemperatureConverter.java file in the Projects pane and
+ select Test File. NetBeans will delegate to the Maven surefire plugin to execute the tests and then
+ display the results in a result windown, showing us a pretty green bar!
+ </para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/netbeans-green-bar.png" format="PNG" align="center"/>
+ </imageobject>
+ <caption>
+ <para>Successful test report in NetBeans</para>
+ </caption>
+ </mediaobject>
+
+ </section>
+
+ <para>
+ As you can see, there was no special configuration necessary to execute the tests in either Eclipse or NetBeans.
+ </para>
+
<!--
vim:et:ts=3:sw=3:tw=120
-->
Added: arquillian/trunk/doc/reference/src/main/docbook/en-US/images/maven-properties-screen.png
===================================================================
(Binary files differ)
Property changes on: arquillian/trunk/doc/reference/src/main/docbook/en-US/images/maven-properties-screen.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: arquillian/trunk/doc/reference/src/main/docbook/en-US/images/netbeans-green-bar.png
===================================================================
(Binary files differ)
Property changes on: arquillian/trunk/doc/reference/src/main/docbook/en-US/images/netbeans-green-bar.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: arquillian/trunk/doc/reference/src/main/docbook/en-US/images/netbeans-project-configuration.png
===================================================================
(Binary files differ)
Property changes on: arquillian/trunk/doc/reference/src/main/docbook/en-US/images/netbeans-project-configuration.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: arquillian/trunk/doc/reference/src/main/docbook/en-US/images/spi-overview-small.png
===================================================================
(Binary files differ)
Property changes on: arquillian/trunk/doc/reference/src/main/docbook/en-US/images/spi-overview-small.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Modified: arquillian/trunk/doc/reference/src/main/docbook/en-US/intro.xml
===================================================================
--- arquillian/trunk/doc/reference/src/main/docbook/en-US/intro.xml 2010-03-01 14:44:20 UTC (rev 4079)
+++ arquillian/trunk/doc/reference/src/main/docbook/en-US/intro.xml 2010-03-04 07:12:27 UTC (rev 4080)
@@ -5,29 +5,70 @@
<title>Introduction</title>
<para>
- We believe that integration testing should be no more complex than writing a simple unit test. We created
+ We believe that integration testing should be no more complex than writing a basic unit test. We created
Arquillian to realize that goal. One of the major complaints we heard about Seam 2 testing (i.e., SeamTest) was,
- not that it wasn't possible, but that it wasn't flexible and it was difficult to setup.
+ not that it isn't possible, but that it isn't flexible and it's difficult to setup. We wanted to correct those
+ shortcomings with Arquillian.
</para>
<para>
- People test in a myriad of ways, which is why it's so vital that, with Arquillian (and ShrinkWrap), we have
- decomposed the problem into its essential elements. The result is a completely flexible and portable integration
- testing framework.
+ Testing needs vary greatly, which is why it's so vital that, with Arquillian (and ShrinkWrap), we have decomposed
+ the problem into its essential elements. The result is a completely flexible and portable integration testing
+ framework.
</para>
<section id="mission">
<title>Mission statement</title>
<para>
- The mission of the Arquillian project is to provide a simple mechanism to test application code inside a
- container. Since the last thing Java developers want is yet another testing framework to make their life more
- complicated, Arquillian integrates transparently with familiar testing frameworks (JUnit 4 and TestNG 5) by
- performing runtime packaging and deployment of tests within Java EE archives and executing the tests inside the
- container. Tests can be launched using existing IDE, Ant and Maven test plugins, thus minimizing the burden on
- the developer to <!-- validate the behavior of managed and enterprise beans or POJOs that use enterprise
- services --> perform integration testing. And the environment in which the tests are run is pluggable, so the
- developer is not locked in to a proprietary testing container.
+ The mission of the Arquillian project is to provide a simple test harness that developers can use to produce a
+ broad range of integration tests for their Java applications (most likely enterprise applications). A test case
+ may be executed within the container, deployed alongside the code under test, or by coordinating with the
+ container, acting as a client to the deployed code.
</para>
+
+ <para>
+ Arquillian defines two styles of container, remote and embedded. A remote container resides in a separate JVM
+ from the test runner. Its lifecycle may be managed by Arquillian, or Arquillian may bind to a container that is
+ already started. An embedded container resides in the same JVM and is mostly likely managed by Arquillian.
+ Containers can be further classified by their capabilities. Examples include a fully compliant Java EE
+ application server (e.g., GlassFish, JBoss AS, Embedded GlassFish), a Servlet container (e.g., Tomcat, Jetty)
+ and a bean container (e.g., Weld SE). Arquillian ensures that the container used for testing is pluggable, so
+ the developer is not locked into a proprietary testing environment.
+ </para>
+
+ <para>
+ Arquillian seeks to minimize the burden on the developer to carry out integration testing by handling all
+ aspects of test execution, including:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>managing the lifecycle of the container (start/stop),</para>
+ </listitem>
+ <listitem>
+ <para>bundling the test class with dependent classes and resources into a deployable archive,</para>
+ </listitem>
+ <listitem>
+ <para>enhancing the test class (e.g., resolving @Inject, @EJB and @Resource injections),</para>
+ </listitem>
+ <listitem>
+ <para>deploying the archive to test (deploy/undeploy) and</para>
+ </listitem>
+ <listitem>
+ <para>capturing results and failures.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ To avoid introducing unnecessary complexity into the developer's build environment, Arquillian integrates
+ transparently with familiar testing frameworks (e.g., JUnit 4, TestNG 5), allowing tests to be launched using
+ existing IDE, Ant and Maven test plugins without any add-ons.
+ </para>
+
+ <para>
+ Arquillian makes integration testing a breeze.
+ </para>
+
</section>
<section id="overview">
@@ -35,7 +76,7 @@
<para>
Arquillian combines a unit testing framework (JUnit or TestNG), ShrinkWrap, and one or more supported target
containers (Java EE container, servlet container, Java SE CDI environment, etc) to provide a simple, flexible
- and pluggable integration testing environment for normal test cases.
+ and pluggable integration testing environment.
</para>
<mediaobject>
@@ -48,9 +89,11 @@
</mediaobject>
<para>
- At the core, Arquillian provides a <emphasis>custom test runner for JUnit and TestNG</emphasis> that allows
- test methods in a test case to be executed inside of a container environment. An Arquillian test case looks
- just like a regular JUnit or TestNG test case with two declarative enhancements, which will be covered later.
+ At the core, Arquillian provides a <emphasis>custom test runner for JUnit and TestNG</emphasis> that turns
+ control of the test execution lifecycle from the unit testing framework to Arquillian. From there, Arquillian
+ can delegate to service providers to setup the environment to execute the tests inside or against the
+ container. An Arquillian test case looks just like a regular JUnit or TestNG test case with two declarative
+ enhancements, which will be covered later.
</para>
<para>
@@ -60,7 +103,24 @@
</para>
<para>
- The test case is transferred into the container's environment through coordination with
+ At this point, it's appropriate to pause and define the three aspects of an Arquillian test case. This
+ terminology will help you better understand the explainations of how Arquillian works.
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para>container — a runtime environment for a deployment</para>
+ </listitem>
+ <listitem>
+ <para>deployment — the process of dispatching an artifact to a container to make it operational</para>
+ </listitem>
+ <listitem>
+ <para>archive — a packaged assembly of resources which become operational inside the container</para>
+ </listitem>
+ </orderedlist>
+
+ <para>
+ The test case is dispatched to the container's environment through coordination with
<emphasis>ShrinkWrap</emphasis>, which is used to declaratively define a custom Java EE archive that
encapsulates the test class and its dependent resources. Arquillian packages the ShrinkWrap-defined archive at
runtime and deploys it to the <emphasis>target container</emphasis>. It then negotiates the execution of the
Modified: arquillian/trunk/doc/reference/src/main/docbook/en-US/master.xml
===================================================================
--- arquillian/trunk/doc/reference/src/main/docbook/en-US/master.xml 2010-03-01 14:44:20 UTC (rev 4079)
+++ arquillian/trunk/doc/reference/src/main/docbook/en-US/master.xml 2010-03-04 07:12:27 UTC (rev 4080)
@@ -16,9 +16,9 @@
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="enrichment.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="execution.xml" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="debugging.xml" />
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extend.xml" />
<!--
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="scenarios.xml" />
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="extend.xml" />
-->
<!--
Modified: arquillian/trunk/doc/reference/src/main/docbook/en-US/preface.xml
===================================================================
--- arquillian/trunk/doc/reference/src/main/docbook/en-US/preface.xml 2010-03-01 14:44:20 UTC (rev 4079)
+++ arquillian/trunk/doc/reference/src/main/docbook/en-US/preface.xml 2010-03-04 07:12:27 UTC (rev 4080)
@@ -4,12 +4,12 @@
<preface>
<title>Preface: Test in the container!</title>
<para>
- Ever since the inception of Java EE, testing enterprise applications has been a big pain point. Testing business
+ Ever since the inception of Java EE, testing enterprise applications has been a major pain point. Testing business
components, in particular, can be very challenging. Often, a vanilla unit test isn't sufficient for validating
such a component's behavior. <emphasis>Why is that?</emphasis> The reason is that components in an enterprise
- application rarely perform operations which are strictly self-contained. Instead, they provide services which
- intimately tie into the greater system. They also have declarative functionality which gets applied to the
- component at runtime. You could say "no business component is an island."
+ application rarely perform operations which are strictly self-contained. Instead, they interact with or provide
+ services for the greater system. They also have declarative functionality which gets applied at runtime. You could
+ say "no business component is an island."
</para>
<para>
@@ -31,10 +31,10 @@
<para>
Arquillian, a new testing framework developed at JBoss.org, empowers the developer to write integration tests for
- business objects that are executed inside an embedded or remote container—whether it be a servlet container, a
- Java EE application server or a Java SE CDI environment. Arquillian strives to make integration testing no more
- complicated than basic unit testing. It turns out, if these tests execute quickly, they're really the only tests
- you need.
+ business objects that are executed inside of or through coordination with an embedded or remote
+ container—whether it be a Servlet container, a Java EE application server or a Java SE CDI environment.
+ Arquillian strives to make integration testing no more complicated than basic unit testing. It turns out, if these
+ tests execute quickly, they're really the only tests you need.
</para>
<para>
More information about the jboss-svn-commits
mailing list