From: <mie...@us...> - 2009-06-23 21:03:37
|
Revision: 4838 http://oorexx.svn.sourceforge.net/oorexx/?rev=4838&view=rev Author: miesfeld Date: 2009-06-23 21:03:30 +0000 (Tue, 23 Jun 2009) Log Message: ----------- Incremental update to ooTest doc Modified Paths: -------------- docs/trunk/ootest/legalstuff_oot.sgml docs/trunk/ootest/oorexxunit.sgml docs/trunk/ootest/ootest.sgml docs/trunk/ootest/ootestframework.sgml docs/trunk/ootest/preface.sgml docs/trunk/ootest/testoorexx.sgml Modified: docs/trunk/ootest/legalstuff_oot.sgml =================================================================== --- docs/trunk/ootest/legalstuff_oot.sgml 2009-06-23 15:30:57 UTC (rev 4837) +++ docs/trunk/ootest/legalstuff_oot.sgml 2009-06-23 21:03:30 UTC (rev 4838) @@ -2,7 +2,7 @@ # # Description: SGML file for ooTest Documentation. # - # Copyright (c) 2008, Rexx Language Association. All rights reserved. + # Copyright (c) 2008-2009, Rexx Language Association. All rights reserved. # # This program and the accompanying materials are made available under # the terms of the Common Public License v1.0 which accompanies this @@ -44,6 +44,7 @@ <orgname>Rexx Language Association</orgname> <copyright> <year>2008</year> + <year>2009</year> <holder>Rexx Language Association. All rights reserved.</holder> </copyright> <authorgroup> @@ -54,7 +55,7 @@ # The following need to be modified for each release! #######################################################################--> <edition>Version 1.0.0</edition> -<pubdate>August 22, 2008</pubdate> +<pubdate>June 23, 2009</pubdate> <!--####################################################################### # The releaseinfo tag is used to show the release status of a document. # Modified: docs/trunk/ootest/oorexxunit.sgml =================================================================== --- docs/trunk/ootest/oorexxunit.sgml 2009-06-23 15:30:57 UTC (rev 4837) +++ docs/trunk/ootest/oorexxunit.sgml 2009-06-23 21:03:30 UTC (rev 4838) @@ -89,7 +89,7 @@ </programlisting> <para> - Description + To Be Written </para> </section> @@ -104,7 +104,7 @@ </programlisting> <para> - Description + To Be Written </para> </section> Modified: docs/trunk/ootest/ootest.sgml =================================================================== --- docs/trunk/ootest/ootest.sgml 2009-06-23 15:30:57 UTC (rev 4837) +++ docs/trunk/ootest/ootest.sgml 2009-06-23 21:03:30 UTC (rev 4838) @@ -1,7 +1,7 @@ <?xml version="1.0" standalone="no"> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [ -<!ENTITY legalstuff SYSTEM "../shared/legalstuff.sgml"> +<!ENTITY legalstuff SYSTEM "legalstuff_oot.sgml"> <!ENTITY preface SYSTEM "preface.sgml"> <!ENTITY chapOverview SYSTEM "testoorexx.sgml"> <!ENTITY chapOORexxUnit SYSTEM "oorexxunit.sgml"> Modified: docs/trunk/ootest/ootestframework.sgml =================================================================== --- docs/trunk/ootest/ootestframework.sgml 2009-06-23 15:30:57 UTC (rev 4837) +++ docs/trunk/ootest/ootestframework.sgml 2009-06-23 21:03:30 UTC (rev 4838) @@ -39,15 +39,59 @@ --> <chapter id="chapOOTest"><title>The ooTest Framework</title> -<indexterm><primary>ooTest</primary></indexterm> +<indexterm><primary>ooTest framework</primary></indexterm> +<indexterm><primary>ooTest</primary> +<secondary>frameworks</secondary></indexterm> <para> - x + The ooTest framework requires the <link linkend="chapOORexxUnit">ooRexxUnit framework</link>, that is + it uses a ::requires directive for <computeroutput>OOREXXUNIT.CLS</computeroutput>. It extends the + functionality of ooRexxUnit in ways that are not neccessarily intended to be generic, but rather are + only intended to serve some specific need in testing ooRexx. Most of the main classes in ooTest are + direct subclasses of a comparable class in ooRexxUnit, adding only minor functionality to the + ooRexxUnit class. </para> +<para> + This section of the book serves as a reference to the public classes, routines, and features of the + ooTest framework. It starts with a general discussion of where and how the framework differs from a + generic unit testing framework and the objects in the framework that implement these differences. The + rest of the material is the reference documentation for the classes and routines that the framework + provides. +</para> +<para id="ootInternalQualifier"> + The reference material is intended to be most useful to people writing test cases for ooRexx. Please + <emphasis role="bold">note</emphasis> how this is structured. Many of the classes and methods of the + framework are used to relieve the test case writer of much, or most, of the burden of implementation. + The test case writer, for the most part, only needs the documentation for a few classes and usually + only for a few methods of those classes. The rest of the classes and methods need only be understood + by the maintainers of the overall ooRexx testing project. +</para> +<para> + However, it makes little sense to document part of a class here, the part used by test case writers, + and the rest of the class in some other place, say a <emphasis role="italic">maintainers</emphasis> + manual. So this strategy is used: the primary classes a test case writer would use are documented + first. Within a class documentation, the methods and attributes most useful in writing test cases are + also documented first. The rest of the classes and methods will be marked with the keyword: <emphasis + role="italic">internal</emphasis>. This doesn't mean these classes or methods are only for internal + use. It is merely meant to indicate to the reader, who is mostly interested in writing test cases, that + she can probably ignore the classes and methods. +</para> +<section id="ooTestGeneralConcepts"><title>General Concepts</title> +<indexterm><primary>concepts</primary> +<secondary>ooTest framework</secondary></indexterm> + +<para> + Description +</para> + <section id="ootTestType"><title>Test Types</title> <indexterm><primary>test types</primary></indexterm> <para> + Test types are implemented through the <link linkend="clsooTestTypes">ooTestTypes</link> and <link + linkend="clsooTestCase">ooTestCase</link> classes. +</para> +<para> Unlike jUnit, which only does unit tests, ooTest is designed to automate all the testing for the ooRexx distribution package. There is of course more to software testing than unit tests. There are stress tests, performance tests, acceptance tests (does the distribution package install correctly, do all the @@ -96,6 +140,9 @@ </para> </section> + +</section> + <!-- Could be chapter, or section --> @@ -176,7 +223,7 @@ </programlisting> <para> - Description + To Be Written </para> </section> @@ -191,7 +238,7 @@ </programlisting> <para> - Description + To Be Written </para> </section> @@ -242,7 +289,7 @@ </programlisting> <para> - Description + To Be Written </para> </section> @@ -257,7 +304,7 @@ </programlisting> <para> - Description + To Be Written </para> </section> Modified: docs/trunk/ootest/preface.sgml =================================================================== --- docs/trunk/ootest/preface.sgml 2009-06-23 15:30:57 UTC (rev 4837) +++ docs/trunk/ootest/preface.sgml 2009-06-23 21:03:30 UTC (rev 4838) @@ -39,9 +39,10 @@ --> <preface id="preface"><title>About This Book</title> <para> - ooTest is a testing framework that facilitates the testing of the ooRexx interpreter. It sits on top - of the ooRexxUnit framework which is a generic testing framework that anyone can use to test their Rexx - applications. + ooTest in the broadest sense represents all the tools and components used to test ooRexx and all of the + tests written to date. Minus the written tests, ooTest is a testing framework that facilitates the + testing of the ooRexx interpreter. It sits on top of the ooRexxUnit framework which is a generic + testing framework that anyone can use to test their Rexx applications. </para> <para> The audience for this book is primarily those interested in testing the ooRexx interpreter. Either by @@ -52,10 +53,42 @@ </para> <para> This book does not provide information on how to program using ooRexx. The assumption is that the - reader is already familar with the intepreter and the use of objects in ooRexx. The book provides a - reference to the ooRexxUnit framework, a reference to the ooTest framework, and information on how to - write tests of the ooRexx interpreter package using the ooTest framework. + reader is already familar with the intepreter and, to some degree, the use of objects in ooRexx. The + book provides a reference to <computeroutput>testOORexx.rex</computeroutput>, the ooRexxUnit framework, + the ooTest framework, and information on how to write tests of the ooRexx interpreter package using the + ooTest framework. </para> +<para> + The book is roughly organized this way: + <itemizedlist> + <listitem> + <para> + An <link linkend="chapOverview">overview</link> of ooTest. + </para> + </listitem> + <listitem> + <para> + A chapter documenting <link linkend="chapTestOORexx">testOORexx.rex</link> which is currently the one + and only test driver propgram. + </para> + </listitem> + <listitem> + <para> + Chapter(s) documenting the <link linkend="chapOORexxUnit">ooRexxUnit</link> framework. + </para> + </listitem> + <listitem> + <para> + Chapter(s) documenting the <link linkend="chapOOTest">ooTest</link> framework. + </para> + </listitem> + <listitem> + <para> + Chapter(s) giving some <link linkend="chapWriteTests">guidence</link> in writing test cases using the ooTest framework. + </para> + </listitem> + </itemizedlist> +</para> <section id="relinf"><title>Related Information</title> <para>See also: Modified: docs/trunk/ootest/testoorexx.sgml =================================================================== --- docs/trunk/ootest/testoorexx.sgml 2009-06-23 15:30:57 UTC (rev 4837) +++ docs/trunk/ootest/testoorexx.sgml 2009-06-23 21:03:30 UTC (rev 4838) @@ -60,12 +60,55 @@ </para> <para> This document serves as a reference to the different components of ooTest. It explains how to execute - the tests, intepret the results, and gives some guidence in writing new tests. The document does not - have much detail on how to obtain ooTest or set it up. That is provided in numerous places. And, - indeed there is very little set up involved in ooTest. It is merely a matter of placing the ooTest - files on the system used to test. + the tests, intepret the results, and gives some guidence on writing new tests. There is very little + involved in obtaining and settin up ooTest. Indeed there is very little set up involved in ooTest. It + is merely a matter of placing the ooTest files on the system used to test. </para> +<section id="getOOTest"><title>Install ooTest</title> +<indexterm><primary>installing ooTest</primary></indexterm> +<indexterm><primary>install</primary> +<secondary>ooTest</secondary></indexterm> + +<para> + Getting and installing ooTest is extremely easy. There is no set up involved, you merely place the + ooTest directory structure on somewhere convenient on your system. The best method of obtaining the + ooTest directory structure is to use a Subversion client to check out the ooTest repository. + Subversion is widely avaliable, easy to install, and easy to use. Directions for obtaining Subversion + have been posted numerous times to the lists related to ooRexx. There is a wealth of information on + this subject on the Internet, simply use Google. +</para> +<para> + Once you have a Subversion client, the following command will check out ooTest and place its directory + structure in the subdirectory named <computeroutput>ooTest.4.0.0</computeroutput>. The subdirectory can + be named anything you wish. +<programlisting> +<![CDATA[ +C:\>svn co https://oorexx.svn.sourceforge.net/svnroot/oorexx/test/trunk ooTest.4.0.0 +]]> +</programlisting> + The command is exactly the same on any operating system. +</para> +<para> + The other way to obtain ooTest is to download one of the ooTest snapshots from the ooRexx project on + SourceForge. The drawback to this method is that the latest snapshot may not be current and you can + not use the Subversion tools to keep your copy of ooTest up-to-date. To download a snapshot go to this + link on SourceForge: + <ulink url="https://sourceforge.net/project/showfiles.php?group_id=119701&package_id=251951"> + <citetitle>SourceForge.net: Open Object Rexx Files</citetitle></ulink> and download the appropriate + file. Then either untar or unzip the file whereever is convenient. For example: +<programlisting> +<![CDATA[ +C:\>unzip ooTest-4.0.0-snapshot04_windows.i386.zip +]]> +</programlisting> + Once the directory structure is placed on your system, you are ready to go. Use the driver program, + <link linkend="chapTestOORexx">testOORexx.rexx</link> to execute some tests. The tests should run and + print out some statistics. This will ensure ooTest is working. The rest of this book goes into detail + on all aspects of ooTest. +</para> +</section> + <section id="ooTestFoundation"><title>History, Foundation</title> <indexterm><primary>ooTest</primary> <secondary>history</secondary></indexterm> @@ -189,11 +232,10 @@ contains <computeroutput>testOORexx.rex</computeroutput>. However, testOORexx.rex is designed to run from any location on the local machine's file system. The main purpose of this is to allow a developer to execute the test suite from within their build directory. But, as the following example - illustrates, testOORexx can be run from anywhere on the system: -<programlisting> -<![CDATA[ -D:\TravelDrive>c:\ooTest\testOORexx.rex -F SimpleTests -Searching for test containers.. + illustrates, testOORexx does not need to be run from the ooTest directory or a build directory, it can + be run from anywhere on the system: +<programlisting> <![CDATA[ +D:\TravelDrive>c:\ooTest\testOORexx.rex -F SimpleTests Searching for test containers.. Executing automated test suite.. ooTest Framework - Automated Test of the ooRexx Interpreter @@ -223,15 +265,19 @@ <para> <indexterm><primary>setTestEnv.bat</primary></indexterm> <indexterm><primary>setTestEnv.sh</primary></indexterm> - Although running testOORexx will correctly set up the PATH to executed the tests, some people may - prefer to change the path. This will allow running testOORexx from anywhere without having to type in - the complete path name of testOORexx, such as <computeroutput>C:\ooTest\testOORexx</computeroutput>. - In addition, on Windows testOORexx is able to completely set up the environment for executing all the - tests, but on unix-like systems the library path can not be set. On the unix-like systems, the library - path <emphasis role="bold">must be</emphasis> set prior to executing any test requiring one of the TODO - external binaries ADD LINK. Two small utility scripts, <computeroutput>setTestEnv.bat</computeroutput> - and <computeroutput>setTestEnv.sh</computeroutput> are provided to handle these chores. On Windows: -<programlisting> <![CDATA[ + Although running testOORexx will correctly set up the PATH to execute the tests, some people may prefer + to change the path in the environment. This will allow running testOORexx from anywhere without having + to type in the complete path name of testOORexx, such as + <computeroutput>C:\ooTest\testOORexx</computeroutput>. In addition, on Windows testOORexx is able to + completely set up the environment for executing all the tests, but on unix-like systems the library + path can not be set. On the unix-like systems, the library path <emphasis role="bold">must + be</emphasis> set prior to executing any test requiring one of the <link + linkend="externalBinariesTestOORexx">external binaries</link>. Two small utility scripts, + <computeroutput>setTestEnv.bat</computeroutput> and + <computeroutput>setTestEnv.sh</computeroutput> are provided to handle these chores. On Windows: + +<programlisting> +<![CDATA[ C:\ooTest>setTestEnv ]]> </programlisting> On a unix-like system be sure to source the utility script: @@ -302,7 +348,7 @@ <secondary>output</secondary></indexterm> <para> - Description + To Be Written </para> </section> @@ -340,7 +386,7 @@ <secondary>define</secondary></indexterm> <para> - Description + To Be Written </para> </section> @@ -349,7 +395,7 @@ <secondary>define</secondary></indexterm> <para> - Description + To Be Written </para> </section> @@ -358,7 +404,7 @@ <secondary>define</secondary></indexterm> <para> - Description + To Be Written </para> </section> @@ -382,7 +428,7 @@ <indexterm><primary>options.ooTest</primary></indexterm> <para> - Description + To Be Written </para> </section> @@ -392,10 +438,20 @@ <indexterm><primary>.testOpts</primary></indexterm> <para> - Description + To Be Written </para> </section> +<section id="externalBinariesTestOORexx"><title>External Binaries</title> +<indexterm><primary>testOORexx</primary> +<secondary>external binaries</secondary></indexterm> +<indexterm><primary>external binaries</primary></indexterm> + +<para> + To Be Written +</para> +</section> + </chapter> This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |