{section}
{column}

h1. Introduction

Some automatic tests, as integration tests, can require external resources. [Junit|http://junit.org/] provides a mechanism to simplify the management of these external resources in an automatic test context: [Rules|https://github.com/junit-team/junit/wiki/Rules].

The Petals JUnit Framework comes with several external resources ready to use:
* a Web server,
* a FTP server.

{column}
{column:width=35%}
{panel:title=Table of contents}{toc:outline=true}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list|showAnonymous=true|showCount=true|showLastTime=true}{panel}
{column}
{section}

h1. A Web server as external resource

The {{WebServer}} rule allows creation of files and folders that are guaranteed to be deleted when the test method finishes (whether it passes or fails):
{code}
public static class HasWebServer {
@Rule
public WebServer webServer = new WebServer();

@Test
public void testUsingWebServer() throws IOException {
// ...
this.webServer.addServlet(servlet, servletPath);
// ...
}
}
{code}

@Rule
public WebServer webServer = new WebServer();

// A web server listening on your own HTTP port
@Rule
public WebServer webServer = new WebServer(8080);
{code}

h2. Registering servlet

A web-server maps URLs on servlets. If your test requires a servlet, you can register a servlet through the API '{{WebServer.addServlet(httpServlet, path)}}', where '{{httpServlet}}' is your servlet to map on the URL path part '{path}}':
{code}
public static class HasWebServer {
@Rule
public WebServer webServer = new WebServer();

@Test
public void testUsingWebServer() throws IOException {
// ...
this.webServer.addServlet(servlet, servletPath);
// ...
}
}
{code}

h3. Pre-defined servlets

Several servlets are provided into the Petals JUnit Framework:
* {{FileServlet}} that replies with the content of a file,
* {{TextServlet}} that replies with a plain-text content.

h4. Working with {{FileServlet}}

The reply of this servlet is:
* the content-type that has been set when creating the servlet,
* the reply content is the content of the given file when creating the servlet.
{code}
public static class HasWebServer {
@Rule
public WebServer webServer = new WebServer();

@Test
public void testUsingWebServer() throws IOException {
// ...
final AbstractHttpServlet fileServlet = new FileServlet(
new File(Thread.currentThread().getContextClassLoader().getResource("my-file").toURI()),
MimeTypeConstants.APPLICATION_ZIP);
this.webServer.addServlet(fileServlet, fileServlet.getPath());
// ...
}
}
{code}

h4. Working with {{TextServlet}}

The reply of this servlet is:
* the content-type is '{{text/plain}}',
* the reply content is '{{A plain text}}'.
{code}
public static class HasWebServer {
@Rule
public WebServer webServer = new WebServer();

@Test
public void testUsingWebServer() throws IOException {
// ...
final AbstractHttpServlet textServlet = new textServlet();
this.webServer.addServlet(fileServlet, fileServlet.getPath());
// ...
}
}
{code}

h2. Getting the URL of a servlet to invoke

Some facilities was included to build the URL of a servlet to invoke:
* {{WebServer.getHttpBaseUrl()}} : returns the base part of URLs served by the web server,
* {{AbstractHttpServlet.getPath()}} : returns the URL path part of the servlet.
Combining both methods builds easily the URL of the servlet to invoke:
{code}

public static class HasWebServer {
@Rule
public WebServer webServer = new WebServer();

@Test
public void testUsingWebServer() throws IOException {
// ...
final AbstractHttpServlet textServlet = new textServlet();
this.webServer.addServlet(fileServlet, fileServlet.getPath());
// ...
final URL urlToInvoke = new URL(this.webServer.getHttpBaseUrl()
+ textServlet.getPath());
// ...
}