Red Hat

In Relation To Arquillian

In Relation To Arquillian

The goal of this blog post is to walk you through an Java EE 6 application from a simple, static web page until we have a full blown stack that consist of the stuff in the list below. I'm calling this stack Summer because after a long, hard winter Spring may be nice but boy, wait until Summer kicks in ;-)

  • CDI (Weld)
  • JSF 2 (facelets, ICEfaces 2)
  • JPA 2 (Hibernate, Envers)
  • EJB 3.1 (no-local-view, asynchronous, singletons, scheduling)
  • Bean Validation (Hibernate Validator)
  • JMS (MDB)
  • JAX-RS (RESTEasy)
  • JAX-WS
  • Arqullian (incontainer-AS6)

We will pack all this in a single WAR. Just because we can (spoiler: in part IV). Noticed that apart from the component and testing frameworks, they are all standards? That's a lot of stuff. Fortunately, the appserver already provides most of the stuff so you're app will still be reasonably small.

As for the environment I'm using

  • Eclipse (Galileo SR2)
  • JBoss 6.0 M3
  • Maven 3 (beta1)
  • Sun JDK 6
  • m2eclipse 0.10

This will not be your typical blog post where everything goes well - we will hit bugs. There will be curses, blood and guts and drama and we will do workarounds and rewrites as we move along. Pretty much the same as your average day as a software developer probably looks like. I'm also no expert in the technologies I use here so there are probably things that could be done better. Consider this more of a write-down of my experiences in EE6-land that will probably mirror what others are going through. I will also not point you to links or additional information, I assume that if I say RESTEasy, you can google up more information if you are interested.

And I almost forgot: don't panic.

In the beginning: Project setup

So, lets start things off - go and download the stuff mentioned in the environment if you don't already have it. I'm not going to insult your intelligense by walking you through that (remind me to insult it later). Besides, it's pretty straightforward.

Let's make a new Maven project (File -> New -> Project... -> Maven -> Maven Project. We skip the archetype selection and just make a simple project with group id com.acme, artifact id Greetings of version 1.0.0-SNAPSHOT packed as a WAR. Now finish the wizard and now you should have a nice, perfect project. It will never be this perfect again as our next step is adding code to it.

Maven tip-of-the-day for Windows users. Google up on how you change the path to your local repo as it might be somewhere under Documents And Settings which has two effects: classpath gets huge and there could be problems due to the spaces. Change it to something like c:\java\m2repo

The first thing we notice that m2eclipse has J2SE-1.4 as default. How 2002. Besides, that will make using annotations impossible so lets change that. Edit the pom.xml and throw in

<build>
	<plugins>
		<plugin>
			<groupId>org.apache.maven.plugins</groupId>
			<artifactId>maven-compiler-plugin</artifactId>
			<version>2.3.1</version>
			<configuration>
				<source>1.6</source>
				<target>1.6</target>
			</configuration>
		</plugin>
	</plugins>
</build>

Save and right-click the project root and go Maven -> Update Project Configuration. Aah, that's better

JSF

Let's wake up JSF. We create a folder WEB-INF in src/main/webapp and throw in a web.xml because no web app is complete without it (enforced by the maven war plugin). OK, actually this can be configured in the plugin but let's keep the web.xml since we'll need it later.

<?xml version="1.0" encoding="ISO-8859-1"?>
<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"/>

and an empty faces-config.xml next to it

<faces-config xmlns="http://java.sun.com/xml/ns/javaee"
              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-facesconfig_2_0.xsd"
              version="2.0"/>

and in webapp we add a greeting.xhtml like

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
	xmlns:h="http://java.sun.com/jsf/html"
	xmlns:ui="http://java.sun.com/jsf/facelets">
	<h:head>
		<title>
			Greetings
		</title>
	</h:head>

	<h:body>
		<h:outputText value="Hello world"/>
	</h:body>
</html>

Will it blend? I mean, will it deploy? Do a mvn clean package and you should have a Greetings-1.0.0-SNAPSHOT in your projects target directory. Throw it into the AS server/default/deploy directory and start up the server and go to

http://localhost:8080/Greetings-1.0.0-SNAPSHOT/faces/greetings.xhtml

The url is not pretty, but the server port, web context root, welcome files and JSF mappings can all be tuned later, let's focus on technologies and dependencies for now. But wait - at which point did we define the JSF servlet and mappings in web.xml? We didn't. It's automagic for JSF-enabled applications.

EJB and CDI

Next step is bringing in some backing beans, let's outsource our greeting. We make a stateless EJB and use it in CDI

package com.acme.greetings;

@Stateful
@Model
public class GreetingBean 
{
	public String getGreeting()
	{
		return "Hello world";
	}
}

The @Stateful defines a stateful session EJB (3.1 since it's a POJO) and the @Model is a CDI stereotype that is @RequestScoped and @Named (which means the lifecycle is bound to a single HTTP request and it has a name that can be referenced in EL and defaults to greetingBean in this case). But we have a problem - the annotations don't resolve to anything. So we need to pick them up from somewhere(tm). Fortunately we can have all the APIs picked up for us by adding the following to our pom.xml

<dependencies>
	<dependency>
		<groupId>org.jboss.spec</groupId>
		<artifactId>jboss-javaee-6.0</artifactId>
		<version>1.0.0.Beta4</version>
		<type>pom</type>
		<scope>provided</scope>
	</dependency>
</dependencies>

Sun Java API artifacts are a bit amusing since getting hold of them can be a bit tricky. First they publish them in the JSR:s and then they treat them like they're top secret. Fortunately Glassfish and now JBoss have started making them available in their repositories (although under their own artifact names, but still)...

We also need to make sure we have set up the JBoss repositories for this according to http://community.jboss.org/wiki/MavenGettingStarted-Users. Have a look at what happened in the projects Maven Dependencies. Good. Now close it and back away. It's getting hairy in there so better trust Maven to keep track of the deps from now on.

The imports should now be available in our bean so we import

import javax.ejb.Stateful;
import javax.enterprise.inject.Model;

and EL-hook the bean up with

<h:body>
	<h:outputText value="#{greetingBean.greeting}"/>
</h:body>

in greetings.xhtml.

Just as no web application is complete without web.xml, no CDI application is complete without beans.xml. Let's add it to WEB-INF

<?xml version="1.0" encoding="ISO-8859-1"?>
<beans xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="
      http://java.sun.com/xml/ns/javaee 
      http://java.sun.com/xml/ns/javaee/beans_1_0.xsd" />

Package and redeploy. We get a warning about encoding when compiling so lets add this to our pom.xml

<properties>
	<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

Back to http://localhost:8080/Greetings-1.0.0-SNAPSHOT/faces/greetings.xhtml SUCCESS! No. Wait. Huge stack trace hits you for 300 points of damage. Let's back up on our EJB, there are still some issues with 3.1 style EJBs in WAR-only-packaging on AS 6 M3. Remove the @Stateful annotation and it becomes a normal CDI managed POJO. Repackage. Redploy. Recoyce.

Testing

Testing is hip nowadays so let's bring in Arquillian. Arquillian is the latest and greatest in EE testing (embedded or incontainer). Start using it now. In a year or so when everone else catch up you can go I've been using it since Alpha. Add the following property to pom.xml:

<arquillian.version>1.0.0.Alpha2</arquillian.version>

and these deps

<dependency>
	<groupId>org.jboss.arquillian</groupId>
	<artifactId>arquillian-junit</artifactId>
	<version>${arquillian.version}</version>
	<scope>test</scope>
</dependency>
<dependency>
	<groupId>junit</groupId>
	<artifactId>junit</artifactId>
	<version>4.8.1</version>
	<scope>test</scope>
</dependency>

and this profile

<profiles>	
	<profile>
		<id>jbossas-local-60</id>
		<dependencies>
			<dependency>
				<groupId>org.jboss.arquillian.container</groupId>
				<artifactId>arquillian-jbossas-local-60</artifactId>
				<version>1.0.0.Alpha2</version>
			</dependency>
			<dependency>
				<groupId>org.jboss.jbossas</groupId>
				<artifactId>jboss-server-manager</artifactId>
				<version>1.0.3.GA</version>
			</dependency>
			<dependency>
				<groupId>org.jboss.jbossas</groupId>
				<artifactId>jboss-as-client</artifactId>
				<version>6.0.0.20100429-M3</version>
				<type>pom</type>
			</dependency>
		</dependencies>
	</profile>
</profiles>

Maven will probably now download the entire internet for you.

Let's write our first test and place it in the test source folder:

package com.acme.greetings.test;

import javax.inject.Inject;

import org.jboss.arquillian.api.Deployment;
import org.jboss.arquillian.junit.Arquillian;
import org.jboss.shrinkwrap.api.ArchivePaths;
import org.jboss.shrinkwrap.api.ShrinkWrap;
import org.jboss.shrinkwrap.api.spec.JavaArchive;
import org.jboss.shrinkwrap.impl.base.asset.ByteArrayAsset;
import org.junit.Assert;
import org.junit.Test;
import org.junit.runner.RunWith;

import com.acme.greetings.GreetingBean;

@RunWith(Arquillian.class)
public class GreetingTest 
{
	@Inject
	GreetingBean greetingBean;

	@Deployment
	public static JavaArchive createTestArchive() 
	{
		return ShrinkWrap.create("test.jar", JavaArchive.class).addClass(
				GreetingBean.class).addManifestResource(
				new ByteArrayAsset("<beans/>".getBytes()),
				ArchivePaths.create("beans.xml"));
	}

	@Test
	public void testInjection() 
	{
		Assert.assertEquals("Hello World", greetingBean.getGreeting());
	}

}

and then we try it out with mvn test -Pjbossas-local-60. If we have the AS running we can save some time, otherwise the manager will start it automagically. Setting the JBOSS_HOME env helps. What happens here is we use Shrinkwrap to create a deployment which consist of our GreetingBean and an empty beans.xml file (for CDI) and the bean is then injected for use in our tests.

This concludes Part I. In part II we will set up ICEfaces and expand our application and in part III we'll set up JPA. Part IV is for MDB and EJB and part V for adding JAX-RS and JAX-WS for importing and exporting stuff.

Seam 3 slides, Arquillian slides and Seam whitepaper

Posted by Pete Muir    |       |    Tagged as Arquillian Seam

I had the opportunity to present Seam and Arquillian to an enthusiastic audience in São Paulo on Saturday - I also saw a really nice presentation from Mauricio Salatino and Alexandre Porcelli explaining very clearly why you should use Drools - hopefully they will post a screencast If you were at the event, and wanted a copy of the slides (or if you are just interested), here they are:

I also just received news that the Red Hat have published a whitepaper on Seam - it's been written by Jacob Orshalick, who co-authored the Seam Framework book and is a seam contributor. Good work Jacob!

Help us select an Arquillian logo

Posted by Dan Allen    |       |    Tagged as Arquillian

Cool software projects have cool logos. We recently announced an alpha release of Arquillian, a project that's going to revolutionize Java EE integration testing. Now we need to make Arquillian cool :)

We are in the process of establishing Arquillian's visual identity, its logo. We've already been through a couple rounds of grayscale design comps with Cheyenne from the JBoss Community design team, who is designing the Arquillian logo. Throughout the process, we've asked community members to provide feedback on the comps to help steer the design process. You can follow some of the progress in this thread or the #arquillian Twitter hashtag. We're casting a wider net this time by asking readers of this blog to chime in.

The themes we are pursuing are:

  • aliens
  • remote control
  • in container

Here are the round 3 logo candidates:

r3v1
r3v2
r3v3
r3v4
r3v5
r3v6

Follow the link to the poll below to let us know which ones you like best and why.

Arquillian logo poll (Round 3)

Once we collect enough feedback, we'll send it over to Cheyenne and let you know which ones made the cut. Thanks for participating!

Testing Java EE the JBoss way

Posted by Pete Muir    |       |    Tagged as Arquillian Java EE Seam Weld

Recently, we've been working hard on a solution to improve the testability of Java EE, and particularly JBoss AS. I'm pleased to say that a critical piece of puzzle, Arqullian, is now available. Congratulations to Aslak and the Arquillian team for releasing the first alpha of Arquillian! You can read more about Arquillian's mission, and our plans for Java EE testing below; alternatively, there are some quick links at the bottom if you want to dive right in.

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. 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. Arquillian seeks to minimize the burden on the developer to carry out integration testing by handling all aspects of test execution, including:
  • managing the lifecycle of the container (start/stop),
  • bundling the test class with dependent classes and resources into a deployable archive,
  • enhancing the test class (e.g., resolving @Inject, @EJB and @Resource injections),
  • deploying the archive to test (deploy/undeploy) and
  • capturing results and failures.
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.

The Arquillian Mission Statement

The first alpha release of Arquillian gives us support for JBoss AS (remote deployments), GlassFish (embedded deployments), Weld SE (embedded deployments) and OpenEJB (embedded deployments). You can also inject beans and component (using @Resource or @Inject) into test cases.

We'll be adding supported containers in future releases - if you want to see your favorite container on the list, join our community and we can show you how to add support for it. We also plan to add more convention over configuration, meaning you'll only need to specify a single deployment and reuse it in all your test cases. Aslak has written more about future ideas in a follow-up blog entry. He also provides some examples of how to use Arquillian.

We're strong believers in writing tests, and writing tests which actually test your business logic in the environment it will finally run in, rather than introducing mocked out objects (which may behave differently). While unit testing is important to ensure the correctness of your logic, it does not ensure the correctness of two objects which interact with each other.

With the help of the ShrinkWrap project, Arquillian gives you the ability to create micro deployments around your tests. Micro-deployments are contained sub-sections of your application logic. This gives you the ability to do lower level integration testing on a lower level then normal integration. It is up to you at what level you want to test!

We also know you need a convenient way to run your test quickly, and that is why we are getting JBoss Embedded AS in shape. Embedded AS offers the potential to bootstrap JBoss AS inside the same JVM when you run your test, making it super easy to debug the test. Unfortunately, Embedded AS support didn't make this release (we made a decision to release what we have now, rather than delay), but we will push this out to you as soon as it's ready.

Testing your components and services gets you a long way, but you'll nearly always want to test your presentation tier as well. And that's where frameworks like JSFUnit and Selenium come in - they allow you to exercise the work flows your user will use. Support for both these frameworks is planned, as well as for Mock JSF Objects.

If you like what you've heard so far, but are worried that Arquillian requires build script wizardry to use, let us surprise you again! Being able to run any of these tests from within the IDE is a key goal of Arquillian -- and the key to a rapid development cycle. Arquillian requires no build wizardry! So check out the documentation and give it a try today!

[ JIRA ] | [ SPI Javadoc, API Javadoc ] | [ Reference Guide ] | [ Release Notes ]

Arquillian 1.0.0 Alpha 1 Released!

Posted by Aslak Knutsen    |       |    Tagged as Arquillian Seam

I'm happy to announce the first alpha release of Arquillian, an open source (ASL v2) framework for running tests in the container. If you want to read more about Arquillian's mission, and how it fits into our vision for testing at JBoss, read Pete's blog.

It's one thing to unit test your code outside of the container, but what happens when you run it inside? Does it still behave the same? How about testing against container managed resources? This is where Arquillian comes into its own.

With Arquillian it's just as easy to write integration tests as unit tests. In fact, to minimize the burden on you, Arquillian integrates with familiar testing frameworks, allowing reuse of tools such as the JUnit/TestNG support in your favorite IDE, Maven Surefire, Ant - in fact any tool which supports TestNG or JUnit!

To show you just how simple this is, here's an example test case setup using JUnit: (we'll get to the actual test next)

@RunWith(org.jboss.arquillian.junit.Arquillian.class)
public class TemperatureConverterTestCase {

   @Deployment
   public static JavaArchive createTestArchive() {
      return Archives.create("test.jar", JavaArchive.class)
         .addClasses(TemperatureConverter.class, TemperatureConverterBean.class);
   }

}

By using JUnit's @RunWith annotation, you tell JUnit to use Arquillian as the test controller. Arquillian will then look for a static method marked with the @Deployment annotation, which creates your micro deployment. In the example above we simply deploy a session bean interface and implementation.

Arquillian hooks into your testing frameworks lifecycle and reacts to events. On the before suite and after suite events the container is started/stopped, while on the before class and after class events your micro deployment is deployed to/undeployed from the container.

The test case is started in the local JVM, and then Arquillian overrides the normal test execution and migrates the test so that it's executed inside the container. By the time the test framework calls your @Test annotated method, the test is running inside the container, giving us the possibility to work with container managed resources. Here's the complete test class with JUnit @Test methods.

@RunWith(org.jboss.arquillian.junit.Arquillian.class)
public class TemperatureConverterTestCase {

   @Deployment
   public static JavaArchive createTestArchive() {
      return Archives.create("test.jar", JavaArchive.class)
         .addClasses(TemperatureConverter.class, TemperatureConverterBean.class);
   }

   @EJB
   private TemperatureConverter converter;

   @Test
   public void shouldConvertToCelsius() {
      Assert.assertEquals(converter.convertToCelsius(32d), 0d);
      Assert.assertEquals(converter.convertToCelsius(212d), 100d);
   }

   @Test
   public void shouldConvertToFarenheit() {
      Assert.assertEquals(converter.convertToFarenheit(0d), 32d);
      Assert.assertEquals(converter.convertToFarenheit(100d), 212d);
   }
}

Note how we can use @EJB to inject the session bean from our deployment into the test case for use in our test method - neat!

The Arquillian TestEnricher SPI supports all the injection annotations from Java EE 6 - @EJB, @Resource and @Inject.

This example test case could run in GlassFish, JBoss AS or OpenEJB as there are no container specific code/configuration at all. The choice is yours. You could even test on multiple platforms!

I want to learn more, where should I go from here?

You can follow up with some in depth usage scenarios and tests described in these articles:

We also have reference documentation which walks you through the examples from Arquillian, and shows you how to create your own Arquillian test suite. You might also find the Javadoc useful, especially if you plan on adding support for another container. You can also check out the forums and more articles can be found on our community site. If your interested in chatting to us, please drop by #jbosstesting on irc.freenode.net

So, what's next?

Some of the things you can expect from Arquillian are:

  • Local run mode -- Sometimes, you don't want to run the test case inside the container itself. A local run mode will be added; a mode where your test controls the deployment but is not deployed as a part of it. This will give you the chance to run a test against, for example, JSF pages or RMI (testing for those nasty Non-Serializable / SessionClosed exceptions).
  • Multiple deployments controlled by same test -- Sometimes your micro deployment is not enough to test on its own and you want to package other components as part of the same deployment. For example, you need to test the interaction between two Web applications.
  • Support for method argument injection -- In the first alpha we only support field injection. In alpha 2 we will be extending the TestEnricher SPI to include support for method argument injection:
@Test
public void shouldWithdrawFromAccount(@EJB AccountManager manager) throws Exception
{
   ...
}
  • Test method interceptors -- Another planned enricher SPI is a test method interceptor. With this we can add support for transactions:
@Test
@TransactionAttribute(TransactionAttributeType.REQUIRES_NEW)
public void shouldWithdrawFromAccount(@EJB AccountManager manager) throws Exception
{
   ...
}
  • Convention over configuration -- The micro deployments should be as easy as possible to create, so adding support for common conventions should help speed up the test development. For example we can automatically add all classes in the same package as the test class to the deployment
  • Arquillian controlled resources -- Sometimes the container requires container specific configuration e.g, java.naming.\* parameters needed to create a InitialContext. If the test case has to explicitly deal with this, it places the burden for container portability back on the test case author. Arquillian will provide an extension point to add Arquillian created/managed resources:
// auto creation of InitialContext based on running container, remote or local.
@ArquillianResource
private InitialContext context;

// auto creation of URL to a specific deployed Servlet, including http port/ip etc.
@ArquillianResource(MyServlet.class)
private URL myServletURL;

// the bundle context of a deployed osgi bundle
@ArquillianResource
private BundleContext context;
  • Add support for more containers -- We will plan to support more containers! Currently we have planned: GlassFish 3 (as a remote container), Jetty, Tomcat, Resin, Felix OSGI. (Hey Spring guys, you're welcome to join in too!)
  • Third party integrations -- In the spirit of ease of development, we integrate with existing test frameworks as much as possible, but we are always keen to learn of new frameworks we can integrate with. We already plan to support Selenium for example.
  • Support for other build tools -- Arquillian Alpha1 comes with Maven support. In upcoming releases, we will distribute builds targeted toward other build tools like Ant and Gradle (that shout out is for our resident Gradle expert, Jason Porter).
  • A project page, logo and artwork -- All good things must look good. That's why the JBoss.org design team is hard at work putting together artwork for the Arquillian project page. Stay tuned!

Where can I see Arquillian in use?

Arquillian is a new framework, but it's going to be put right to work as the workhorse to test all the Seam 3 modules. It will also be our recommended solution for testing your Seam application. (We'd love to see the community try it out for testing Seam 2 applications). We'll also replace the current core of the JSR-299 CDI TCK with Arquillian, likely for the 1.1 version of the TCK. (To provide a little history, Arquillian originated from the JBoss Test Harness that was developed by Pete Muir as the foundation of the CDI TCK).

If you have any thoughts on these ideas, or would like to suggest some new avenues we should explore, please contact us on the Arquillian Dev forum.

And, what's open source with out the community?!

A big thanks to the Arquillian and ShrinkWrap community for helping out on this release by being early adopters, joining in on community meetings, general discussions and writing blogs, articles and patches. In alphabetical order: Dan Allen, Steven Boscarine, German Escobar, Jordan Ganoff, Ken Gullaksen, Pete Muir, Jason Porter, Andrew Lee Rubinger. You guys rock!

[ JIRA ] | [ SPI Javadoc, API Javadoc ] | [ Reference Guide ] | [ Release Notes ] | [ Maven Artifacts ]

back to top