$Id: TESTING.txt,v 1.7 2003/06/04 06:16:04 oglueck Exp $
================================================================
Testing HttpClient
================================================================

DEPENDENCIES:

For testing changes to the component, you will need JUnit
(version 3.8 or later), which can be obtained from:

  http://www.junit.org/

To help the test process find JUnit, you may make a copy of the
build.properties.sample file, rename to build.properties, and
modify it to reflect the location of junit.jar.

TESTING:

You may use the provided Ant script to run the tests. There
are three primary test targets you'll want to consider:

* test-nohost
   - Runs all the "pure" unit tests--those that don't rely upon
     anything outside of the JUnit VM.

* test-local
   - Runs all of the tests that don't rely upon an external
     Internet connection. To run these tests you'll need
     a web server, and a servlet engine with the test web
     application installed.

* test
   - Runs all of the tests, including those that rely upon
     a "local" web server/servlet engine, as well as those
     that rely upon an external Internet connection.
     Developer's are encouraged to ensure that all of the
     "test" test cases pass before submitting or committing
     patches to httpclient.

BUILDING AND DEPLOYING THE TEST WEB APPLICATION:

Many of the JUnit tests make use of a web application developed
specifically for testing HTTP client.  To build the web
application, you'll need the Servlet classes (e.g., j2ee.jar
or servlet.jar).  You can either obtain the Servlet API from:

  http://java.sun.com/products/servlets

or use the one shipping with Tomcat under:

 <tomcat-home>/common/lib/servlet.jar

Note that you need a current version (2.3) of the Servlet API
like one shipping with a current Tomcat release. Trying to use
an old version will result in compile failure.

To help the build and test process find the servlet API, you may
make a copy of the build.properties.sample file, rename to
build.properties, and modify it to reflect the location of
servlet.jar on your computer.

To build the web application, run the "compile.test-webapp"
ant target.  This will generate a web application directory
ready to deploy to your favorite servlet engine.

For testing purposes, this web application is assumed to
be running in the context "httpclienttest" on the web server
running on port 8080 on 127.0.0.1.  You may change these
default values in your build.properties file by changing the
properties:

 httpclient.test.localHost
 httpclient.test.localPort

See TestWebapp for details.

This web application has been tested with Tomcat 3.2,
4.0 and 4.1.

ADDING TESTS:

To add a new Junit TestCase to one of the
"standard" Suites, you should add it to one
(and only one) of the following files:

 * TestNoHost.java
    - use this file if the test has no
      external dependencies (i.e., it
      runs entirely within the JUnit VM)

 * TestExternalHost.java
    - use this file if the test depends
      upon a connection to the public Internet

 * TestLocalHost.java
    - use this file if the test depends upon
      a local webserver (running on
      ${httpclient.test.localHost} and
      ${httpclient.test.localPort})

 * TestWebapp.java
    - use this file if the test depends upon
      the test webapp