Overview

Hydrant is a collection of Ant scripts, shell scripts, and properties files that automate building and deployment of applications. Hydrant is documented in this HowTo.

The hydrant webapp-pinger sub-project builds JMeter test scripts that perform a "smoke-test" on web applications, generally webapps that are themselves built using hydrant. The smoke-test generally tests whether an application:

• is reachable via a specified URL;
• presents a login screen when a protected resource is requested; and,
• serves the protected resource after a valid username and password are presented

A smoke-test is not designed to assure that an application is functioning fully or properly, only that it is "live"!

The hydrant webapp-pingers are designed to be run with Ant, and invoked by a shell script.

Building Webapp Pingers with Hydrant

The webapp-pingers are generally built as part of an automated build of a set of applications. Details regarding how to configure a hydrant project so that a webapp-pinger script for that project will build properly is beyond the scope of this HowTo; the sample hydrant.properties file given in this HowTo (including its comments) is a guide to hydrant project configuration for webapp-pingers.

The webapp-pinger scripts generated during the hydrant automated build are specified in a configuration file, in hydrant/webapp-pinger/conf/default-pinger-builder.properties. This file may be substituted with another by specifying the Ant runtime parameter pinger.builder.properties.

Minimally, to successfully generate webapp-pinger scripts, the following hydrant sub-projects must be given as parameters to the top-level hydrant shell script (more info on running hydrant in this HowTo):

• ist-jxde
• webapp-pinger

Additionally, the hydrant sub-project directories corresponding to the tokens listed in the hydrant.project.list property of hydrant/webapp-pinger/conf/default-pinger-builder.properties (or other specified pinger-builder.properties file) must be present as sibling directories to hydrant/webapp-pinger.

The build-pingers target is the default in hydrant/webapp-pinger/build.xml. Run the usage target of the Ant script hydrant/webapp-pinger/build.xml for more information on invoking the webapp-pinger project's build-pingers target, including parameters that may be passed to the script. To run the usage target from a shell script (e.g., if ant is not on your machine's path), type: sh build-webapp-pinger.sh usage

Deploying the Webapp Pingers

Unless the webapp-pinger.build.home property in webapp-pinger-build.properties is set differently, the generated webapp-pinger scripts will be written to the target directory ${cvs.home}/webapp-pinger. The webapp-pingers may be run from there.

Alternately, the target directory and its dependencies (${cvs.home}/ist-jxde and ${cvs.home}/jmeter-#.#.#) may be copied to another machine or location from which the pingers may be run. If the property create.webapp-pinger.jar is set when the webapp-pingers are built, the file webapp-pinger.jar, containing the target directory and its dependencies will be created in ${cvs.home}. This single file may be moved to another machine and un-jarred as a more convenient method for copying the necessary files and directories.

Running a single Webapp Pinger

A single webapp-pinger is most conveniently run by invoking the shell script run-webapp-pinger.sh. Example:

        sh run-webapp-pinger.sh projectABC 
          -Dtest.base.host.name="server-qa.berkeley.edu"
          -Ddeploy.mode=qa
      

The following parameters may be passed to the shell script; the first parameter is required:

ping-target

required; the name of the app to be pinged; pass the app name only, without parameter name, per the example given above (e.g., projectABC)

test.base.host.name

optional, applies to all webapp-pingers; default, per webapp-pinger, is value in each hydrant project's properties file (generally a production-server name: server.berkeley.edu) e.g., -Dtest.base.host.name="server-qa.berkeley.edu" - note that double-quotes are necessary if a hyphen is part of the host name.

deploy.mode

optional, applies to all webapp-pingers; default, per webapp-pinger, is value in each hydrant project's properties file (generally, prod) e.g., -Ddeploy.mode=qa

stop.tests.on.first.error

optional; set parameter to stop running app tests upon first app test failure (otherwise all tests complete) e.g., -Dstop.tests.on.first.error=XXX

Running a set of Webapp Pingers

The complete set of webapp-pingers is most conveniently run by invoking the shell script run-webapp-pinger-set.sh. Example:

        sh run-webapp-pinger-set.sh 
          -Ddeploy.mode=qa 
          -Dtest.base.host.name="server-qa.berkeley.edu"
      

The following parameters may be passed to the shell script:

test.base.host.name

optional, applies to all webapp-pingers; default, per webapp-pinger, is value in each hydrant project's properties file (generally a production-server name: server.berkeley.edu) e.g., -Dtest.base.host.name="server-qa.berkeley.edu" - note that double-quotes are necessary if a hyphen is part of the host name.

deploy.mode

optional, applies to all webapp-pingers; default, per webapp-pinger, is value in each hydrant project's properties file (generally, prod) e.g., -Ddeploy.mode=qa

stop.tests.on.first.error

optional; set parameter to stop running app tests upon first app test failure (otherwise all tests complete) e.g., -Dstop.tests.on.first.error=XXX

Test Results

For a single webapp-pinger test, results are most conveniently viewed by opening the file ${webapp-pinger.build.home}/webapp-pinger/test-results/html/${app-name}-smoke-test-results.html in a browser window. Failed test steps render in a red, bolded font; if none of the tests appear in red, no failures occurred.

Results for sets of webapp-pinger tests are most conveniently viewed by opening the file ${webapp-pinger.build.home}/webapp-pinger/test-results/html/test-results-index.html in a browser window. Failed tests render in a red, bolded font; if all the application-specific links are shown in green, no failures occurred.

Other indications that failures occurred are:

Error Code on exit

The ant task that runs the pingers will exit with an error code of 1 (one) if any failures occur.

Failure-indicating file exists

The file ${webapp-pinger.build.home}/webapp-pinger/test-results/disposition/FAILURE_OCCURRED exists if any failures occurred

Ant output includes failure notice

As each test completes, the console log emits a message clearly indicating whether the test was a success or failure, e.g., * * * S U C C E S S * * *.