Changeset 112 for trunk

Timestamp:

02/18/11 14:19:57 (15 months ago)

Author:

mgalloy

Message:

Docs.

Location:

trunk

Files:

• docs/using-mgunit.rst (modified) (1 diff)
• overview.txt (modified) (1 diff)
• src/assert.pro (modified) (1 diff)
• src/mgunit.pro (modified) (2 diffs)
• src/mgutclirunner__define.pro (modified) (1 diff)
• src/mgutcompoundrunner__define.pro (modified) (1 diff)
• src/mgutguirunner__define.pro (modified) (1 diff)
• src/mguthtmlrunner__define.pro (modified) (1 diff)
• src/mgutjunitrunner__define.pro (modified) (1 diff)
• src/mguttestcase__define.pro (modified) (11 diffs)
• src/mguttestrunner__define.pro (modified) (1 diff)
• src/mguttestsuite__define.pro (modified) (10 diffs)
• src/mgutxmlrunner__define.pro (modified) (1 diff)

trunk/docs/using-mgunit.rst

@@ -153 +153 @@
 This will send the normal output to the results.log file.
 
-HTML output can also be created with the boolean `HTML`` keyword to the `MGUNIT`` routine. Generally, the `FILENAME` keyword is used in conjunction with this option::
+HTML output can also be created with the boolean `HTML` keyword to the `MGUNIT` routine. Generally, the `FILENAME` keyword is used in conjunction with this option::
 
   IDL> mgunit, 'indgen_uts', filename='test-results.html', /html

trunk/overview.txt

@@ -1 @@
-`mgunit` is a lightweight framework for writing unit tests intended to take the pain out of writing boilerplate code to run tests and tally the results, leaving you free to create as many tests as are useful for your purposes.
+`mgunit` is a unit testing framework modeled on other `xUnit testing frameworks <http://en.wikipedia.org/wiki/XUnit>`. The goal is to allow easy creation and reporting of results of tests, while still allowing for many different testing situations. Simple naming conventions replace formal creation of hierarchies and specification of tests. This allows test suites to be created with a minimum of code beyond the actual code of the tests themselves.
 
-See ``Using mgunit`` in the `docs` directory for more details about using `mgunit`.
+See "Using mgunit" in the `docs` directory for more details about using `mgunit`.
+
+The basic structure of `mgunit` is that tests are created by subclassing `MGutTestCase`, tests can be grouped together into suites for convenience by subclassing `MGutTestSuite`, and tests are run my calling `mgunit`. The `assert` routine is useful inside a test for making an assertion during the test. The `error_is_pass.pro` batch file is useful to include in a test when the test is supposed to crash. 
 
 :Dirs:

trunk/src/assert.pro

@@ -4 +4 @@
 ; Raises an error if the given condition is not met. Uses `logical_predicate`
 ; to determine truth of condition: so zero or null values are false, anything
-; else is true. Be careful of conditions like::
+; else is true. Be careful of conditions like the following::
 ;     
 ;    assert, not file_test(filename)
 ;
-; which use bitwise operators (the above is always false).
+; This uses the bitwise `not` operator and therefore this assertation is 
+; always false.
+;
+; :Examples:
+;    It is typical to check the error in a calculation like the following::
+;
+;       assert, error gt tolerance, 'incorrect result, error = %f', error
+;
+;    It is also useful to check a pre-condition for running a test at the 
+;    beginning of the test and skip the test if not met::
+;
+;       assert, long(strmid(!version.release, 1, 1)) ge 8, $
+;               'IDL version too old: %s', !version.release, $
+;               /skip
 ;
 ; :Params: 
 ;    condition : in, required, type=boolean
 ;       condition to assert
-;    msg : in, optional, type=string, default="Assertion failed"
+;    msg : in, optional, type=string, default="'Assertion failed'"
 ;       message to throw if condition is not met
 ;    arg1 : in, optional, type=string
-;       argument for any C format codes in msg
+;       first argument for any C format codes in msg
 ;    arg2 : in, optional, type=string
-;       argument for any C format codes in msg
+;       second argument for any C format codes in msg
 ;    arg3 : in, optional, type=string
-;       argument for any C format codes in msg
+;       third argument for any C format codes in msg
 ;
 ; :Keywords:
 ;    skip : in, optional, type=boolean
-;       set to skip test instead of fail
+;       set to skip the current test instead of passing or failing
 ;-
 pro assert, condition, msg, arg1, arg2, arg3, skip=skip

trunk/src/mgunit.pro

@@ -3 +3 @@
 ;+
 ; Determines if the current terminal is a TTY, calling `MG_TERMISTTY` safely
-; even if cmdline_tools is not installed or built.
+; even if `cmdline_tools` is not installed or built.
+;
+; :Private:
 ;
 ; :Returns: 
@@ -22 +24 @@
 
 ;+
-; Runs unit tests. 
+; Runs unit tests provided.
+;
+; :Examples:
+;    If there tests `test1_ut__define.pro` and test2_ut__define.pro` had been
+;    created, then they could be run like::
+;
+;       IDL> mgunit, ['test1_ut', 'test2_ut']
+;
+;    Or one could be run individually like::
+;
+;       IDL> mgunit, 'test1_ut'
 ; 
 ; :Params:
 ;    tests : in, optional, type=strarr
-;       array of test suites and/or test cases
+;       array of test suite and/or test case classnames
 ;
 ; :Keywords:

trunk/src/mgutclirunner__define.pro

@@ -5 +5 @@
 ; runner. The `MGutCliRunner` displays the results in the output log or in a 
 ; log file.
+;
+; :Private:
 ;-
 

trunk/src/mgutcompoundrunner__define.pro

@@ -5 +5 @@
 ; runner. The `MGutCompoundRunner` allows results to be sent to multiple
 ; test runners, e.g., to the display and to a file.
+;
+; :Private:
 ;-
 

trunk/src/mgutguirunner__define.pro

@@ -4 +4 @@
 ; Results for tests, test cases, and test suites are reported to the test 
 ; runner. The `MGutGUIRunner` displays the results in an interactive GUI.
+;
+; :Private:
 ;-
 

trunk/src/mguthtmlrunner__define.pro

@@ -4 +4 @@
 ; Results for tests, test cases, and test suites are reported to the test 
 ; runner. The `MGutHTMLRunner` displays the results in the output HTML file.
+;
+; :Private:
 ;-
 

trunk/src/mgutjunitrunner__define.pro

@@ -26 +26 @@
 ;      </testsuite>
 ;    </testsuites>
+;
+; :Private:
 ;-
 

trunk/src/mguttestcase__define.pro

@@ -2 +2 @@
 
 ;+
-; Subclass `MGutTestCase` to actually write tests. Any function method whose 
-; name starts with "test" will be considered a test. Tests are executed and 
-; results are reported to the test runner object.
-;-
+; Subclass `MGutTestCase` to actually write tests. In a subclass of 
+; `MGutTestCase`, any function method whose name starts with "test" will be 
+; considered a test. Tests are executed and results are reported to the test 
+; runner object.
+;
+; :Examples:
+;    To write your own tests, simply subclass from this class and make methods
+;    that start with "test"::
+;
+;       pro mytest::test_myroutine
+;         compile_opt strictarr
+;          
+;         answer = myroutine(1.0)   ; answer should be 2.
+;         assert, abs(answer - 2.) lt 0.01, 'incorrect result, %f', answer
+;
+;         return, 1
+;       end
+;
+;       pro mytest__define
+;         compile_opt strictarr
+;          
+;         define = { mytest, inherits MGutTaseCase }
+;       end
+;
+; :Properties:
+;    npass : type=integer
+;       number of passing tests
+;    nfail : type=integer 
+;       number of failing tests
+;    nskip : type=integer 
+;       number of skipped tests
+;    ntests : type=integer
+;       number of tests
+;    testnames : type=strarr 
+;       array of method names which begin with "test"
+;-
+
 
 ;+
@@ -27 +60 @@
 ;+
 ; Set this test to be skipped.
+;
+; :Private:
 ;-
 pro mguttestcase::skip
@@ -38 +73 @@
 ; This is a safe place to actually run a single test. Any errors that occur 
 ; are assumed to be from the test and recorded as a failure for it.
+;
+; :Private:
 ;
 ; :Returns: 
@@ -75 +112 @@
 ; Run setup method before each test.
 ;
+; :Private:
+; 
 ; :Keywords:
 ;    fail : out, optional, type=boolean
@@ -98 +137 @@
 ; Run teardown method before each test.
 ;
+; :Private:
+;
 ; :Keywords:
 ;    fail : out, optional, type=boolean
@@ -119 +160 @@
 
 ;+
-; Removes the given prefix from the msg if present.
+; Removes the given `prefix` from the `msg` if present.
 ; 
+; :Private:
+;
 ; :Params:
 ;    msg : in, required, type=string
@@ -139 +182 @@
 ;+
 ; Display test results via test runner methods.
+;
+; :Private:
 ;-
 pro mguttestcase::display
@@ -167 +212 @@
 ; Run the tests for this class (i.e. methods with names that start with 
 ; "test").
+;
+; :Private:
 ;-
 pro mguttestcase::run
@@ -258 +305 @@
 ; Find the name and number of tests (i.e. methods with names that start with 
 ; "test").
+;
+; :Private:
 ;-
 pro mguttestcase::findTestnames
@@ -284 +333 @@
 ;+
 ; Get properties of the object.
-; 
-; :Keywords:
-;    npass : out, optional, type=integer
-;       number of passing tests
-;    nfail : out, optional, type=integer 
-;       number of failing tests
-;    nskip : out, optional, type=integer 
-;       number of skipped tests
-;    ntests : out, optional, type=integer
-;       number of tests
-;    testnames : out, optional, type=strarr 
-;       array of method names which begin with "test"
 ;-
 pro mguttestcase::getProperty, npass=npass, nfail=nfail, nskip=nskip, $
@@ -312 +349 @@
 ; Test suites can contain other test suites or test cases. The level is the
 ; number of layers down from the top most test suite (level 0).
+;
+; :Private:
 ;
 ; :Params:

trunk/src/mguttestrunner__define.pro

@@ -5 +5 @@
 ; runner. Each subclass of MGutTestRunner displays them in some way. 
 ; MGutTestRunner itself is abstract and shouldn't be instantiated.  
+;
+; :Private:
 ;-
 

trunk/src/mguttestsuite__define.pro

@@ -5 +5 @@
 ; and add test suites/test cases in its `init` method or create an 
 ; `MGutTestSuite` and use the `add` method to add test suites/cases.
+;
+; For example, it is typical do create a test suite like the following::
+;
+;    function mytestsuite_uts::init, _extra=e
+;      compile_opt strictarr
+;
+;      if (~self->MGutTestSuite::init(_strict_extra=e)) then return, 0
+;
+;      self->add, /all
+;
+;      return, 1
+;    end
+;
+;    pro mytestsuite_uts__define
+;      compile_opt strictarr
+;
+;      define = { MyTestSuite_uts, inherits MGutTestSuite }
+;    end
+;
+; This test will add all the files in the current directory that end in 
+; "_ut__define.pro" as test cases. Then the following will run all the test
+; cases in a directory::
+;
+;    IDL> mgunit, 'mytestsuite_uts'
+;
+; :Properties:
+;    home : type=string
+;       location of the root of the test suite
+;    failures_only : type=boolean
+;       set to report only failed tests
+;    name : type=string
+;       name of the object
+;    npass : type=integer
+;       number of passing tests contained in the hierarchy below this object
+;    nfail : type=integer
+;       number of failing tests contained in the hierarchy below this object
+;    nskip : type=integer
+;       number of skipped tests contained in the hierarchy below this object
+;    ntestcases : type=integer
+;       number of directly contained test suites or test cases
+;    ntests : type=integer
+;       number of tests contained in the hierarchy below this object
+;    test_runner : in, required, type=object
+;       subclass of `MGtestRunner`
 ;-
 
@@ -11 +55 @@
 ; Recompile the class definition before creating the object to make sure it is
 ; the newest definition (convenient when making changes to a test).
+;
+; :Private:
 ;
 ; :Params:
@@ -34 +80 @@
 ; it.
 ;
+; :Private:
+;
 ; :Returns: 
-;    obj
+;    object
 ;
 ; :Params:
@@ -67 +115 @@
 ; Recompiles all test cases contained by the suite or contained by child 
 ; suites.
+; 
+; :Private:
 ;-
 pro mguttestsuite::recompileTestCases
@@ -84 +134 @@
 ;+
 ; Display test results via test runner methods.
+; 
+; :Private:
 ;-
 pro mguttestsuite::display
@@ -110 +162 @@
 ;+
 ; Run the contained test suites or test cases.
+;
+; :Private:
 ;-
 pro mguttestsuite::run
@@ -158 +212 @@
 ;       set to add all the files in the current directory that end in 
 ;       "_ut__define.pro" (the current directory is defined to be the 
-;       directory where the method calls this method is located)
+;       directory where the method calling this method is located)
 ;-
 pro mguttestsuite::add, tests, all=all
@@ -232 +286 @@
 ;+
 ; Get properties of the object.
-;
-; :Keywords:
-;    name : out, optional, type=string
-;       name of the object
-;    npass : out, optional, type=integer
-;       number of passing tests contained in the hierarchy below this object
-;    nfail : out, optional, type=integer
-;       number of failing tests contained in the hierarchy below this object
-;    nskip : out, optional, type=integer
-;       number of skipped tests contained in the hierarchy below this object
-;    ntestcases : out, optional, type=integer
-;       number of directly contained test suites or test cases
-;    ntests : out, optional, type=integer
-;       number of tests contained in the hierarchy below this object
 ;-
 pro mguttestsuite::getProperty, name=name, $
@@ -275 +315 @@
 ; number of layers down from the top most test suite (level 0).
 ;
+; :Private:
+;
 ; :Params:
 ;    level : in, required, type=integer
@@ -311 +353 @@
 ;    home : in, optional, type=string, default=''
 ;       location of the root of the test suite
-;    test_runner : in, required, type=object
-;       subclass of MGtestRunner
-;    failures_only : in, optional, type=boolean
-;       set to report only failed tests
+
+
 ;-
 function mguttestsuite::init, name=name, home=home, test_runner=testRunner, $

trunk/src/mgutxmlrunner__define.pro

@@ -4 +4 @@
 ; Results for tests, test cases, and test suites are reported to the test 
 ; runner. The `MGutXMLRunner` displays the results in the output XML file.
+;
+; :Private:
 ;-