Arquillian Warp 1.0.0.Alpha3 Released

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 Warp component!

Warp Alpha3 is a last stop to Beta releases which brings mainly enhancements and bug fixes, but also a pretty new documentation:

Documentation Draft

Even though a documentation draft isn’t published yet to the Arquillian site, it is almost completed.

This documentation describes; where Warp’s place in a space of integration testing, how to start with Warp in your project, what features are supported by Warp API and few words about debugging tests and an extension architecture.

Highlighted Enhancements

Jacoco Support

Thanks to Aris Tzoumas, Warp users can now enjoy coverage reporting using arquillian-extension-jacoco. But the contribution was bigger than just that since it enabled a lot of other features.

Meaningful Reporting

The concepts Warp builds upon aren’t really complex, however the implementation needs to make sure that users can understand when something breaks. Warp tries to add as much contextual information as needed to overcome common issues together with a hint on how to resolve an issue.

We hope to improve reporting even more, but here we rely on you – don’t hesitate to report to us when your experience with Warp isn’t as smooth as it should be.

JSF Managed Beans Injection

You can now inject any managed artifact through EL expressions using standard ManagedProperty annotation:

@ManagedProperty(“#{facesContext.application}”) Application application;
@ManagedProperty(“#{myBean}”) SomeFacesBean myBean;

SPI enhancements

Independent Bi-directional Communication

During the Alpha3 development we have identified many common problems which came down to basics that Alpha2 was built upon: piggy-backing on HTTP request/response and wrapping HttpServletResponse.

In order to overcome those problems, Warp now leverages an internal SPI for bi-directional direct communication between test and server (originally created by Aris as a way to support Jacoco).

This is a fundamental change as it changes the way Warp transfers inspections and it also opens up to completely new possibilities by creating a tigher relationship between a test and a server.

Important Bug Fixes

Do not interfere with non-Warp tests

Warp Alpha2 wasn’t really a good citizen and it tried to hook into all tests even though they weren’t annotated with @WarpTest. Those problems should now be addressed.

Enjoy the Release

Alpha3 comes with lot of enhancements which improves the user experience, but it also brings some improvements which were needed to support rising REST and SeamTest migration layer extensions driven by Jakub Narloch and Marek Schmidt.

Let us know if we can smoothly enter a Beta releases train!

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 Warp
Version 1.0.0.Alpha3 view tag
Release date 2013-06-20
Released by Lukas Fryc
Compiled against

Published artifacts org.jboss.arquillian.extension

  • org.jboss.arquillian.extension » arquillian-warp-bom pom
  • org.jboss.arquillian.extension » arquillian-warp-api jar javadoc pom
  • org.jboss.arquillian.extension » arquillian-warp-spi jar javadoc pom
  • org.jboss.arquillian.extension » arquillian-warp-impl jar javadoc pom
  • org.jboss.arquillian.extension » arquillian-warp-jsf jar javadoc pom

Release notes and resolved issues 24

Bug fixes + Jacoco support

Component Upgrade
  • ARQ-1140 - Warp: upgrade LittleProxy to 0.5
  • ARQ-1415 - Warp: upgrade to Arquillian Core 1.0.4
  • ARQ-1416 - Warp: upgrade to ShrinkWrap resolver 1.0.0
Enhancement
  • ARQ-934 - Warp: Reuse manager during whole test
  • ARQ-1325 - Warp: replace piggy-backing on request/response with direct test->filter communication
  • ARQ-1353 - Warp: propagate manager's context to proxy correctly
  • ARQ-1361 - Warp: bring more clarity to ServerResponseTimeoutException failures
Feature Request
  • ARQ-1312 - Warp: introduce RequestProcessingDelegationService
  • ARQ-1319 - Warp: Jacoco support
  • ARQ-1367 - Warp: wrapped response causes NPE
  • ARQ-1368 - Warp: reverse order of chaining of request builder
  • ARQ-1371 - Warp: enricher allowing to inject JSF managed beans / properties
  • ARQ-1386 - Warp: provide a meaningful message when test isn't annotated with @WarpTest
  • ARQ-1400 - Failure to create Enrichment hidden by Client Assertion
Bug
  • ARQ-1027 - Support CommandService Protocol SPI via Warp Protocol
  • ARQ-1291 - Warp: single request execution does enrich only first request
  • ARQ-1320 - Warp - The NonWrittingResponse does not override the flushBuffer() method allowing for committing response.
  • ARQ-1324 - Warp HTTP request header size beyond reasonable limits
  • ARQ-1326 - Warp: the @RunAsClient tests uses proxy even in case the test is not @WarpTest
  • ARQ-1365 - Warp: CommandEventBus doesn't support (port) redirects
  • ARQ-1369 - Warp: TestContainerToClientChannel sporadically fails
  • ARQ-1395 - CommandBusService is started even tho the test is not a @WarpTest
  • ARQ-1396 - CommandEventBusService use wrong metadata to match Request URI
  • ARQ-1397 - Multiple problems running Warp on WildFly 8.0.0.Alpha1

Thanks to the following list of contributors: Lukas Fryc, Aris Tzoumas, Jakub Narloch, Aslak Knutsen

Arquillian Warp 1.0.0.Alpha2 Released

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.Alpha2 release of the Arquillian Warp component!

It has been a pretty long road from Alpha1 to this release, focused primarily on polishing the user experience.

So without any further ado, let’s look at the new shiny features!

Highlighted Features

Renaming Warp API methods

The API methods were renamed according to the results of our public survey. (read more)

In the simplest scenario you want to inspect the first request after performing a given client activity. For this purpose, you can use a basic Warp API known from Alpha1:

Warp
    .initiate(Activity)
    .inspect(Inspection);

This will intercept the first request coming from the client and ignore the rest of the potential requests.

Additionally, Warp will ignore requests for favicon.ico which could fail your test unexpectadly.

You can find more samples for this API in a source .

Anonymous and Inner Classes

It’s now much easier to define a verification code, which is also more readable.

In Alpha1, you had to use a top-level or a static inner classes to define inspections.

In Alpha2, you can provide non-static inner class or even anonymous class.

HelloWarp.java
Warp
    // first you need to initiate activity which triggers HTTP request
    .initiate(new Activity() {
        public void perform() {
            ajaxButton.click();
        }
    })

    // and then specify what behavior should be inspected on the server
    .inspect(new Inspection() {

        // don't forget to specify serialVerionUID to allow serialization
        private static final long serialVersionUID = 1L;
        
        // bring JSF context via dependency injection
        @ArquillianResource
        FacesContext facesContext;

        // verify expected behavior in given request phase
        @AfterPhase(RESTORE_VIEW)
        public void beforeServlet() {
            assertTrue(facesContext.isPostback());
        }
    });

This example showed how to use the new API together with anonymous inspections

Multiple Requests / Request Groups

It is possible to intercept several requests during one Warp execution.

Warp allows you to verify more than one request triggered by a single client activity. This allows you to verify e.g. a request for HTML page and all its resources (JS, CSS, images) separately. This feature is called Request Groups.

TestRequestGroups.java
// Request Group execution will return WarpResult
WarpResult result = Warp
    .initiate(Activity)
    // a group specification without name - the name will be generated
    .group()
        .observe(HttpRequestFilter)
        .inspect(Inspection1)
    // a named group specification - the result can be easily accessed
    .group("second")
        .observe(HttpRequestFilter)
        .inspect(Inspection2)
    // you need to execute whole Request Group once it is completely specified
    .execute();
    
    // you can access details of finished execution
    result.getGroup("second").getInspection();

The Request Groups execution returns a WarpResult which contains details about the finished execution. In order to access the results related to a specific group, you can give the group a name

Request Observers & Fluent API

The new API for observing the correct request allows you to select which request should be verified on a server.

When using Request Groups, all of the requests will be inspected by the inspections defined in that group. There might be one or more requests verified by each group.

Since multiple request can be triggered, you might want to choose the correct request to observe. For this purpose, we have the HttpRequestFilter interface, where you specify which HttpRequest should matches the current group.

import static org.jboss.arquillian.warp.client.filter.http.HttpFilters.request;

// will accept only requests for HTML
...group()
    .observe(request().uri().contains(".html"))

// will accept only REST requests for JSON
...group()
    .observe(request().header().containsValue("Accept", "application/json"))

// will accept only POST requests
...group()
   .observe(request().method().equal(POST))

In order to simplify writing the Warp specifications, you can define the observer using a fluent API and static factory methods.

Dependency Injection for Servlets and JSF

Test enrichers now allow the the injection of Servlet and JSF resources. (read more)

Renaming Phaser to Warp JSF

The JSF specific extension was renamed from Phaser to Warp JSF. (read more)

Introduction of Dependency Chain

The dependency chain was introduced to bring in all necessary dependencies by specifying just one dependency. (read more)

Warp Extensions for REST and Spring MVC

Thanks to Jakub Narloch, we have two new additions to Arquillian Galaxy. (read more)

Under the Hood

Usability and Debugging Improvements

A focus of Alpha2 was to polishing the way Warp behave in case of failures and on debuggability of Warp execution.

Validation of Warp Specification

Warp now validates that the number of observed requests match a number of expected requests. It also makes sure that all of defined lifecycle callbacks are executed on the server, to avoid any false positives.

As you can see there are many of new features, so let’s look at them separately:

Renaming Warp API

After Alpha1 we got several requests for clarifying the Warp high-level API:

Warp.execute(ClientAction).verify(ServerAssertion)

The announced survey helped us choose the new API. As a result, 88% of participants reported they found this new API more natural:

Warp.initiate(Activity).inspect(Inspection)

Big thanks to everyone who participated in the survey! This type of collaboration makes me really proud to be part of the team.

Warp Extensions: REST and Spring MVC

Warp was from the beginning built as a project that focused on any framework/technology that is based on top of the Servlet API.

Thus it’s not surprising that there are already two extensions shaping out thanks to Jakub Narloch:

Introduction of Dependency Chain

Putting Warp to work in your Maven project is now as easy as defining a single dependency:

pom.xml
<dependency>
    <groupId>org.jboss.arquillian.extension</groupId>
    <artifactId>arquillian-warp</artifactId>
    <version>1.0.0.Alpha2</version>
    <type>pom</type>
</dependency>

This declaration will bring Warp core, which supports Servlet API lifecycle callbacks.

Renaming Phaser to Warp JSF

Initially we had created Phaser as the next generation of the successful JSFUnit. It occured to use that Phaser is an unfortunate name and it just makes it harded to understand the Arquillian eco-system.

That’s why we have come up with a simpler variant – so let me introduce the Warp JSF extension.

You can bring Warp JSF to your project just by adding the following declaration:

pom.xml
<dependency>
    <groupId>org.jboss.arquillian.extension</groupId>
    <artifactId>arquillian-warp-jsf</artifactId>
    <version>1.0.0.Alpha2</version>
</dependency>

Dependency Injection for Servlets and JSF

After the announcement of the Alpha1 release, we focused on improving Warp to come closer to the Arquillian goal: bring all necessary dependencies to the test (in our case to inspection).

Now, you can not only inject all CDI managed beans (@Inject), EJB beans (@EJB) or container managed resources @Resource, but you can also inject the following resources:

  • Servlet resources
    • ServletRequest or HttpServletRequest
    • ServletResponse or HttpServletResponse
  • JSF resources
    • FacesContext
    • Application
    • ELContext, ELResolver, ExpressionFactory
    • ExceptionHandler
    • Flash
    • NavigationHandler
    • PartialViewContext
    • RenderKit
    • ResourceHandler
    • StateManager
    • UIViewRoot
    • ViewHandler

Migration from Alpha1

We’ve create a little bash script to convert the java source from Alpha1 API to Alpha2 that might help you with the upgrade.

How to Learn Warp?

The best way now is to look at functional tests for Warp or Warp JSF.

Roadmap

The roadmap to Beta1 is pretty clear:

  • documentation and guides
  • adding features known from SeamTest and JSFUnit
  • new injections and event hooks (e.g. improved CDI integration)
  • hardering and usability enhancements (here we rely on your issue reports!)

Along the way we will welcome every idea for integrating Warp with your favorite web framework – so don’t be a stranger and come to us!

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 Warp
Version 1.0.0.Alpha2 view tag
Release date 2013-01-08
Released by Lukas Fryc
Compiled against

Published artifacts org.jboss.arquillian.extension

  • org.jboss.arquillian.extension » arquillian-warp-bom pom
  • org.jboss.arquillian.extension » arquillian-warp-api jar javadoc pom
  • org.jboss.arquillian.extension » arquillian-warp-spi jar javadoc pom
  • org.jboss.arquillian.extension » arquillian-warp-impl jar javadoc pom
  • org.jboss.arquillian.extension » arquillian-warp-jsf jar javadoc pom

Release notes and resolved issues 35

Renaming API methods according to survey; Anonymous/Inner Class; Request Observers/Filters

Component Upgrade
  • ARQ-1052 - Upgrade Arquillian Core to 1.0.3.Final
  • ARQ-1053 - Upgrade Arquillian Drone to 1.1.0.Final
Enhancement
  • ARQ-979 - Exposed BeforeServlet and AfterServlet events to SPI
  • ARQ-980 - Make ServletRequest an injectable resource
  • ARQ-981 - Move BeforeServlet and AfterServlet events to SPI
  • ARQ-1060 - Fail to start a Warp test when @Deployment(testable=false) and when no @RunAsClient present
  • ARQ-1120 - Warp: safe propagation server-side failures to client-side
  • ARQ-1223 - Warp JSF: refactor PhaseLifecycleEvent to expose name of the event when debugging
  • ARQ-1224 - Warp: expose RequestContext and RequestScope to SPI
  • ARQ-1236 - Warp: filter favicon.ico requests by default
  • ARQ-1246 - Warp: single execution should observe only first request
Feature Request
  • ARQ-932 - Warp: support for inner/anonymous classes
  • ARQ-937 - Add usage examples to API/SPI classes
  • ARQ-964 - Verify that all tests in ServerAssertion has been called - prevents false negatives
  • ARQ-965 - Warp: Enable common JSF objects (FacesContext, Application) to be injected using @ArquillianResource
  • ARQ-967 - Warp: client-side filters for waiting for "right" request or enriching several requests
  • ARQ-1056 - Warp: Enable common JSF objects (FacesContext, Application) to be injected using @Inject
  • ARQ-1057 - Warp: Resource provider for HttpServletRequest/HttpServletResponse
  • ARQ-1061 - Debug output from Warp when Arquillian logging enabled
  • ARQ-1073 - Warp: buffering writer/stream re-initializes on each getWriter/getOutputStream call
  • ARQ-1204 - Builder for Warp filters.
Bug
  • ARQ-972 - Warp tests should be excluded from scanning by CDI container
  • ARQ-973 - Warp: if primitive field in ServerAssertion is changed during test, it is wrongly changed to initial value on deenrichment
  • ARQ-976 - The exceptions that occurrs in @AfterServlet test is not being propagated back to the client.
  • ARQ-982 - Response header size exceeded in Warp test.
  • ARQ-992 - Warp does not support request redirection.
  • ARQ-1063 - Warp: when both ServerAssertion and ClientAction fails, server error should be reported
  • ARQ-1163 - Warp: response is not properly commited
  • ARQ-1174 - Warp: DeploymentEnricher should check whether current TestClass is annotated with WarpTest
  • ARQ-1195 - Warp: do not remove static inner classes from deployment
  • ARQ-1197 - Warp: report that serialVersionUID was not set for Inspection
  • ARQ-1254 - Warp: RequestPayload decides whether transform class for all inspections instead of each inspection at own
Task
  • ARQ-1054 - Warp: rename arquillian-warp-phaser to arquillian-warp-jsf
  • ARQ-1055 - Introduce Warp depchain
  • ARQ-1233 - Warp: rename API according to results of survey

Thanks to the following list of contributors: Lukas Fryc, Jakub Narloch, Martin Kouba, Brian Leathem, Aslak Knutsen

Arquillian Warp 1.0.0.Alpha1 Released

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.Alpha1 release of the Arquillian Warp component!

  • Have you ever wanted to test a web application using real HTTP requests, but still have the opportunity to verify server-side state and behavior?
  • Wouldn’t it be great to have the full power of Arquillian Drone, driving Selenium or WebDriver on the client, then combine that with an Arquillian in-container test?

Now you can!

Ike’s innovative army has created yet another powerful weapon for your testing arsenal, Arquillian Warp.

Testing on both sides of the request

Arquillian Warp fills the void between client-side and server-side testing. Using Warp, you can initiate an HTTP request using a client-side testing tool such as WebDriver and, in the same request cycle, execute in-container server-side tests. This powerful combination lets you cover integration across client and server.

Now you can send real requests that execute real application logic and render content in a real browser and test it end-to-end. Mocks? Who needs those? Imagine the debugging possibilities this opens up!

This may sound like sci-fi, but it’s a reality. It’s advanced alien technology for killing real bugs that you can get your hands on today!

Let’s warp to the code

We’ll start with a normal Arquillian Drone client-side test with one enhancement, a @WarpTest annotation on the test class. This extra annotation instructs Arquillian Warp to enhance the request.

@WarpTest
@RunWith(Arquillian.class)
public class BasicWarpTest {
    @Drone
    WebDriver browser;

    @ArquillianResource
    URL contextPath;

    @Deployment
    public static WebArchive createDeployment() { ... }

    @Test
    @RunAsClient
    public void test_initial_page() {
        // triggers a HTTP request to a server
        browser.navigate().to(contextPath);
        // stay tuned...
    }
}

Note that you can use any HTTP client. For the sake of simplicity we’ve used @Drone to hook WebDriver (Selenium 2) into our test. Additionally, we’ve declared a web archive to be tested and injected its URL into the test case.

So far, we’ve defined a basic Drone test. Let’s start to warp this test so we can use it to test server-side logic as well. We begin by defining an implementation of ServerAssertion as an inner class of the test:

public static class InitialRequestAssertion extends ServerAssertion {
    @Inject
    TowelBean towel;

    @AfterPhase(RENDER_RESPONSE)
    public void test_initial_state() {
        // verify we are on right viewId
        assertEquals("/index.xhtml", FacesContext.getCurrentInstance().getViewRoot().getViewId());

        // assert the bean state
        assertNull(42, towelBean.getAnswerToLife());
    }
}

An object of this assertion class will be later enriched on the server (i.e., TowelBean will be injected) and then the lifecycle method annotated with @AfterPhase will be invoked in an appropriate phase of the request (after the response is rendered in the JSF lifecycle). This lifecycle method is effectively our server-side test.

All we need to do now is hook this assertion class to the request that is initiated by the browser. To do that, we warp the Selenium call in a Warp action:

@Test
@RunAsClient
public void test_initial_page() {
    // define the client action which will lead to HTTP request
    Warp.execute(new ClientAction() {
        public void action() {
            // the original request
            browser.navigate().to(contextPath);
        }
    
    // enhance the subsequent HTTP request with ServerAssertion
    }).verify(new InitialRequestAssertion());
}

That’s it! Here’s how it plays out:

  1. The Selenium-controlled browser initiates an HTTP request
  2. The request is trapped and enhanced with the InitialRequestAssertion object (which gets added as a payload of the request)
  3. When the request arrives at the server, the InitialRequestAssertion assertion object is registered with Arquillian and the request lifecycle proceeds
  4. After the response is rendered on the server, the InitialRequestAssertion object is enriched with all the required resources (EJB beans, CDI beans, Spring beans or Arquillian resources) and the lifecycle (test) method is invoked
  5. Once the request is complete, the InitialRequestAssertion object is sent back to the client
  6. If anything on the server-side failed (including assertions you defined), the failure is propagated back to the client and handled as a test failure

Currently, Warp supports lifecycle callbacks for the Servlet and JSF lifecycles, but it’s designed to be able to handle any server-side lifecycle.

Some of the highlights in this release

Support for Servlet events

Warp gives you the ability to test any Servlet lifecycle with these two lifecycle annotations:

@BeforeServlet – triggered before the request is processed by the Servlet
@AfterServlet – triggered after the request is processed by the Servlet

Support for JSF lifecycle events (Phaser extension)

Warp’s Phaser extension provides integration with the JSF lifecycle. You can use these lifecycle annotations to test the application in any JSF phase:

@BeforePhase(Phase) – triggered before the given JSF phase is executed
@AfterPhase(Phase) – triggered after the given JSF phase is executed

Compatible with any HTTP client

Warp works with any HTTP client: Selenium, HtmlUnit, HttpUnit, REST client, JavaScript test, Android device. No boundaries here!

Open to more protocols

Only the HTTP protocol is supported currently, but other protocols can be supported as well! (An SPI will be defined in a later releases)

Open to more frameworks

Warp is designed to support any server-side web framework based on the Servlets API

Need to know more?

You can find the complete Maven-based sample usage in the Arquillian Showcase.

Additionally, you can look at the functional tests in the Warp test suite:

Roadmap

In future releases, we’ll be looking into further improving the extension, most notably by providing framework-specific enrichments:

  • Injectable HttpServletRequest
  • Injectable FacesContext
  • etc.

Warp offers many possibilities for integration:

  • Support for wide range of server-side web frameworks (Wicket, Vaadin, GWT, Tapestry, …)
  • Support for alternative protocols (WebSockets)
  • Built-in support for variety of client-side testing tools

Call to action

If you would like to have support for your favorite web framework, you see features that are missing or you can see room for improvement, don’t hesitate and come to the Arquillian forums or the #arquillian channel on Freenode IRC!

We would love to hear your ideas and feedback for how to stretch Warp to reach beyond the boundaries of the test galaxy!

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 Warp
Version 1.0.0.Alpha1 view tag
Release date 2012-05-24
Released by Lukas Fryc
Compiled against

Published artifacts org.jboss.arquillian.extension

  • org.jboss.arquillian.extension » arquillian-warp-bom pom
  • org.jboss.arquillian.extension » arquillian-warp-api jar javadoc pom
  • org.jboss.arquillian.extension » arquillian-warp-spi jar javadoc pom
  • org.jboss.arquillian.extension » arquillian-warp-impl jar javadoc pom
  • org.jboss.arquillian.extension » arquillian-warp-phaser jar javadoc pom

Release notes and resolved issues 9

First Release of Warp Extension

Enhancement
  • ARQ-931 - Warp: Define API/SPI
  • ARQ-933 - Warp: server exception propagation
  • ARQ-948 - Make the ServerAssertion abstract class to ensure future compatibility
  • ARQ-955 - Warp: Define BOM
Feature Request
  • ARQ-578 - Create a Extension for handling Server State assertion during normal Servlet/JSF requests
  • ARQ-957 - Add Warp Showcase sample
Bug
  • ARQ-935 - Should handle de-enrich of final fields
  • ARQ-943 - Should be able to detect Serialization problems

Thanks to the following list of contributors: Lukas Fryc, Ken Finnigan, Aslak Knutsen