Changeset 50

Timestamp:

04/09/09 13:19:19 (3 years ago)

Author:

mgalloy

Message:

Fixing up examples and documentation; changed name of Workbench templates.

Location:

trunk/mgunit

Files:

• docs/findgen_ut__define.pro (modified) (4 diffs)
• docs/indgen_uts__define.pro (modified) (2 diffs)
• docs/indgen_ut__define.pro (modified) (4 diffs)
• docs/using-mgunit.txt (modified) (2 diffs)
• Makefile (modified) (2 diffs)
• src/mgunit-templates.xml (added)
• src/test-templates.xml (deleted)

trunk/mgunit/docs/findgen_ut__define.pro

@@ -10 +10 @@
 
 ;+
+; This test should pass the assertion and return 1 (i.e. success). Tests can
+; also return 0 or generate an error to indicate failure.
+;-
+function findgen_ut::test_basic
+  compile_opt strictarr
+  
+  a = findgen(5)
+  assert, array_equal(a, [0.0, 1.0, 2.0, 3.0, 4.0]), 'Correct elements'
+
+  return, 1
+end
+
+
+;+
 ; This test fails because the assertion is wrong. 
 ;-
-function findgen_ut::test1
+function findgen_ut::test_fail_example
   compile_opt strictarr
   
@@ -23 +37 @@
 
 ;+
-; This test should pass the assertion and return 1 (i.e. success). Tests can
-; also return 0 or generate an error to indicate failure.
-;-
-function findgen_ut::test2
-  compile_opt strictarr
-  
-  a = findgen(5)
-  assert, array_equal(a, [0.0, 1.0, 2.0, 3.0, 4.0]), 'Correct elements'
-
-  return, 1
-end
-
-
-;+
 ; This is a test that will pass because the code of the test is supposed to
 ; cause an error. To do this kind of test, use the "error_is_pass" batch file.
 ;-
-function findgen_ut::test3
+function findgen_ut::test_error
   compile_opt strictarr
-  
   @error_is_pass
 
@@ -55 +54 @@
 ; "error_is_fail" batch file. IO errors don't normally cause a test to fail.
 ;-
-function findgen_ut::test4
-  compile_opt strictarr
-  
+function findgen_ut::test_baderror
+  compile_opt strictarr  
   @error_is_fail
 
@@ -72 +70 @@
   compile_opt strictarr
   
-  define = { findgen_ut, inherits MGtestCase }
+  define = { findgen_ut, inherits MGutTestCase }
 end

trunk/mgunit/docs/indgen_uts__define.pro

@@ -4 +4 @@
   compile_opt strictarr
 
-  if (~self->mgtestsuite::init(_extra=e)) then return, 0
+  if (~self->mguttestsuite::init(_extra=e)) then return, 0
 
   ;self->add, ['indgen_ut', 'findgen_ut']
@@ -16 +16 @@
   compile_opt strictarr
   
-  define = { indgen_uts, inherits MGtestSuite }
+  define = { indgen_uts, inherits MGutTestSuite }
 end

trunk/mgunit/docs/indgen_ut__define.pro

@@ -10 +10 @@
 
 ;+
+; This test should pass the assertion and return 1 (i.e. success). Tests can
+; also return 0 or generate an error to indicate failure.
+;-
+function indgen_ut::test_basic
+  compile_opt strictarr
+  
+  a = indgen(5)
+  assert, array_equal(a, [0.0, 1.0, 2.0, 3.0, 4.0]), 'Correct elements'
+
+  return, 1
+end
+
+
+;+
 ; This test fails because the assertion is wrong. 
 ;-
-function indgen_ut::test1
+function indgen_ut::test_fail_example
   compile_opt strictarr
   
@@ -23 +37 @@
 
 ;+
-; This test should pass the assertion and return 1 (i.e. success). Tests can
-; also return 0 or generate an error to indicate failure.
-;-
-function indgen_ut::test2
-  compile_opt strictarr
-  
-  a = indgen(5)
-  assert, array_equal(a, [0.0, 1.0, 2.0, 3.0, 4.0]), 'Correct elements'
-
-  return, 1
-end
-
-
-;+
 ; This is a test that will pass because the code of the test is supposed to
 ; cause an error. To do this kind of test, use the "error_is_pass" batch file.
 ;-
-function indgen_ut::test3
+function indgen_ut::test_error
   compile_opt strictarr
-  
   @error_is_pass
 
@@ -55 +54 @@
 ; "error_is_fail" batch file. IO errors don't normally cause a test to fail.
 ;-
-function indgen_ut::test4
+function indgen_ut::test_baderror
   compile_opt strictarr
+  @error_is_fail
   
-  @error_is_fail
-
   a = indgen('another_string')
 
@@ -72 +70 @@
   compile_opt strictarr
   
-  define = { indgen_ut, inherits MGtestCase }
+  define = { indgen_ut, inherits MGutTestCase }
 end

trunk/mgunit/docs/using-mgunit.txt

@@ -1 @@
-MGunit is a unit testing framework modeled on other unit testing frameworks such as JUnit. The goal is to allow easy creation and reporting of results of tests, but still allow for all needed flexibility. 
+Introduction
+------------
 
-The structure of tests created for this framework is straightforward. Individual tests are methods of an class that subclasses MGtestCase. Each method returns 1 for success or 0 for failure (or throws an error). Each test method's name must start with "test". Test cases may be (but are not required to be) grouped into test suites.
+MGunit is a unit testing framework modeled on other unit testing frameworks such as JUnit. The goal is to allow easy creation and reporting of results of tests, but still allow for all needed flexibility. 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.
 
-The examples (findgentest, indgentest, and indgensuite) of MGunit discussed are available for download.
 
-To create a test, subclass MGtestCase like::
+Basic use
+---------
 
-  pro findgentest__define
-    define = { findgentest, inherits MGtestCase }
+Individual tests are methods of a class that subclasses MGutTestCase. Each method returns 1 for success or 0 (or throws an error) for failure. Each test method's name must start with "test". 
+
+For example, let's create some tests for the FINDGEN function. First, subclass MGutTestCase like below::
+
+  pro findgen_ut__define
+    compile_opt strictarr
+    
+    define = { findgen_ut, inherits MGutTestCase }
   end
 
-A test is just a method whose name starts with "test". MGunit will find the tests automatically (make sure they are either already compiled or above findgentest__define in the same file). A test case may have as many tests as necessary. For example, a simple test:
-function findgentest::test2
-  a = findgen(5)
-  assert, array_equal(a, [0.0, 1.0, 2.0, 3.0, 4.0]), 'Correct elements'
+A test is just a method of this class whose name starts with "test". The mgunit framework will find the tests automatically. For example, a simple test::
 
-  return, 1
-end
+  function findgen_ut::test_basic
+    compile_opt strictarr
+  
+    a = findgen(5)
+    assert, array_equal(a, [0.0, 1.0, 2.0, 3.0, 4.0]), 'Correct elements'
 
-Return 1 for success. For failure, either return 0 or throw an error. Here the helper routine ASSERT will throw an error using the given message if its condition is not met. This will be reported as a failure along with the message. To run this test, use:
-IDL> mgunit, 'findgentest'
+    return, 1
+  end
+
+Return 1 for success. For failure, either return 0 or throw an error. Here the helper routine ASSERT will throw an error using the given message if its condition is not met. This will be reported as a failure along with the message. To run this test, use the following::
+
+  IDL> mgunit, 'findgen_ut'
+  "All tests" test suite starting (1 test suite/case, 1 tests)
+     "findgen_ut" test case starting (4 tests)
+        test_basic: passed
+     Results: 1 / 1 tests passed
+  Results: 1 / 1 tests passed
+
+A test case may have as many individual tests (methods with names starting with "test") as necessary. 
+
+One tricky situation is that sometimes invalid input must be tested to make sure the routine fails. In these situations, throwing an error should indicate the success of the test, not a failure. In this case use the provided batch file error_is_pass at the beginning of the routine, like::
+
+  function findgen_ut::test_error
+    compile_opt strictarr
+    @error_is_pass
+
+    a = findgen('string')
+
+    return, 0
+  end
+
+As an example of showing a failing test, the example test case includes a test_fail_example method with an invalid assertion. Also provided is an example of using the error_is_fail batch file in the test_baderror method. Runtime errors will cause a test to fail, but IO errors normally will not. The test_baderror test uses @error_is_fail to make an IO error cause the test to fail::
+
+  function findgen_ut::test_baderror
+    compile_opt strictarr  
+    @error_is_fail
+
+    a = findgen('another_string')
+
+    return, 1
+  end
+
+Running all the test case now results in the following::
+
+  IDL> mgunit, 'findgen_ut'
+  "All tests" test suite starting (1 test suite/case, 4 tests)
+     "findgen_ut" test case starting (4 tests)
+        test_basic: passed
+        test_error: passed
+        test_fail_example: failed "Wrong number of elements"
+        test_baderror: failed "Type conversion error: Unable to convert given STRING to Long64."
+     Results: 2 / 4 tests passed
+  Results: 2 / 4 tests passed
+
+Both test failures above are expected and present only to demonstrate features of mgunit.
+
+
+Running multiple test cases
+---------------------------
+
+Another test case, indgen_ut, is provided as an example. It is analogous to findgen_ut for the INDGEN routine.
+
+Multiple test cases can be executed by specifying them as an array::
+
+  IDL> mgunit, ['findgen_ut', 'indgen_ut']
+  "All tests" test suite starting (2 test suites/cases, 10 tests)
+     "findgen_ut" test case starting (5 tests)
+        test_baderror: failed "Type conversion error: Unable to convert given STRING to Long64."
+        test_basic: passed
+        test_error: passed
+        test_fail_example: failed "Wrong number of elements"
+        test_incorrecterror: failed "Type conversion error: Unable to convert given STRING to Long64."
+     Results: 2 / 5 tests passed
+     "indgen_ut" test case starting (5 tests)
+        test4: failed "Type conversion error: Unable to convert given STRING to Long64."
+        test_baderror: failed "Type conversion error: Unable to convert given STRING to Long64."
+        test_basic: passed
+        test_error: passed
+        test_fail_example: failed "Wrong number of elements"
+     Results: 2 / 5 tests passed
+  Results: 4 / 10 tests passed
+
+Alternatively, test cases may be grouped into test suites. Test suites are  just collections of test cases. To make a suite, subclass MGutTestSuite and use the add method in the the subclass' init method to add test classes. For example, to make a suite containing the indgen_ut and findgen_ut test cases::
+
+  function indgen_uts::init, _extra=e
+    compile_opt strictarr
+
+    if (~self->mguttestsuite::init(_extra=e)) then return, 0
+
+    ;self->add, ['indgen_ut', 'findgen_ut']
+    self->add, /all
+  
+    return, 1
+  end
+
+  pro indgen_uts__define
+    compile_opt strictarr
+  
+    define = { indgen_uts, inherits MGutTestSuite }
+  end
+
+The commented out line will specifically add indgen_ut and findgen_ut, wherever their source code files may be located. Instead, the ALL keyword is used to add all test cases in the same directory as the test suite source code file. Test cases to be found in this manner must use the convention to name the class with an appended "_ut", as in "findgen_ut".
+
+mgunit will also accept a mixed array of test suites and test cases, as in::
+
+  IDL> mgunit, ['findgen_ut', 'indgen_ut', 'indgen_uts']
+
+In our case, this does not make sense because this will execute the same tests twice.
+
+
+Fixtures
+--------
+
+Setup/teardown.
+
+Common checks i.e. memory leaks
+
+
+Other output
+------------
+
+Compound, log, HTML
 
 Results can be sent to a log file with the LOG_FILE:
@@ -34 +155 @@
       Results: 2 / 4 tests passed
    Results: 2 / 4 tests passed
+   
 
-One tricky situation is that sometimes invalid input must be tested to make sure the routine fails. In this case, throwing an error should indicate a success of the test, not a failure. In this case use the provided batch file error_is_pass at the beginning of the routine, like:
-function findgentest::test3
-  @error_is_pass
+Miscellaneous
+-------------
 
-  a = findgen('string')
+Templates for the IDL Workbench are provided to make test/suite creation even faster. To use them, first navigate to the Workbench preferences. There should be a Templates section under the IDL heading. Click the "Import" button on the right and navigate to the "test-templates.xml" file in the mgunit source. Two new templates, "Test case" and "Test suite", should now be available. Typing "testcase" into a new file and then selecting Edit > Content Assist from the menus will create a test case which can be filled out like a form. Suites can be created the same way by typing "testsuite".
 
-  return, 1
-end
 
-Multiple test cases can be specified as an array
-IDL> mgunit, ['findgentest', 'indgentest']
+Tips
+----
 
-or by creating a test suite. Test suites are very simple; they are just collections of test cases. To make a suite, subclass MGtestSuite and use the add method to add test classes. For example,
-function indgensuite::init, _extra=e
-  compile_opt strictarr
+Subclass a subclass of MGutTestCase.
 
-  if (~self->mgtestsuite::init(_extra=e)) then return, 0
-
-  self->add, ['indgentest', 'findgentest']
-
-  return, 1
-end
-
-pro indgensuite__define
-  define = { indgensuite, inherits MGtestSuite }
-end
-
-This test suite is available for download (source / docs). mgunit can run test suites also,
-IDL> mgunit, 'indgensuite'
-
-mgunit will also accept a mixed array of test suites and test cases.

trunk/mgunit/Makefile

@@ -33 +33 @@
         cp src/error_is_pass.pro mgunit-$(RELEASE)/
         cp src/style.css mgunit-$(RELEASE)/
-        cp src/test-templates.xml mgunit-$(RELEASE)/
+        cp src/mgunit-templates.xml mgunit-$(RELEASE)/
         cp COPYING mgunit-$(RELEASE)/
         cp RELEASE mgunit-$(RELEASE)/   
@@ -54 +54 @@
         cp src/dist_tools/mg_src_root.pro mgunit-src-$(RELEASE)/
         cp src/cmdline_tools/mg_ansicode.pro mgunit-src-$(RELEASE)/
-        cp src/test-templates.xml mgunit-src-$(RELEASE)/
+        cp src/mgunit-templates.xml mgunit-src-$(RELEASE)/
         cp COPYING mgunit-src-$(RELEASE)/
         cp RELEASE mgunit-src-$(RELEASE)/