Arquillian Blog

Since we wrote this post we didn't laze around. Check our latest announcement.

The Arquillian team is proud to announce the 1.0.0.Beta3 release of the Arquillian Spring Framework Extension component!

It has again been a while since that last Arquillian Spring extension release, but it’s finally here. This release focus mainly on further integration and compatibility with the Arquillian Universe

Upgraded to Arquillian Core 1.1.x

With Arquillian Core 1.1.0.Final came the new ShrinkWrap Resolver 2.0 APIs.

The Arquillian Spring Deployers have been updated to support the new ShrinkWrap Resolver 2.0 APIs and should now work with the latest and greatest from the Arquillian Universe.

Arquillian Persistence Extension support

In this release we’ve added a new module, arquillian-persistence-spring, which integrates Spring with the Arquillian Persistence Extension.

More specifically, it’s an implementation of the Persistence Extension DataSourceProvider SPI.

This integration allow you to configure the Persistence Extension to operate on a DataSource configured in your Spring applicationContext.

Configure your DataSource and TransactionManager in the applicationContext.xml file. For example;

<bean id="dataSource" class="org.springframework.jdbc.datasource.DriverManagerDataSource">
   ...
</bean>

<bean id="txManager" class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
  <property name="dataSource" ref="dataSource"/>
</bean>

Then setup your Test case using the Spring, Transaction and Persistence Extension annotations:

@RunWith(Arquillian.class)
@Transactional(manager = "txManager")
@SpringConfiguration("applicationContext.xml")
@DataSource("dataSource")
public class JpaEmployeeRepositoryTestCase {

...

    @Test
    @ShouldMatchDataSet(value = "employee.yml", excludeColumns = "id")
    public void testSave() {

        Employee employee = new Employee();
        employee.setName("Test employee");

        employeeRepository.save(employee);

        employee = new Employee();
        employee.setName("New employee");

        employeeRepository.save(employee);
    }

    @UsingDataSet("employee.yml")
    @Cleanup(strategy = CleanupStrategy.USED_TABLES_ONLY)
    public void testGetEmployees() throws Exception {

        List<Employee> result = employeeRepository.getEmployees();

        assertNotNull("Method returned null list as result.", result);
        assertEquals("Two employees were expected.", 2, result.size());
    }
}

Optionally you can configure the transaction manager reference and data source reference globally for the whole test suite via arquillian.xml

<arquillian>
   <extension qualifier="transaction">
      <property name="manager">txManager</property>
   </extension>
   <extension qualifier="persistence">
      <property name="defaultDataSource">dataSource</property>
   </extension>
</arquillian>

See the Persistence Extension Reference Docs for more ingo

What is Arquillian?

Arquillian is open source software that empowers you to test JVM-based applications more effectively. Created to defend the software galaxy from bugs, Arquillian brings your test to the runtime so you can focus on testing your application's behavior rather than managing the runtime. Using Arquillian, you can develop a comprehensive suite of tests from the convenience of your IDE and run them in any IDE, build tool or continuous integration environment.

Release details

Component	Arquillian Spring Framework Extension
Version	1.0.0.Beta3 view tag
Release date	2014-06-26
Released by	Aslak Knutsen
Compiled against	Arquillian Core – 1.1.5.Final Arquillian Drone Extension – 1.3.1.Final Arquillian Warp – 1.0.0.Alpha7 Arquillian Transaction Extension – 1.0.1.Final Arquillian Persistence Extension – 1.0.0.Alpha7 JUnit – 4.8.1

Published artifacts org.jboss.arquillian.extension

• org.jboss.arquillian.extension » arquillian-service-deployer-spring-common jar javadoc pom
• org.jboss.arquillian.extension » arquillian-service-deployer-spring-2.5 jar javadoc pom
• org.jboss.arquillian.extension » arquillian-service-deployer-spring-3 jar javadoc pom
• org.jboss.arquillian.extension » arquillian-service-integration-spring jar javadoc pom
• org.jboss.arquillian.extension » arquillian-service-container-spring jar javadoc pom
• org.jboss.arquillian.extension » arquillian-service-integration-spring-inject jar javadoc pom
• org.jboss.arquillian.extension » arquillian-service-integration-spring-javaconfig jar javadoc pom
• org.jboss.arquillian.extension » arquillian-transaction-spring jar javadoc pom
• org.jboss.arquillian.extension » arquillian-persistence-spring jar javadoc pom
• org.jboss.arquillian.extension » arquillian-service-integration-spring-2.5-int-tests jar javadoc pom
• org.jboss.arquillian.extension » arquillian-service-integration-spring-3-int-tests jar javadoc pom
• org.jboss.arquillian.extension » arquillian-warp-spring jar javadoc pom

Release notes and resolved issues 3

Feature Request

• ARQ-1107 - Provide means for using Spring configured data sources through Persistence Extension
• ARQ-1402 - Upgrade ShrinkWrap Resolvers to 2.0.0 Beta

Bug

• ARQ-1806 - Disable failing Spring test due to unintended transactions behavior

Thanks to the following list of contributors: Aslak Knutsen, Tommy Tynjä, Jakub Narloch, Andrew Lee Rubinger

Since we wrote this post we didn't laze around. Check our latest announcement.

The Arquillian team is proud to announce the 1.1.5.Final release of the Arquillian Core component!

1.1.4.Final had some nasty bugs in it, 1.1.5.Final should have cleared these up.

What’s fixed in 1.1.5.Final?

Fixed false positives with JUnit from 1.1.4.Final

Arquillian Core 1.1.4.Final had a nasty bug where it would ‘erase’ some special exception cases that could happen In Container, that gave the Client side the wrong result.

This has now been fixed. Expected exceptions, Assumption and Injection errors should now be reported correctly(Both when using the @Rule and the @Test.expected variants).

JUnit @Rules support

JUnit rules has historically been a bit tricky with Arquillian. They are executed outside of the Before/After lifecycle where Arquillian has been hooking in, leaving us with no control over when they are executed.

This has in the past caused them to be executed both on the Client side and In Container. With 1.1.5.Final, we’ve moved how all this is executed and included @Rules into the Before/After handling.

This means, @Rules will follow the same rules as @Before/@After, that again follow the execution of @Test. If the @Test is executed In Container, so will the @Rule. If @Test executes on Client, so will the @Rule.

Internal TestResult state correlates with actual result

An old bug in Arquillian has been that the Internal state of the TestResult inside of Arquillian has not matched the TestResult reported by the Test Framework. This comes from how Arquillian work and integrate with the different Test Framework.

The normal case is when using @Test.expected Exception setup, Arquillian internally will report it as failed since it caught an Exception. But the Test Framework might later choose that, no, this was Expected. This happens after Arquillian gave up control of the result and we never had a callback to get this result updated to the actual state.

From the Users perspective, this is just an internal detail and has been nothing to worry about. We’ve been moving forward with the Arquillian Recorder Extension that create User reports for the test run based on the internal state. Because of this, these reports has come out a bit off.

This is now fixed for both the JUnit and TestNG integrations.

For Extension developers who require the correct TestResult; @Observe the After event.

Support exporting Deployments exploded

Arquillian has always supported exporting to disk the Archive that is about to be deployed to the container, either via the arquillian.deploymentExportPath System Property or via arquillian/engine/property@name=deploymentExportPath in arquillian.xml.

It dawned on us that if you’re exporting the deployments to disk, you’re probably interested in seeing the content.

With 1.1.5.Final you can add the arquillian.deploymentExportExploded System Property or arquillian/engine/property@name=deploymentExportExploded in arquillian.xml to have the deployment automatically exploded on export.

What is Arquillian?

Arquillian is open source software that empowers you to test JVM-based applications more effectively. Created to defend the software galaxy from bugs, Arquillian brings your test to the runtime so you can focus on testing your application's behavior rather than managing the runtime. Using Arquillian, you can develop a comprehensive suite of tests from the convenience of your IDE and run them in any IDE, build tool or continuous integration environment.

Release details

Component	Arquillian Core
Version	1.1.5.Final view tag
Release date	2014-06-25
Released by	Aslak Knutsen
Compiled against	ShrinkWrap – 1.2.2 ShrinkWrap Descriptors – 2.0.0-alpha-5 JUnit – 4.8.1 TestNG – 5.14.6

Published artifacts org.jboss.arquillian.core

• org.jboss.arquillian.core » arquillian-core-api jar javadoc pom
• org.jboss.arquillian.core » arquillian-core-spi jar javadoc pom
• org.jboss.arquillian.core » arquillian-core-impl-base jar javadoc pom
• org.jboss.arquillian.config » arquillian-config-api jar javadoc pom
• org.jboss.arquillian.config » arquillian-config-spi jar javadoc pom
• org.jboss.arquillian.config » arquillian-config-impl-base jar javadoc pom
• org.jboss.arquillian.test » arquillian-test-api jar javadoc pom
• org.jboss.arquillian.test » arquillian-test-spi jar javadoc pom
• org.jboss.arquillian.test » arquillian-test-impl-base jar javadoc pom
• org.jboss.arquillian.container » arquillian-container-spi jar javadoc pom
• org.jboss.arquillian.container » arquillian-container-impl-base jar javadoc pom
• org.jboss.arquillian.container » arquillian-container-test-api jar javadoc pom
• org.jboss.arquillian.container » arquillian-container-test-spi jar javadoc pom
• org.jboss.arquillian.container » arquillian-container-test-impl-base jar javadoc pom
• org.jboss.arquillian.junit » arquillian-junit-core jar javadoc pom
• org.jboss.arquillian.junit » arquillian-junit-standalone jar javadoc pom
• org.jboss.arquillian.junit » arquillian-junit-container jar javadoc pom
• org.jboss.arquillian.testng » arquillian-testng-core jar javadoc pom
• org.jboss.arquillian.testng » arquillian-testng-standalone jar javadoc pom
• org.jboss.arquillian.testng » arquillian-testng-container jar javadoc pom
• org.jboss.arquillian.testenricher » arquillian-testenricher-cdi jar javadoc pom
• org.jboss.arquillian.testenricher » arquillian-testenricher-ejb jar javadoc pom
• org.jboss.arquillian.testenricher » arquillian-testenricher-resource jar javadoc pom
• org.jboss.arquillian.testenricher » arquillian-testenricher-initialcontext jar javadoc pom
• org.jboss.arquillian.protocol » arquillian-protocol-servlet jar javadoc pom
• org.jboss.arquillian.protocol » arquillian-protocol-jmx jar javadoc pom
• org.jboss.arquillian » arquillian-bom pom

Release notes and resolved issues 15

Feature Request

• ARQ-286 - Should support JUnit @Rules
• ARQ-1606 - Support deploymentExportPath to export Exploded
• ARQ-1607 - Please avoid using arquillian.launch files, it makes Eclipse generate error logs
• ARQ-1802 - Expose the underlying HTTPConnection used by Servlet protocol to allow new protocols manipulation access.

Bug

• ARQ-181 - When using @Test expected exception, the internal state of the TestResult is unknown - JUnit
• ARQ-1437 - NPE in ExceptionProxy.readExternal() for root cause leads to deserializationProblem = true
• ARQ-1742 - Exception thrown before BeforeSuite event are not reported to user.
• ARQ-1758 - Test passes although it fails unexpectedly
• ARQ-1772 - Arquillian Debug does not print real event class
• ARQ-1773 - JUnittests pass when exception is thrown from @Before-annotated method
• ARQ-1796 - Regression: JUnit ExpectedException is not handled correctly
• ARQ-1801 - @Before not called with arquillian-junit-standalone
• ARQ-1803 - Deployments not being un-deploying when JUnit Category is used
• ARQ-1804 - When using @Test expected exception, the internal state of the TestResult is unknown - TestNG
• ARQ-1816 - Arquillian core is eating up framework exceptions

Thanks to the following list of contributors: Aslak Knutsen, Karol Lassak, Ales Justin

JPA type converters provide an easy way to define how an entity attribute gets persisted to the database. You can use them to implement lots of different features, e.g. to encrypt your data as I showed in a previous post: How to use a JPA Type Converter to encrypt your data
But writing the type converter is not enough. We also need to make sure, that it is working correctly.

In general, there are two ways to test a type converter. We could write a unit test to check, if the conversion works correctly. But a unit test performs a test of the isolated class without putting it into the real execution environment. That means that we will still not know, if the converter works in one of our applications. If everything is set up correctly, the persistence provider will call the converter before writing to and after reading from the database. So we also need to check if the type converter gets called by the persistence provider and if everything works fine under that condition. We need to test the converter inside of the container we want to use for our application.

We will have a look at how this can be done with Arquillian and its persistence extension.

Something about Arqillian

If you are already familiar with Arquillian, you can skip this part. For all of you who have never worked with Arquillian so far, I just want to give some basic information. You can find a more detailed description at the Arquillian Getting Started guide.

Arquillian is a test framework for in container testing. The idea is to do not mock the container you want to use but to test your code inside of it. This provides the advantage, that you can test if your code will also work in your execution environment and not only in your mocked up test scenario. Arquillian provides lots of functionality to manage the container, inject required resources like EJBs or an EntityManager and make your live much easier.

The Arquillian tests are executed by junit. This is great, because you can use them everywhere, where you can execute junit tests. And that means in your IDE, as part of your build process, on your CI server, simply everywhere.

Object under test

The following code snippet shows the object under test for this example. It is a type converter that encrypts and decrypts a String attribute. The converter gets called by the persistence provider before writing to and after reading from the database. If you want to read more about how this type converter works, check my posting about it.

@Converter
public class CryptoConverter implements AttributeConverter<String, String> {

    private static final String ALGORITHM = "AES/ECB/PKCS5Padding";
    private static final byte[] KEY = "MySuperSecretKey".getBytes();

    @Override
    public String convertToDatabaseColumn(String ccNumber) {
      // do some encryption
      Key key = new SecretKeySpec(KEY, "AES");
      try {
         Cipher c = Cipher.getInstance(ALGORITHM);
         c.init(Cipher.ENCRYPT_MODE, key);
         return Base64.encodeBytes(c.doFinal(ccNumber.getBytes()));
      } catch (Exception e) {
         throw new RuntimeException(e);
      }
    }

    @Override
    public String convertToEntityAttribute(String dbData) {
      // do some decryption
      Key key = new SecretKeySpec(KEY, "AES");
      try {
        Cipher c = Cipher.getInstance(ALGORITHM);
        c.init(Cipher.DECRYPT_MODE, key);
        return new String(c.doFinal(Base64.decode(dbData)));
      } catch (Exception e) {
        throw new RuntimeException(e);
      }
    }
}

Setting it up

Before we can start to write our tests, we need to define a few dependencies. I will only show how to configure the dependencies we need for this example. If you have not already set up arquillian tests for your project, you will have to do a little bit more. Please check the Getting Started guide to learn how to setup arquillian for your project. Don’t be afraid, there is not too much to do.

As you can see in the following snippet, we will use JUnit 4.11, Arquillian 1.1.3.Final, the Arquillian Persistence Extension 1.0.0.Alpha7 and the WildFly Application Server 8.1.0.Final.

<?xml version="1.0" encoding="UTF-8"?>
<project
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
    xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    
    ...

    <properties>
        <version.junit>4.11</version.junit>
        <version.arquillian>1.1.3.Final</version.arquillian>
        <version.arquillian_persistence>1.0.0.Alpha7</version.arquillian_persistence>
        <version.wildfly>8.1.0.Final</version.wildfly>
    </properties>

    <dependencyManagement>
        <dependencies>
            ...
            <dependency>
                <groupId>org.jboss.arquillian</groupId>
                <artifactId>arquillian-bom</artifactId>
                <version>${version.arquillian}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        ...
        <dependency>
            <groupId>javax.enterprise</groupId>
            <artifactId>cdi-api</artifactId>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>${version.junit}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.jboss.arquillian.junit</groupId>
            <artifactId>arquillian-junit-container</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.jboss.arquillian.extension</groupId>
            <artifactId>arquillian-persistence-dbunit</artifactId>
            <version>${version.arquillian_persistence}</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

Writing the tests

There are two things we need to do to setup our test environment. At first, we need to tell junit that this test shall be executed as a junit test. This is done by @RunWith(Arquillian.class).

Additionally, we need to create the test deployment, that will be deployed to the container. Therefore we need to implement at least one method and annotate it with @Deployment. As you can see in the following code snippet, we use ShrinkWrap to create a jar archive deployment. The archive contains the CreditCard entity, the CryptoConverter type converter and the test class. There is no need to include any EJBs or other classes which implement business logic. We can inject the EntityManager into our test case and use it directly to persist and read entities. We will have a more detailed look at it later on.

Additionally, we need to add some manifest resources to create a persistence unit, register the type converter and add an empty beans.xml to activate CDI. Please check the getting started guide to get more information on ShrinkWrap and creating deployments.

@RunWith(Arquillian.class)
public class TestCryptoConverter {

    @Deployment
    public static JavaArchive createDeployment() {
        return ShrinkWrap
                .create(JavaArchive.class)
                .addClasses(CreditCard.class, CryptoConverter.class,
                        TestCryptoConverter.class)
                .addAsManifestResource("META-INF/persistence.xml",
                        "persistence.xml")
                .addAsManifestResource("META-INF/orm.xml", "orm.xml")
                .addAsManifestResource(EmptyAsset.INSTANCE, "beans.xml");
    }

After this is done, we can start to write the test cases. At first, we will persist a CreditCard entity and check, if the credit card number gets encrypted by the CryptoConverter. Therefore we inject the EntityManager, create a CreditCard entity and pass it to the persist method of the EntityManager. The validation of the persisted data, is done by the Arquillian persistence extension. We just need to define the data we expect to be written to the database. The expected data is defined in the cc.yml file, which is referenced in the @ShouldMatchDataSet annotation. Because the id attribute is generated by the database, we want to exclude it from the validation. This can be done by referencing it in the excludeColumns attribute of the annotation.

    @PersistenceContext
    private EntityManager em;

    @Test
    @ShouldMatchDataSet(value = "data/cc.yml", excludeColumns = "id")
    public void testEncryption() {
        CreditCard cc = new CreditCard();
        cc.setName("My Name");
        cc.setCcNumber("123456789");

        this.em.persist(cc);
    }

The cc.yml contains the following information.

CreditCard:
  - id: 1
    name: My Name
    ccNumber: egFfkhd8cRh82tvsh3VVUg==

In the second test, we will check if we can search the database for a CreditCard entity with a given credit card number. Therefore we use the @UsingDataSet annotation to seed the database with data defined in the cc.yml file. Now we can use the injected EntityManager to call a named query to search for CreditCard entity with the given number.

    @Test
    @UsingDataSet("data/cc.yml")
    public void testRead() {
        CreditCard cc = this.em
                .createNamedQuery(CreditCard.BY_NUMBER, CreditCard.class)
                .setParameter("number", "123456789").getSingleResult();
        Assert.assertEquals("My Name", cc.getName());
    }

Conclusion

We used Arquillian and the Arquillian Persistence extension to test a JPA type converter. Therefore we injected the EntityManager and used the annotations @ShouldMatchData and @UsingDataSet to validate and seed the database with a yml file.
If you want to try it yourself, you can find the sources on github.
You can run it by calling: git clone https://github.com/thjanssen/JPA2.1.git && cd JPA2.1/CryptoConverter && mvn test

What are your experiences with testing your Java EE application with Arquillian? Please write a comment about it.

Want to learn more about Arquillian, see the Arquillian Guides: http://arquillian.org/guides/

About the author

Thorben Janssen is a senior developer with more than 10 years of experience in Java EE development and architecture. During these years he acted as developer, architect, project and technical lead to create high available, clustered mobile billing solutions and laboratory information management systems.
Visit his blog: http://www.thoughts-on-java.org or follow him on twitter and google+ to read more about Java EE7 and Arquillian.

Since we wrote this post we didn't laze around. Check our latest announcement.

The Arquillian team is proud to announce the 1.1.0.Final release of the Arquillian OSGi component!

What is Arquillian OSGi?

ShrinkWrap is the simplest way to create archives in Java. Using the fluent and intuitive ShrinkWrap API, developers may assemble JARs, WARs, and EARs to be deployed directly by Arquillian during testing.

Release details

Component	Arquillian OSGi
Modules	Arquillian OSGi :: Container :: JBoss :: Embedded Arquillian OSGi :: Container :: Felix :: Embedded Arquillian OSGi :: Container :: Equinox :: Embedded Arquillian OSGi :: Container :: Karaf :: Managed Arquillian OSGi :: Container :: Karaf :: Remote
Version	1.1.0.Final view tag
Release date	2014-06-11
Released by	Thomas Diesler
Compiled against	Arquillian Core – 1.1.2.Final ShrinkWrap – 1.1.2

Published artifacts org.jboss.arquillian.protocol

• org.jboss.arquillian.protocol » arquillian-protocol-osgi jar javadoc pom
• org.jboss.arquillian.testenricher » arquillian-testenricher-osgi jar javadoc pom
• org.jboss.arquillian.container » arquillian-container-osgi jar javadoc pom
• org.jboss.arquillian.container » arquillian-container-osgi-tests jar javadoc pom
• org.jboss.arquillian.container » arquillian-container-jbosgi-embedded jar javadoc pom
• org.jboss.arquillian.container » arquillian-container-felix-embedded jar javadoc pom
• org.jboss.arquillian.container » arquillian-container-equinox-embedded jar javadoc pom
• org.jboss.arquillian.container » arquillian-container-karaf-embedded jar javadoc pom
• org.jboss.arquillian.container » arquillian-container-karaf-managed jar javadoc pom
• org.jboss.arquillian.container » arquillian-container-karaf-remote jar javadoc pom

Thanks to the following list of contributors: Martin Basovnik, Stefan Bunciak, Thomas Diesler

Since we wrote this post we didn't laze around. Check our latest announcement.

The Arquillian team is proud to announce the 1.0.0.Alpha3 release of the Arquillian Recorder component!

What is Arquillian?

Arquillian is open source software that empowers you to test JVM-based applications more effectively. Created to defend the software galaxy from bugs, Arquillian brings your test to the runtime so you can focus on testing your application's behavior rather than managing the runtime. Using Arquillian, you can develop a comprehensive suite of tests from the convenience of your IDE and run them in any IDE, build tool or continuous integration environment.

Release details

Component	Arquillian Recorder
Version	1.0.0.Alpha3 view tag
Release date	2014-06-06
Released by	Stefan Miklosovic
Compiled against	Arquillian Core – 1.1.4.Final

Published artifacts org.arquillian.extension

• org.arquillian.extension » arquillian-recorder-api jar javadoc pom
• org.arquillian.extension » arquillian-recorder-spi jar javadoc pom
• org.arquillian.extension » arquillian-recorder-reporter-api jar javadoc pom
• org.arquillian.extension » arquillian-recorder-reporter-spi jar javadoc pom
• org.arquillian.extension » arquillian-recorder-reporter-impl jar javadoc pom
• org.arquillian.extension » arquillian-recorder-screenshooter-api jar javadoc pom
• org.arquillian.extension » arquillian-recorder-screenshooter-spi jar javadoc pom
• org.arquillian.extension » arquillian-recorder-screenshooter-impl-base jar javadoc pom
• org.arquillian.extension » arquillian-recorder-video-api jar javadoc pom
• org.arquillian.extension » arquillian-recorder-video-spi jar javadoc pom
• org.arquillian.extension » arquillian-recorder-video-impl-base jar javadoc pom

Release notes and resolved issues 5

Enhancement

• ARQ-1715 - Merge release profile to default profile

Feature Request

• ARQ-1706 - Add multilanguage to AsciiDocExporter
• ARQ-1726 - Reporter does not consider screenshots taken manually in test methods

Bug

• ARQ-1722 - Name of Screenshooter method setting screenshot type is mangled
• ARQ-1748 - Making html report with screenshooter on cp deletes target

Thanks to the following list of contributors: Stefan Miklosovic, Alex Soto, Karel Piwko