vanitha 01/03/06 12:20:18
Modified: doc design
Log:
Modified "jakarta-watchdog-4.0/doc/design" to reflect the new Watchdog-4.0
changes.
Revision Changes Path
1.2 +229 -96 jakarta-watchdog-4.0/doc/design
Index: design
===================================================================
RCS file: /home/cvs/jakarta-watchdog-4.0/doc/design,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- design 2000/10/03 22:16:02 1.1
+++ design 2001/03/06 20:20:17 1.2
@@ -1,103 +1,236 @@
+Jakarta Watchdog-4.0 Design Document
+====================================
+
+Overview
+========
+Watchdog-4.0 consists of various JSP and Servlet tests intended to validate JSP1.2
and Servlet2.3 specification and api.
+
+Watchdog-4.0 itself utilizes various other components namely:
+
+- Ant (ant.jar): Ant is a Java based build tool. In theory it is kind of like
"make" without makes wrinkles and with the full portability of pure java code.
+
+- GTest (testdriver.jar): GTest is a Java based single client used by the
Watchdog-4.0tests. Based on the rules of Ant, GTest is defined as a task for each
request in the jsp-gtest.xml and servlet-gtest.xml files, which are parsed by Ant.
Each of the GTest attributes (request="GET /test/binaries/image1.gif HTTP/1.0";
goldenFile="${gdir}/image1.gif"; responseMatch="PreInclude";
expectHeaders="Content-Type:image/gif"; exactMatch="true ) specified as part of the
'GET' request in the XML files, are defined as setter methods in the GTest client.
These setter methods must be defined as public void and takes a single argument. The
name of the method must begin with "set", followed by the attribute name, with the
first character in uppercase, and the rest in lowercase.
+
+
+Watchdog-4.0 Tests Approach:
+===========================
+
+The Watchdog-4.0 Tests will utilize the Tomcat Reference Implementation to develop
JSP and Servlet CTS tests.
+
+The tests will also use the 'GTest' client, to provide golden-file comparison for
result checking, session tracking, sending request headers etc.
+
+Each JSP or Servlet assertion will have a server-side test associated with it.
+
+There is one JSP/Servlet test for each method in the api.
+
+Tests exist for positive and negative assertions
+
+The fields 'testName', 'assertion' and 'testStrategy' provided in the jsp-gtest.xml
and servlet-gtest.xml reflect the assertion being tested and referenced in the
JSP1.2/Servlet2.3 specification.
+
+The JSPs and Servlet server-side code have comments in them that reflect the
assertion and purpose of the test.
+
+
+The following steps are taken for executing the Watchdog-4.0 tests:
+=================================================================
+1 User invokes watchdog.bat or watchdog.sh
+
+2.The above batch files invoke Ant with an XML file (jsp-gtest.xml /
servlet-gtest.xml) and a target in the XML as parameters
+
+3.Ant parses the XML file and executes the specified target
+
+4.Results are validated by the target either in the form of expected-header
results, return codes, golden-files or a combinations of them.
+
+
+Watchdog-4.0 Directory Structure
+===============================
+
+ [jakarta-watchdog-4.0]
+ |
+ |
+ ----------------------------
+ | | |
+ | | |
+ Readme | |
+ build.xml | |
+ build.bat | |
+ build.sh | |
+ | |
+ [doc] [src]
+ design |
+ |
+ |
+ ----------------------------------------------------------
+ | | | | |
+ | | | | |
+ | | | | |
+ | [golden-files] | | |
+ [bin] [clients] [conf] [etc] [server]
+ watchdog.sh | jsp-gtest.xml ear-dd.xml |
+ watchdog.bat [org] servlet-gtest.xml web.dtd |
+ | -------------
+ [apache] | |
+ | [jsp-tests] [servlet-tests]
+ [jcheck] | |
+ | ---------- |
+ ---------- | | |
+ | | [WEB-INF] [jsp] [WEB-INF]
+ [jsp] [servlet] |
+ -----------
+ | |
+ web.xml [classes]
+
+
+Watchdog-4.0 Tests Hierarchy
+============================
+The Watchdog-4.0 test hierarchy is divided into server-side JSP/Servlet tests and
on the client-side to have golden-files. These are basically the jsp-tests and the
servlet-tests directories.
+The client, GTest, resides as part of the 'lib/testdriver.jar' file. This is a
single client used to execute all the JSP and Servlet tests.
+
+jakarta-watchdog-4.0/Readme:This gives info on how to build the
Watchdog-4.0workspace and also its dependencies.
+
+
+Watchdog-4.0 Build:
+==================
+build.xml: This is a rules file that is input to ant for building the
Watchdog-4.0workspace
+build.sh, build.bat: These are platform specific scripts for building the workspace
+
+
+Misc Watchdog-4.0 Files:
+=======================
+jakarta-watchdog-4.0/src/conf/jsp-gtest.xml: List of all the JSP assertions tested
+jakarta-watchdog-4.0/src/conf/servlet-gtest.xml: List of all the Servlet assertions
tested
+jakarta-watchdog-4.0/src/bin/watchdog.sh,watchdog.bat: Platform dependant script
files to execute the Watchdog-4.0tests
+
+Watchdog-4.0 Client Files:
+=========================
+These are the golden-files used by each of the JSP/Servlet server-side tests after
the results are processed.
+The hierarchy for these follow the same path as the server-side tests. The parent
directory of these are specified by the name value pair in the XML files
(jsp-gtest.xml, servlet-gtest.xml). The field 'wgdir' and its value specify the
directory location of the golden-files.
+
+jakarta-watchdog-4.0/src/clients/org/apache/jcheck/jsp/client: JSP Clients
+jakarta-watchdog-4.0/src/clients/org/apache/jcheck/servlet/client: Servlet Clients
+
+
+Watchdog-4.0 Server-side Files:
+==============================
+
+JSP server-side tests:
+=====================
+
+jakarta-watchdog-4.0/src/server/jsp-tests/WEB-INF/classes: This contains all the
beans used refrenced by the JSP tests
+
+jakarta-watchdog-4.0/src/server/jsp-tests/WEB-INF/tlds: This contains all the tlds
refrenced by the JSP tag tests
+
+Core_syntax Tests:
+=================
+jakarta-watchdog-4.0/src/server/jsp-tests/jsp/core_syntax: This directory covers
tests for chapter#2-Core Syntax and Semantics and chapter#4 - Standard Actions and
Directives of the JSP1.2 specification.
+
+jakarta-watchdog-4.0/src/server/jsp-tests/jsp/core_syntax/beantests: Has tests for
useBean,setProperty and getProperty action tags.
-jakarta-watchdog
+jakarta-watchdog-4.0/src/server/jsp-tests/jsp/core_syntax/directives: Has tests for
the forward,include,page and taglib directive
+
+jakarta-watchdog-4.0/src/server/jsp-tests/jsp/core_syntax/implicitobjects: Has
tests for the implicit objects - request, response, pagecontext, out, session, config,
page, application
+
+jakarta-watchdog-4.0/src/server/jsp-tests/jsp/core_syntax/scripting: Has tests for
declaration, expressions and scriptlet.
+
+jakarta-watchdog-4.0/src/server/jsp-tests/jsp/core_syntax/misc: Has tests for
plugin.
+
+JSP Engine Tests:
================
-
-Watchdog overview
------------------
+jakarta-watchdog-4.0/src/server/jsp-tests/jsp/engine: These are tests for the
following api classes:
+javax.servlet.jsp.JspEngineInfo
+javax.servlet.jsp.JspFactory
+javax.servlet.jsp.JspWriter
+javax.servlet.jsp.PageContext
+
+JSP Tag Ext Tests:
+=================
+jakarta-watchdog-4.0/src/server/jsp-tests/jsp/tagext: These are tests for the
following api classes:
+javax.servlet.jsp.BodyContent
+javax.servlet.jsp.BodyTagSupport
+javax.servlet.jsp.TagData
+javax.servlet.jsp.TagSupport
+javax.servlet.jsp.VariableInfo
+
+It also has tests for the various options in the tag library descriptor. This is
specified in the following:
+jakarta-watchdog-4.0/src/server/jsp-tests/jsp/tagext/tld_resource_path
+
+Tests for the Lifecycle of Tag are located in:
+jakarta-watchdog-4.0/src/server/jsp-tests/jsp/tagext/LifeCycle
+
+
+Servlet server-side tests:
+=========================
+
+jakarta-watchdog-4.0/src/server/servlet-tests/WEB-INF/web.xml: Contains the
mappings for test servlets
+
+Tests for javax_servlet api:
+===========================
+
+jakarta-watchdog-4.0/src/server/servlet-tests/WEB-INF/classes/tests/javax_servlet/GenericServlet:
Tests for methods methods destroy(), getServletConfig(), getServletContext() and
getServletInfo() are provided.
+
+jakarta-watchdog-4.0/src/server/servlet-tests/WEB-INF/classes/tests/javax_servlet/RequestDispatcher:
Tests for methods forward() and include() are provided.
+
+jakarta-watchdog-4.0/src/server/servlet-tests/WEB-INF/classes/tests/javax_servlet/Servlet:
Tests for methods init(), getServletConfig(), getServletInfo() are present here.
+
+jakarta-watchdog-4.0/src/server/servlet-tests/WEB-INF/classes/tests/javax_servlet/ServletConfig:
Tests for methods getServletName(), getInitParameter(), getInitParameterNames,
getServletContext() are present here.
+
+jakarta-watchdog-4.0/src/server/servlet-tests/WEB-INF/classes/tests/javax_servlet/ServletContext:
Tests for methods specified in the javax.servlet.ServletContext interface. All of
them are postiive test cases.
+
+jakarta-watchdog-4.0/src/server/servlet-tests/WEB-INF/classes/tests/javax_servlet/ServletException:
Tests for methods specified in the javax.servlet.ServletException class. Tests for
the constructors are also provided.
+
+jakarta-watchdog-4.0/src/server/servlet-tests/WEB-INF/classes/tests/javax_servlet/ServletInputStream:
Tests for method javax.servlet.ServletInputStream.readLine().
+
+jakarta-watchdog-4.0/src/server/servlet-tests/WEB-INF/classes/tests/javax_servlet/ServletOutputStream:
Provides positive tests for methods specified in the
javax.servlet.ServletOutputStream class.
+
+jakarta-watchdog-4.0/src/server/servlet-tests/WEB-INF/classes/tests/javax_servlet/ServletRequest:
Provides positive tests for methods specified in the javax.servlet.ServletRequest
class.
+
+jakarta-watchdog-4.0/src/server/servlet-tests/WEB-INF/classes/tests/javax_servlet/ServletResponse:
Provides positive tests for methods specified in the javax.servlet.ServletResponse
class.
+
+jakarta-watchdog-4.0/src/server/servlet-tests/WEB-INF/classes/tests/javax_servlet/SingleThreadModel:
Provides positive test for javax.servlet.SingleThreadModel interface.
+
+jakarta-watchdog-4.0/src/server/servlet-tests/WEB-INF/classes/tests/javax_servlet/ServletOutputStream:
Provides positive tests for methods specified in the
javax.servlet.ServletOutputStream class.
+
+jakarta-watchdog-4.0/src/server/servlet-tests/WEB-INF/classes/tests/javax_servlet/UnavailableException:
Provides constructor tests for javax.servlet.UnavailableException class.
+
+
+Tests for javax_servlet_http api:
+================================
+
+jakarta-watchdog-4.0/src/server/servlet-tests/WEB-INF/classes/tests/javax_servlet_http/Cookie:
Provides positive tests for the Cookie class.
+
+jakarta-watchdog-4.0/src/server/servlet-tests/WEB-INF/classes/tests/javax_servlet_http/HttpServletRequest:
Provides positive tests for the HttpServletRequest class.
+
+jakarta-watchdog-4.0/src/server/servlet-tests/WEB-INF/classes/tests/javax_servlet_http/HttpServletResponse:
Provides positive tests for the HttpServletResponse class.
+
+jakarta-watchdog-4.0/src/server/servlet-tests/WEB-INF/classes/tests/javax_servlet_http/HttpSession:
Provides positive tests for the HttpSession class.
+
+
+How to add new Watchdog-4.0 test
+================================
+To add a new test to the Watchdog-4.0directory, do the following:
+
+- Create the server side code (JSP / Servlet) in the respective directory
+ (The new directory should be located in jakarta-watchdog-4.0/src/server/...)
+
+- Add all the related bean classes used by the JSP / Servlet in the respective
WEB-INF directory
+ (The new bean classes should be in
+ (JSP: jakarta-watchdog-4.0/src/server/jsp-tests/WEB-INF)
+ (Servlet: jakarta-watchdog-4.0/src/server/servlet-tests/WEB-INF)
+
+- Add golden-files if needed by the tests
+ (The new files should be located in
+ (JSP: jakarta-watchdog-4.0/src/clients/org/apache/jcheck/jsp/client)
+ (Servlet: jakarta-watchdog-4.0/src/clients/org/apache/jcheck/servlet/client)
+
+- If it is a servlet test, an entry is required in the web.xml located at
+ (Servlet: jakarta-watchdog-4.0/src/server/servlet-tests/WEB-INF/web.xml)
-Watchdog consists of various JSP and Servlet tests intended to validate
-JSP1.1 and Servlet2.2 API / specification.
+- Make an entry for the test in the jsp-gtest.xml / servlet-gtest.xml located at
+ (JSP/Servlet: jakarta-watchdog-4.0/src/conf )
-There are two forms of test frameworks:
- - Generic clients: these follow jsp.xml format and are driven by GTest harness
- This format is applicable to the tests which do not need complex result
processing
- on the client side.
- - Specialized clients: these tests follow servlet.xml format and are driven by
Moo harness
- This format should be used where complex processing of the results is
required on the
- client side.
-
-
-Watchdog itself utilizes various other components:
- Ant (ant.jar)
- Moo (moo.jar)
- GTest (testdriver.jar)
-
-
-1. user invokes watchdog.bat or watchdog.sh
-
-2. watchdog.bat or watchdog.sh invoke ant with an xml file and a target in the xml
as parameters
-
-3. ant parses the xml file and executes the specified target
-
-3. results are validated by the target either in the form of return codes or
golden-files or
- combinations of both.
-
-
-Directory structure
--------------------
-
- [jakarta-watchdog]
- |
- / \
- / | \
- / | \
- / | \
- / | \
- / | \
- / | \
- build.xml [doc] [src]
- build.bat |
- build.sh /|\
- / | \
- / | \
- / | \
- / | \
- /| | |\
- / | | | \
- / | | | \
- / | | | \
- [conf] [client] [etc] [server]
- jsp.xml | web.xml |
- servlet.xml [org] |
- | / \
- [apacge] / \
- | / \
- [jckeck] [jsp] [WEB-INF]
- | jsp-tests |
- [jsp] / | \
- | / | \
- [client] / | \
- / \ [classes] web.xml [lib]
- / \ ..servlets.. moo.jar
- ...golden-files...
-
-How to Add new tests
---------------------
-
-JSP Test
---------
- - Server side of the test
- % cd jakarta-watchdog/src/server/jsp
- % mkdir your-test-dir
- % cd your-test-dir
- % cp ~ your-test-jsp.jsp .
-
- - Client side of the test
- % cd jakarta-watchdog/src/conf
- % add your-test entry to either jsp.xml or servlet.xml
-
-Servlet Test
---------
- - Server side of the test
- % cd jakarta-watchdog/src/server/WEB-INF/classes
- % mkdir your-test-dir
- % cd your-test-dir
- % cp ~ your-test-servlet.java .
-
- - Client side of the test
- % cd jakarta-watchdog/src/conf
- % add your-test entry to either jsp.xml or servlet.xml
+- Clean the existing watchdog build (build.sh clean)
- - Edit web.xml for configuring servlet mappings
+- Build the new workspace (build.sh dist)
+- Test against the latest milestone Tomcat build
+- Putback the tests if they pass
