[jboss-svn-commits] JBoss Common SVN: r4430 - arquillian/trunk/doc/reference/src/main/docbook/en-US.
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Mon May 24 08:49:52 EDT 2010
Author: aslak
Date: 2010-05-24 08:49:52 -0400 (Mon, 24 May 2010)
New Revision: 4430
Removed:
arquillian/trunk/doc/reference/src/main/docbook/en-US/configuration.xml
Modified:
arquillian/trunk/doc/reference/src/main/docbook/en-US/container_glassfish-embedded-30.xml
arquillian/trunk/doc/reference/src/main/docbook/en-US/container_jbossas-local-51.xml
arquillian/trunk/doc/reference/src/main/docbook/en-US/container_jbossas-local-60.xml
arquillian/trunk/doc/reference/src/main/docbook/en-US/containers.xml
arquillian/trunk/doc/reference/src/main/docbook/en-US/execution.xml
Log:
ARQ-121 Some language changes + layout fixes.
Deleted: arquillian/trunk/doc/reference/src/main/docbook/en-US/configuration.xml
===================================================================
--- arquillian/trunk/doc/reference/src/main/docbook/en-US/configuration.xml 2010-05-24 10:47:31 UTC (rev 4429)
+++ arquillian/trunk/doc/reference/src/main/docbook/en-US/configuration.xml 2010-05-24 12:49:52 UTC (rev 4430)
@@ -1,61 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" []>
-
-<chapter id="configuration">
- <title>Configuration</title>
-
- <para>
- You can come a long way with default values, but at some point you may need to customize some of the container
- settings to fit your environment. We're going to have a look at how this can be done with Arquillian.
- Arquillian will look for a file named <filename>arquillian.xml</filename> in the root of your classpath.
- If it exists it will be auto loaded, else default values be used. So this file is not a requirement.
- </para>
-
- <para>
- Lets imagine that we're working for the company example.com and in our environment we have two servers;
- test.example.com and hudson.example.com. test.example.com is the JBoss instance we use for our integration
- tests and hudson.example.com is our continuous integration server that we want to run our integration suite
- from. You do want continuous integration testing, right? All containers default to localhost, so we obviously
- can't have that if we want to test against our test.example.com server.
- </para>
-
- <programlisting role="XML"><![CDATA[<?xml version="1.0"?>
-
-<arquillian xmlns="http://jboss.com/arquillian"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xmlns:jboss="urn:arq:org.jboss.arquillian.jbossas.remote60">
-
- <engine>
- <deploymentExportPath>/tmp</deploymentExportPath>
- </engine>
-
- <jboss:container>
- <remoteServerAddress>test.example.com</remoteServerAddress>
- <remoteServerHttpPort>8181</remoteServerHttpPort>
- <localDeploymentBindAddress>hudson.example.com</localDeploymentBindAddress>
- <localDeploymentBindPort>7000</localDeploymentBindPort>
- </jboss:container>
-
-</arquillian>]]></programlisting>
-
- <para>
- That should do it! What we have done here is to declare a XML namespace using the defined name for the
- JBoss AS 6.0 Remote container. This is needed by Arquillian to know which ContainerConfiguraiton your trying to
- create. Next step is to create a <emphasis>container</emphasis> element in that namespace and add the options you
- want to configure inside. In this example we're saying that the server we want to test against can be found on
- address test.example.com using port 8181, and the remote server can communicate back to us on address hudson.example.com
- on port 7000. The callback is needed by some containers as a way of transferring the deployment
- to the remote server, the deployment initialization is then based on URLs.
- </para>
-
- <tip>
- For a complete overview of all the containers and their configuration options,
- see <xref linkend="container.reference"/>
- </tip>
-
- <warning>
- Some containers require a jndi.properties file on classpath with the containers standard
- JNDI properties for the initial connection.
- </warning>
-</chapter>
\ No newline at end of file
Modified: arquillian/trunk/doc/reference/src/main/docbook/en-US/container_glassfish-embedded-30.xml
===================================================================
--- arquillian/trunk/doc/reference/src/main/docbook/en-US/container_glassfish-embedded-30.xml 2010-05-24 10:47:31 UTC (rev 4429)
+++ arquillian/trunk/doc/reference/src/main/docbook/en-US/container_glassfish-embedded-30.xml 2010-05-24 12:49:52 UTC (rev 4430)
@@ -72,9 +72,9 @@
<table frame="all">
<title>Container Configuration Options</title>
<tgroup cols="4">
- <colspec colnum="1" colname="name" colwidth="4*" />
+ <colspec colnum="1" colname="name" colwidth="2*" />
<colspec colnum="2" colname="type" colwidth="1*" />
- <colspec colnum="3" colname="default" colwidth="1*" />
+ <colspec colnum="3" colname="default" colwidth="3*" />
<colspec colnum="4" colname="description" colwidth="4*" />
<thead>
<row>
Modified: arquillian/trunk/doc/reference/src/main/docbook/en-US/container_jbossas-local-51.xml
===================================================================
--- arquillian/trunk/doc/reference/src/main/docbook/en-US/container_jbossas-local-51.xml 2010-05-24 10:47:31 UTC (rev 4429)
+++ arquillian/trunk/doc/reference/src/main/docbook/en-US/container_jbossas-local-51.xml 2010-05-24 12:49:52 UTC (rev 4430)
@@ -58,9 +58,9 @@
<table frame="all">
<title>Container Configuration Options</title>
<tgroup cols="4">
- <colspec colnum="1" colname="name" colwidth="4*" />
+ <colspec colnum="1" colname="name" colwidth="2*" />
<colspec colnum="2" colname="type" colwidth="1*" />
- <colspec colnum="3" colname="default" colwidth="1*" />
+ <colspec colnum="3" colname="default" colwidth="3*" />
<colspec colnum="4" colname="description" colwidth="4*" />
<thead>
<row>
Modified: arquillian/trunk/doc/reference/src/main/docbook/en-US/container_jbossas-local-60.xml
===================================================================
--- arquillian/trunk/doc/reference/src/main/docbook/en-US/container_jbossas-local-60.xml 2010-05-24 10:47:31 UTC (rev 4429)
+++ arquillian/trunk/doc/reference/src/main/docbook/en-US/container_jbossas-local-60.xml 2010-05-24 12:49:52 UTC (rev 4430)
@@ -72,9 +72,9 @@
<table frame="all">
<title>Container Configuration Options</title>
<tgroup cols="4">
- <colspec colnum="1" colname="name" colwidth="4*" />
+ <colspec colnum="1" colname="name" colwidth="2*" />
<colspec colnum="2" colname="type" colwidth="1*" />
- <colspec colnum="3" colname="default" colwidth="1*" />
+ <colspec colnum="3" colname="default" colwidth="3*" />
<colspec colnum="4" colname="description" colwidth="4*" />
<thead>
<row>
Modified: arquillian/trunk/doc/reference/src/main/docbook/en-US/containers.xml
===================================================================
--- arquillian/trunk/doc/reference/src/main/docbook/en-US/containers.xml 2010-05-24 10:47:31 UTC (rev 4429)
+++ arquillian/trunk/doc/reference/src/main/docbook/en-US/containers.xml 2010-05-24 12:49:52 UTC (rev 4430)
@@ -179,11 +179,11 @@
</para>
<para>
- Lets imagine that we're working for the company example.com and in our environment we have two servers;
- test.example.com and hudson.example.com. test.example.com is the JBoss instance we use for our integration
- tests and hudson.example.com is our continuous integration server that we want to run our integration suite
- from. You do want continuous integration testing, right? All containers default to localhost, so we obviously
- can't have that if we want to test against our remote test server.
+ Lets imagine that we're working for the company <literal>example.com</literal> and in our environment we have two servers;
+ <literal>test.example.com</literal> and <literal>hudson.example.com</literal>. <literal>test.example.com</literal>
+ is the JBoss instance we use for our integration tests and <literal>hudson.example.com</literal> is our continuous integration server
+ that we want to run our integration suite from. By default, Arquillian will use localhost, so we need to tell it to use
+ <literal>test.example.com</literal> to run the tests.
</para>
<programlisting role="XML"><![CDATA[<?xml version="1.0"?>
@@ -192,27 +192,29 @@
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jboss="urn:arq:org.jboss.arquillian.jbossas.remote60">
- <engine>
- <deploymentExportPath>/tmp</deploymentExportPath>
- </engine>
+ <engine>
+ <deploymentExportPath>/tmp</deploymentExportPath>
+ </engine>
- <jboss:container>
- <jboss:remoteServerAddress>test.example.com</jboss:remoteServerAddress>
- <jboss:remoteServerHttpPort>8181</jboss:remoteServerHttpPort>
- <jboss:localDeploymentBindAddress>hudson.example.com</jboss:localDeploymentBindAddress>
- <jboss:localDeploymentBindPort>7000</jboss:localDeploymentBindPort>
- </jboss:container>
+ <jboss:container>
+ <jboss:remoteServerAddress>test.example.com</jboss:remoteServerAddress>
+ <jboss:remoteServerHttpPort>8181</jboss:remoteServerHttpPort>
+ <jboss:localDeploymentBindAddress>
+ hudson.example.com
+ </jboss:localDeploymentBindAddress>
+ <jboss:localDeploymentBindPort>7000</jboss:localDeploymentBindPort>
+ </jboss:container>
</arquillian>]]></programlisting>
<para>
- That should do it! What we have done here is to declare a XML namespace using the defined name for the
- JBoss AS 6.0 Remote container. This is needed by Arquillian to know which ContainerConfiguraiton your trying to
- create. Next step is to create a <emphasis>container</emphasis> element in that namespace and add the options you
- want to configure inside. In this example we're saying that the server we want to test against can be found on
- address test.example.com using port 8181, and the remote server can communicate back to us on address hudson.example.com
- on port 7000. The callback is needed by some containers as a way of transferring the deployment
- to the remote server, the deployment initialization is then based on URLs.
+ That should do it! "Each type of container has it's own XML namespace for configuration - here we use the JBoss AS 6.0
+ Remote container. Each container has different configuration options. Next step is to create a
+ <literal>container</literal> element in that namespace and add the options you want to configure inside.
+ In this example we're saying that the server we want to test against can be found on
+ address <literal>test.example.com</literal> using port 8181, and the remote server can communicate back to us
+ on address <literal>hudson.example.com</literal> on port 7000. Some containers expect to be given a URL from which
+ they can retrieve the application to be deployed. For these containers, Arquillian will start a local HTTP server.
</para>
<tip>
Modified: arquillian/trunk/doc/reference/src/main/docbook/en-US/execution.xml
===================================================================
--- arquillian/trunk/doc/reference/src/main/docbook/en-US/execution.xml 2010-05-24 10:47:31 UTC (rev 4429)
+++ arquillian/trunk/doc/reference/src/main/docbook/en-US/execution.xml 2010-05-24 12:49:52 UTC (rev 4430)
@@ -209,17 +209,16 @@
<title>Test run modes</title>
<para>
- Your application normally has two sides to it, it's the internal view and the external view. So far we've focused
- on the internal view and showed you how to test your application from the inside. This is great for things
- like asserting on HTTP session state or calling local EJBs, but it doesn't tell you much about how the world
- perceives you. So your external view is how you're application is viewed by others. This can be by WebServices,
- remote EJBs or plain Servlets. While you can reach remote EJBs from the inside of the container, you're not using
- it in the same way as you would if you were a client. Does your object serialization work? Does your network work?
+ So far, we've focused on testing your application internals, but we also want to test how others (people, or other programs)
+ interact with the application. Typically, you want to make sure that every use case and execution path is fully tested.
+ Third parties can interact with your application in a number of ways, for example web services, remote EJBs or via http.
+ You need to check that you object serialization or networking work for instance.
</para>
<para>
This is why Arquillian comes with two run modes, <literal>IN_CONTAINER</literal> and <literal>AS_CLIENT</literal>.
- <literal>IN_CONTAINER</literal> is for your internal view and <literal>AS_CLIENT</literal> is for your external view.
- Lets dive a bit deeper into the differences between the run modes and see how they effect your test execution and packaging.
+ <literal>IN_CONTAINER</literal> is to test your application internals and <literal>AS_CLIENT</literal> is to test
+ how your application is used by clients. Lets dive a bit deeper into the differences between the run modes and
+ see how they effect your test execution and packaging.
</para>
<section>
@@ -228,16 +227,13 @@
@Run(IN_CONTAINER)
public class MyTestCase</programlisting>
<para>
- Lets start with the advanced one first. As we just talked about, to be able to run in-container, we need
- to repackage your defined <literal>@Deployment</literal> to add some of the Arquillian internals. This gives
- us the ability to communicate with the test, enrich the test and run the test remotely.
- When in this run mode your test is no longer living in your local JVM, but in the remote container.
- This is the default mode.
+ As we mentioned above, we need to repackage your <literal>@Deployment</literal>, adding some Arquillian support
+ classes, to run in-container. This gives us the ability to communicate with the test, enrich the test and run the
+ test remotely. In this mode, the test executes in the remote container; Arqullian uses this mode by default.
</para>
<para>
- Here is a overview of the inputted <literal>@Deployment</literal> and the expected
- output of the packaging process.
+ Here is an overview of the expected output of the packaging process when you provide a <literal>@Deployment</literal>.
</para>
<table frame="all">
<title>EEDeploymentPackager rules</title>
@@ -249,7 +245,7 @@
<thead>
<row>
<entry>@Deployment</entry>
- <entry>Serlvet EE v.</entry>
+ <entry>Servlet EE v.</entry>
<entry>Output</entry>
<entry>Action</entry>
</row>
@@ -259,42 +255,59 @@
<entry>JavaArchive</entry>
<entry>EE 5</entry>
<entry>EnterpriseArchive</entry>
- <entry>Create a new EnterpriseArchive, add Deployment and ServletProtocl as module, the other Auxiliary Archives as libraries.</entry>
+ <entry>Create a new <literal>EnterpriseArchive</literal>, add <literal>@Deployment</literal> and <literal>ServletProtocol</literal> as module, the other <literal>Auxiliary Archives</literal> as libraries.</entry>
</row>
<row>
<entry>WebArchive</entry>
<entry>EE 5</entry>
<entry>Exception</entry>
- <entry>Can not merge two WebArchives and both packed in a EnterpriseArchive will result in isolation issues.</entry>
+ <entry>
+ Can not merge two <literal>WebArchives</literal> and both packaged in a <literal>EnterpriseArchive</literal> will result in isolation issues.
+ <footnote>
+ <para>In the current release Arquillian does not try to merge descriptor files, like web.xml, nor can you
+ avoid it trying to package the <literal>@Deployment</literal>. This will change in future releases.</para>
+ </footnote>
+ </entry>
</row>
<row>
<entry>EnterpriseArchive</entry>
<entry>EE 5</entry>
<entry>EnterpriseArchive</entry>
- <entry>Same as JavaArchive, but using the Deployment defined EnterpriseArchive instead of creating a new.</entry>
+ <entry>Same as <literal>JavaArchive</literal>, but using the <literal>@Deployment</literal> defined <literal>EnterpriseArchive</literal> instead of creating a new.</entry>
</row>
<row>
<entry>JavaArchive</entry>
<entry>EE 6</entry>
<entry>WebArchive</entry>
- <entry>Creates a new WebArchive, adds Deployment and Auxiliary Archives as libraries.</entry>
+ <entry>Creates a new <literal>WebArchive</literal>, adds <literal>@Deployment</literal> and <literal>Auxiliary Archives</literal> as libraries.</entry>
</row>
<row>
<entry>WebArchive</entry>
<entry>EE 6</entry>
<entry>WebArchive</entry>
- <entry>Adds Deployment and Auxiliary Archives as libraries.</entry>
+ <entry>Adds <literal>@Deployment</literal> and <literal>Auxiliary Archives</literal> as libraries.</entry>
</row>
<row>
<entry>EnterpriseArchive</entry>
<entry>EE 6</entry>
<entry>EnterpriseArchive</entry>
- <entry>Finds the protocol JavaArchive based on name(arquillian-protocol.jar), wraps this jar in a WebArchive and adds it as a module. The other Auxiliary Archives are added as libraries.</entry>
+ <entry>Finds the protocol <literal>JavaArchive</literal> based on name(<filename>arquillian-protocol.jar</filename>), wraps this jar in a <literal>WebArchive</literal> and adds it as a module. The other <literal>Auxiliary Archives</literal> are added as libraries.</entry>
</row>
</tbody>
</tgroup>
</table>
-
+ <note>
+ <para>
+ In Alpha-2 Arquillian only has one protocol implementation for communicating with remote servers, the servlet protocol.
+ So the reason for the big difference in packaging between EE 5 and EE 6 containers is mainly due to the support of
+ Web Fragments in the EE 6 specification. Web Fragments lets Arquillian add it self to the <literal>@Deployment</literal>
+ without drastically changing it, but it also means it has to be a <literal>WebArchive</literal> in the deployment.
+ </para>
+ <para>
+ In the next release you will be able to control the packaging your self and we will also look into
+ other protocol implementations like jmx and remote ejb.
+ </para>
+ </note>
</section>
<section>
@@ -309,13 +322,37 @@
and you're free to test the container from the outside, as your clients see it. The only thing Arquillian
does is to control the lifecycle of your <literal>@Deployment</literal>.
</para>
+
+ <para>Here is an example calling a Servlet using the <literal>AS_CLIENT</literal> mode.</para>
+ <programlisting role="JAVA">@RunWith(Arquillian.class)
+ at Run(AS_CLIENT)
+public class LocalRunServletTestCase
+{
+ @Deployment
+ public static WebArchive createDeployment()
+ {
+ return ShrinkWrap.create("test.war", WebArchive.class)
+ .addClass(TestServlet.class);
+ }
+
+ @Test
+ public void shouldBeAbleToCallServlet() throws Exception
+ {
+ String body = readAllAndClose(new URL("http://localhost:8080/test/Test").openStream());
+
+ Assert.assertEquals(
+ "Verify that the servlet was deployed and returns the expected result",
+ "hello",
+ body);
+ }
+}</programlisting>
</section>
-
+
<tip>
<para>
The effect of the different run modes depend on the <literal>DeployableContainer</literal> used.
Both modes might seem to behave the same in some Embedded containers, but you should avoid
- mixing your internal and external view tests. One thing is that they should test different
+ mixing your internal and external tests. One thing is that they should test different
aspects of your application and different usecases, another is that you will miss the
benefits of switching <literal>DeployableContainers</literal> and run the same tests suite against
a remote server if you do.
More information about the jboss-svn-commits
mailing list