FYI: working on user guide

[dan.j.allen]

For those of you starting to experiment with Arquillian, I have good news for you if you've found yourself getting stuck. I'm putting my cabin fever to good use and working on a draft of the user guide. I'm hoping to have something to ready by the end of the weekend. It will include a getting started section, which will be your ticket to getting your first green bar w/ Arquillian. Stay tuned!

...and thanks for your patience. As early adopters, you play a key role in the future success of this project!

[dan.j.allen]

Btw, here is a link to the Arquillian User Guide Outline I put together in preparation for writing the reference guide for Arquillian.

[alrubinger]

Huge.

S,

ALR

[dan.j.allen]

I'm proud to say that the first rough draft of the Arquillian user guide is complete. I was very eager to get this done, even though it was Super Bowl weekend, because I really want to ensure success for our early adopters and keep the development of this framework rolling.

At this point, I consider every part of the user guide open for review. Please let me know what you think. If there is something that doesn't make sense, let's get it fixed. If I'm not explaining something right, please correct me. If you don't agree with how I am interpreting the purpose of the framework, let's talk about it. I really want this user guide to hit home and give the developer the confidence to test their applications with ease using Arquillian.

Until an alpha of Arquillian is released, you'll have to build the user guide from source. Checkout the reference guide from SVN and build it by executing "mvn package". The HTML and PDF versions of the reference guide will end up under the target/docbook/publish directory.

[aslak]

Excellent work Dan!
A Couple of comments so far:
* The examples are using a old v. of ShrinkWrap (Path vs ArchivePath). I will commit a patch to both examples and Arquillian. ([ARQ-61|https://jira.jboss.org/jira/browse/ARQ-61])
* We're directly depending on shrinkwrap-impl by using ByteArrayAsset. Since we don't have any CDI beans.xml support in ShrinkWrap yet, I think we should change to add them as a ClassLoader Resource instead. ([ARQ-49|https://jira.jboss.org/jira/browse/ARQ-49])
* In the JPA example, we show a persistence.xml that hardcodes the classes it should use. Since we have full control of the deployment maybe we should consider letting the persistence provider do class scanning instead. This will let the user reuse the persistence.xml across multiple tests.
* Setting up the example for Maven deps, we don't need to explicitly depend on JUnit or TestNG, they are pulled in from arquillian-junit/testng.
* We should show how to set up/run Arquillian inside the IDE. When using Maven profile we need to use eclipse:eclipse with profile defined.
* The @Deployment signature is really: public static Archive<?> xx()
* Mentioning ContainerDeployers(test-harness), in Arquillian it is DeployableContainer
* Tiny bug in the TestEnrichement ejb lookup .. local set twice, not local and remote
I think i'll add a SPI section, describing all the SPIs and how to are used.

[jnorris10]

Dan, nice job on this!  It's looking really good.

[dan.j.allen]

Thanks for the fixes Aslak!

I was getting tired and I know I left out some detail in the getting start guide, namely the Eclipse setup. I'll fill that in the next day or two. I strongly advocate the use of m2eclipse and will make that the recommended approach.

I have a chapter set aside for the SPI called extend.xml. It's currently commented out of the master since it is blank. I'll leave the writing to you and then it can be uncommented in the master file. Writing this section will complement the current review of the SPI that ALR kicked off.

[aslak]

You define 3 Container types:

• A standalone (remote) container
• An embedded container
• A Java SE bean container

I tend to define the types as:

• Remote Container
  • Not in the same JVM
  • No life cycle control (only deploy/undeploy)
  • Same or remote machine
  • JBoss AS, GlassFish...
• Local Container
  • Not in the same JVM
  • Full life cycle control (start/stop deploy/undeploy)
  • Same machine
  • JBoss AS, GlassFish...
• Embedded Container
  • Same JVM
  • Full lifecycle control (start/stop deploy/undeploy)
  • Same machine
  • JBoss AS Embedded, GlassFish Embedded, Weld-SE, OpenEJB...

wdyt?

[alrubinger]

This could just be my EJB background shining through, but to me "local" and "remote" are relative to a JVM/process, not a physical machine.  Might be confusing to others when they want to know why a @EJB injection of a local business interface doesn't work in a "local" test which has different JVM but same physical machine.

I like "Embedded"; there's little doubt about where that is.

Ha, for different machines we should abuse the word "cloud".

But seriously, any better terms to denote physical locality?

S,

ALR

[aslak]

ALRubinger wrote:

Might be confusing to others when they want to know why a @EJB injection of a local business interface doesn't work in a "local" test which has different JVM but same physical machine.

But it does work, because the test is running in the Container.

If it's local/remote or embedded doesn't matter.

In local run mode on the hand, only Remote is supported.

[alrubinger]

aslak wrote:

ALRubinger wrote:

Might be confusing to others when they want to know why a @EJB injection of a local business interface doesn't work in a "local" test which has different JVM but same physical machine.

But it does work, because the test is running in the Container.

If it's local/remote or embedded doesn't matter.

In local run mode on the hand, only Remote is supported.

Hehe, again, I don't think it should *always* be running inside the container.  It's really useful to test from the outside too.

S,

ALR

[dan.j.allen]

Aslak, I'm glad you brought this up, because it's one of the things I had down in my notes to clarify.

I think we are really dealing with two types of classifications. The first classification is whether the container is running in the same JVM, which is how you have defined them. The second is the type of environment, from a fully-compatible Java EE container to a hybrid of bootstrapped frameworks (a bean container), with servlet containers falling in between.

To consider Embedded GlassFish and Weld SE in the same catagory, with no other type of classification, is too vague.

Let me try a new arrangement:

• Standalone container (perhaps the term Remote still applies)
  
  • Different JVM; remote communication (e.g., HTTP)
  • Deploy/Undeploy
  • Java EE, Servlet
• Managed container (perhaps the term Local still applies)
  
  • Different JVM; remote communication (e.g., HTTP)
  • Start/Stop
  • Deploy/Undeploy
  • Java EE, Servlet
• Embedded container
  • Same JVM (remote communication?)
  • Start/Stop
  • Deploy/Undeploy
  • Java EE, Servlet
• Java SE bean environment
  • Same JVM
  • Start/Stop (i.e., bootstrap)
    
  • Specialized deploy/undeploy
  • Weld SE, Spring, Guice

I believe that the first three are true integration tests, whereas the last is more like context testing (for lack of a better term).

[dan.j.allen]

This topic ended up being a core discussion in the first half of the Arquillian Meeting Log | 20100215. I'm currently working on revising the mission statement based on the conclusions from that meeting. I should have a draft by tomorrow's meeting.

[dan.j.allen]

I've started a new thread for the Mission statement draft. Chime in there.