You may have encountered the situation where Arquillian fails to run the test case when using a web container (Java EE 6 or Servlet), reporting this exception as the reason:

Caused by: java.lang.IllegalStateException: Error launching test [...]
    at org.jboss.arquillian.protocol.servlet_3.ServletMethodExecutor.invoke(ServletMethodExecutor.java:61)
    at org.jboss.arquillian.impl.handler.ContainerTestExecuter.callback(ContainerTestExecuter.java:50)
    at org.jboss.arquillian.impl.handler.ContainerTestExecuter.callback(ContainerTestExecuter.java:40)
    at org.jboss.arquillian.impl.event.MapEventManager.fire(MapEventManager.java:63)
    ... 26 more
Caused by: java.lang.IllegalStateException: Error launching test at http://localhost:8080/test/ArquillianServletRunner?outputMode=serializedObject&className=[...]&methodName=[...]. Kept on getting 404s.
    at org.jboss.arquillian.protocol.servlet_3.ServletMethodExecutor.execute(ServletMethodExecutor.java:125)
    at org.jboss.arquillian.protocol.servlet_3.ServletMethodExecutor.invoke(ServletMethodExecutor.java:57)
    ... 29 more

To be straightforward, Arquillian shouldn't let itself get into this situation. The negotiation with the server should be more robust, as should the validation of the archive being deployed. You can expect problems like this to be prevented by the time Arquillian emerges out of Alpha.

But you need to know how to resolve this today. Hence the purpose of this FAQ.

What this exception means is that the Servlet that Arquillian puts into your archive when it's deployed is not responding on the context path /test. There are a couple reasons why this problem might be occuring:

1. Your deployment is a WebArchive, but it's not named test.war
2. Your deployment is a WebArchive that contains a web.xml that uses the Servlet 2.3 DTD

Let's go through the checklist.

Naming your WebArchive

The first thing to ensure is that, as of Arquillian 1.0.0.Alpha4, if you are creating a WebArchive deployment, you must name it test.war. We recognize that's a really poor assumption on Arquillian's part. It's going away soon (see ARQ-153). Until then, just make sure you are using the following starting point:

@Deployment
public static void Archive<?> createDeployment()
{
   return ShrinkWrap.create(WebArchive.class, "test.war")
      ...;
}

If your archive has the correct name, you may need to check your web.xml.

Activating web-fragment.xml descriptors

Arquillian registers its Servlet using a new feature of Servlet 3.0, web.xml fragments (i.e., web-fragement.xml). If the web.xml that you add to the WebArchive uses the Servlet 2.3 DTD header, the Arquillian web-fragment.xml won't be processed and the mapping for ArquillianServletRunner won't be activated.

If you aren't using a web.xml in your WebArchive, then you don't have to worry about this problem.

Other causes

There may be other causes for this error that are not mentioned here. Please let us know if you discover another root cause and we will add it. The more cases we can document, the more robust we can make this part of Arquillian so you'll bump into this problem again (or you'll know exactly what do to to resolve it).

For web fragments, you have to use the 2.5 or 3.0 web-app deployment descriptor.  So anyone testing an older app with Arquillian will get this error, even in a Servlet 3.0 container.