Rationale

Complex software development efforts with many developers collaborating on the same code base require a means of ensuring that changes introduced in one module do not produce a rippling effect on other modules by breaking some dependencies or assumptions. One of the widely employed approaches to achieve such goal calls for simultaneous development of software units and corresponding test cases. The latter can be executed against the former in order to ensure that the software units comply with their contract or programming interface. Such suite of test cases helps developers ensure formal validity and integrity of the their software artifact while it evolves through multiple development cycles.

JUnit, a popular open-source unit testing framework, has been employed in the HttpClient project. Please refer to the JUnit web site for more detailed information http://www.junit.org/index.htm

Different types of unit tests in the HttpClient project

  • Test cases that have no external dependencies in order to execute;
  • Test cases that require access to external public resources (usually high profile web sites);
  • Test cases that must be run against a local web application that implements test specific functions and produces specific HTTP responses. These tests are the most critical component of the entire test suite as they allow for testing of most arcane aspects of the HTTP protocol that are not easily reproducible with external resources.

It is absolutely crucial that patches are tested for compliance with the entire test suite in order to be considered for acceptance into the main CVS trunk

The purpose of this document is to help potential HttpClient contributors compile and deploy the test web application (later referred as Test WebApp)

Test WebApp external dependencies

In order to successfully compile the Test WebApp we need satisfy the following external dependencies

  • Apache Jakarta Tomcat

    servlet engine version 4.0.3 or higher. Technically any Servlet 2.3 and JSP 1.2 compliant servlet engine should do. However, the Test WebApp has been mostly used with Tomcat servlet engine. If you need assistance in deploying the Tomcat servlet engine please refer to this document
  • Apache Jakarta Ant

    build tool version 1.5.1 or higher
  • JUnit

    unit testing framework version 3.7 or higher
  • JavaTM Secure Socket Extension (JSSE)

    version 1.0.3 or higher

Development environment

HttpClient is a Java based framework and so is not tied to any particular platform. However setup instructions such as these must choose a particular enviroment to describe. This document will describe the setup for j2sdk1.4 on Unix.

  1. Specify Test WebApp build properties

    Update references in the file build.properties to refer to correct locations on your local system. The build.properties is located in the root directory of the HttpClient source tree. Most importantly the location of the following packages must be specified: junit.jar, servlet.jar

    For example, you can copy the build.properties.sample to your home directory as build.properties and modify the following lines to match your system configuration:

    • servlet.jar=/usr/local/jakarta-tomcat/common/lib/servlet.jar
    • junit.jar=/usr/local/junit/junit.jar

Build Test WebApp

From the root directory of the HttpClient source tree, run the following command:

/opt/ant test-webapp-war

If all external dependencies have been correctly specified the execution of the Ant task should result in creation of web archive target/httpclienttest.war.

Deploy Test WebApp

  • Shutdown Tomcat

    Run the shutdown script: /usr/local/jakarta-tomcat/bin/shutdown.sh

  • Copy the httpclienttest.war file into the webapps directory

    Your tomcat installations webapp directory might be in either /var/tomcat/webapps or /usr/local/jakarta-tomcat/webapps.

    Note: You can control where ant test-webapp-war target puts the generated httpclienttest.war file by modifying the test-webapp.dest property. This can be set to create the war file in the tomcat webapps directory so you can skip this manual step.

  • Startup Tomcap

    Run the startup script: /usr/local/jakarta-tomcat/bin/shutdown.sh

    Tomcat will check for new web archives in its base directory and automatically deploy them.

  • Test the deployment of the httpclienttest web archive

    Point your browser to the following URL: http://127.0.0.1:8080/httpclienttest/headers

    If the Test WebApp has been properly deployed and is ready for use you should see similar response in your browser

    This is a response to an HTTP GET request.

    Request Headers:

    name="user-agent";value="Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.3a) Phoenix/0.5"

    name="accept";value="text/xml,application/xml,application/xhtml+xml,text/html

    name="accept-language";value="en-us,en;q=0.5"

    name="accept-encoding";value="gzip,deflate,compress;q=0.9"

    name="accept-charset";value="ISO-8859-1,utf-8;q=0.7,*;q=0.7"

    name="keep-alive";value="300"

    name="connection";value="keep-alive"

Run test cases

In case you run a non-default installation of the Tomcat servlet engine you may need to update the following properties in the build.properties file

  • httpclient.test.localHost
  • httpclient.test.localPort
  • httpclient.test.webappContext

run the webapp tests using Ant:

ant test-local

You should receive BUILD SUCCESSFUL message if all test cases succeeded

Disregard WARN messages. The test cases run through valid and invalid cases and as such warnings are part of the HttpClient test sequence.