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
http://jakarta.apache.org/tomcat/index.html
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.
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
This document assumes basic familiarity with these technologies. If you need more detailed information about any of them, please refer to the links provided above.
If you need assistance in deploying the Tomcat servlet engine please refer to the following document
http://jakarta.apache.org/tomcat/tomcat-4.0-doc/RUNNING.txt
Development environment
JDK: 1.2.2 or higher
OS: Unix or Unix like
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
The explicit specification of the following JSSE packages are optional if you are using Sun JDK 1.4.0 or higher or IBM JDK 1.3.0 or higher with security options: jsse.jar, jnet.jar, jcert.jar, jce.jar
Build Test WebApp
Change your current directory to the root directory of the HttpClient source tree
Execute
</opt/ant>/bin/ant test-webapp-war
Where
</opt/ant> is the root directory of the Ant build tool
If all external dependencies have been correctly specified the execution of the Ant task should result in creation of the Java web archive at the following location:
./target/httpclienttest.war
Deploy Test WebApp
Stop Tomcat
./bin/shutdown.sh
Make sure you have write permissions for the following location
</var/tomcat/>webapps or /usr/local/jakarta-tomcat/webapps
Where
</var/tomcat/> is the base directory of the Tomcat service (CATALINA_BASE)
Drop the resultant WAR file into the </var/tomcat/>webapps directory
Restart Tomcat
./bin/startup.sh
Tomcat will check for new web archives in its base directory and automatically deploy them.
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="host";value="127.0.0.1:8080"
name="user-agent";value="Mozilla/5.0
(X11; U; Linux i686; en-US; rv:1.3a) Gecko/20021207
Phoenix/0.5"
name="accept";value="text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,video/x-mng,image/png,image/jpeg,image/gif;q=0.2,*/*;q=0.1"
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: the host name for the "local" webserver (default: 127.0.0.1)
httpclient.test.localPort: the port for the "local" webserver (default: 8080)
httpclient.test.webappContext: the context to which the test webapp is deployed (default: httpclienttest)
Execute
</opt/ant>/bin/ant test-local
Where
</opt/ant> is the root directory of the Ant build tool
You should receive BUILD SUCCESSFUL message if all test cases succeeded
In case of test failures you will see similar output
[java] .............. [java] Time: 18,067 [java] There was 1 failure: [java] 1) testConnTimeout(org.apache.commons.httpclient.TestHttpConnection)junit.framework.AssertionFailedError: Should have timed out [java] at org.apache.commons.httpclient.TestHttpConnection.testConnTimeout(TestHttpConnection.java:114) [java] at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) [java] at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) [java] at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25) [java] FAILURES!!! [java] Tests run: 260, Failures: 1, Errors: 0
Disregard WARN messages. The test cases run through valid and invalid cases and as such warnings are part of the HttpClient test sequence.