t.rexx expanded a lot

README.md

@@ -4,11 +4,11 @@ Unit testing framework for Rexx.
 
 The test framework comprises three files: t1, t2, and t3. Each contains a piece of the test framework. The code works by concatenating thesse files with a test script and with the Rexx file to be tested, resulting in a single Rexx program. The order of concatenation is:
 
-1. t1 -> variables used by the test framework
+1. t1.rexx -> variables used by the test framework
 1. the file containing the test script
-1. t2 -> boilerplate code that displays the results of the tests
+1. t2.rexx -> boilerplate code that displays the results of the tests
 1. the file containing the code to be tested
-1. t3 -> test framework functions
+1. t3.rexx -> test framework functions
 
 ## Running tests with bash
 
@@ -25,6 +25,36 @@ The batch file ```runt.bat``` performs the concatenation and executes the result
 ```shell
 runt calc-check calc
 ```
+## Writing your own test
+There are four rexx functions to call in your test script:
+* context()
+* globalmock()
+* localmock()
+* check()
+
+Syntax:                                                                    
+  * context('descripttion') is the test suite description                      
+  * check() is the check procedure to check returncodes from a function or variables set/changed in a procedure.
+    - input to check()   
+      - arg1: Description of the test  
+      - arg2: procedure call incl. arguments
+      - arg3: variable name to check if any
+      - arg4: operand like =, <>, >, <, >= or <=
+      - arg5: expected value
+  * localmock() is the function to call if you want to mock a call and replace it with some other rexx code. Localmock() is reset by the following call to check() and a following call to globalmock()
+  * globalmock() is the function to call if you want to mock a call and replace it with some other rexx code. Globalmock() is in effect for the rest of the test suite.
+    - input to localmock() and to globalmock()
+      - arg1: Name of procedure to mock
+      - arg2: Rexx code to replace the procedure call with. Lines must be seperated by ;
+  - note: globalmock() resets any localmock() so always use globalmock() before localmock()
+  - limitation: the same procedure call cannot first be mocked by globalmock() and then later be remocked by a localmock() - unpredicted result will occure.
+  * Samples:
+```shell  
+globalmock('sayCalcResultWithReturn', "say 'call to sayCalcResultWithReturn mocked #1'; say 'call to sayCalcResultWithReturn mocked #2';")
+localmock('sayCalcResult', "say 'call to sayCalcResult mocked #1'; say 'call to sayCalcResult mocked #2'; say 'call to sayCalcResult mocked #3';")
+check( 'Adding 5 and 2', "calc(5,  '+', 2)",, 'to be', 7)
+check( 'Dividing 15 by 3 = 5', "calcWithoutAnyReturn 15, '/', 3", 'calcResult', '=', 5)
+```
 
 ## Running tests with JCL
 
@@ -50,4 +80,20 @@ On a zOS system, concatenate the files and run the resulting Rexx program using
 //SYSTSIN   DD DUMMY
 // 
 ```
-
+
+## Change history
+* 0.0.1 initial version by Dave Nicolette
+* 0.0.2 (not tested on z/OS nor Windows)
+  - Variable initialization moved to init-procedure in t3.rexx
+  - t1, t2 and t3 renamed to .rexx to trigger indent, coloring etc in VScode
+  - check() function expanded to handle both calls to functions and procedures
+  - check() function expanded to compare named varables instead of only return values
+  - check() function expanded also to handle =, <, >, <>, ^= >= and <=
+  - call to expect() funktion moved from test script to check() function in t3.rexx
+  - a lot more samples added.
+* 0.0.3 (not tested on z/OS nor Windows)
+  - mock() function added
+* 0.0.4 (not tested on z/OS nor Windows)
+  - mock() function renamed to localmock()
+  - globalmock() added
+  - result from program with mocks collected and printed at the end of the run

calc-check.rexx

@@ -1,8 +1,69 @@
-/* test script to demonstrate the rexx unit test framework */
-
-context('Checking the calc function')
-check( 'Adding 3 and 4',        expect( calc( 3,  '+', 4 ),  'to be',      6  ))
-check( 'Adding 5 and 2',        expect( calc( 5,  '+', 2 ),  'to be',      7  ))
-check( 'Subtracting 3 from 10', expect( calc( 10, '-', 3 ),  'to be',      7  ))
-check( 'Multiplying 15 and 2',  expect( calc( 15, '*', 2 ),  'to be',     31  ))
-check( 'Dividing 3 into 15',    expect( calc( 15, '/', 3 ),  'not to be', 13  ))
+/*******************************************************************************
+ * test script to demonstrate the rexx unit test framework                    
+ * Syntax:                                                                    
+ *   context('descripttion') is the test suite description                      
+ *
+ *   mock() is used to mock out a call to another procedure and insert some
+ *   replacement code.
+ *   - mock() is only valid for 1 (one) check
+ *   - no global mock() is implementated yet.
+ *
+ *   check() is the check procedure to check returncodes from a function or 
+ *   variables set or changed in a pr   ocedure.
+ *   input to check()   
+ *      arg1: Description of the test  
+ *      arg2: procedure call incl. argum   ents
+ *      arg3: variable name to check if    any
+ *      arg4: operand like =, <>, >, <, >= or <=
+ *      arg5: expected value
+ ******************************************************************************/
+
+context('Checking',
+        'the calc function and',
+        'calcWithoutAnyReturn proedure')
+
+check( 'Check if variable "op" is set to "to be"', 'calc(3, "+", 4)', 'op', 'to be', 'to be'  )
+check( 'Check if variable "op" is set to "="', 'calc(3, "+", 4)', 'op', '=', '='  )
+check( 'Adding 5 and 2', 'calc(5,  "+", 2)',, 'to be', 7)
+check( 'Subtracting 3 from 10', 'calc(10, "-", 3)',, 'to be', 7)
+check( 'Multiplying 15 and 2 - must fail',  'calc(15, "*", 2)',, 'to be', 31)
+check( 'Dividing 3 into 15 not to be 13', 'calc(15, "/", 3)',, 'not to be', 13)
+check( 'Dividing 3 into 15 ^= 13', 'calc(15, "/", 3)',, '^=', 13)
+check( 'Dividing 3 into 15 <> 13', 'calc(15, "/", 3)',, '<>', 13)
+check( 'Dividing 3 into 15 not to be 5 - must fail', 'calc(15, "/", 3)',, 'not to be', 5)
+check( 'Dividing 3 into 15 ^= 5 - must fail', 'calc(15, "/", 3)',, '^=', 5)
+
+globalmock('sayCalcResult2', "say 'call to sayCalcResult2 globalMocked'")
+
+check( 'Dividing 3 into 15 <> 5 - must fail',, 
+       'calc(15, "/", 3)',,
+       ,, 
+       '<>',, 
+       5)
+check( 'Dividing 15 by 3 > 4', 'calc(15, "/", 3)',, '>', 4)
+check( 'Dividing 15 by 3 >= 4', 'calc(15, "/", 3)',, '>=', 4)
+check( 'Dividing 15 by 3 >= 5', 'calc(15, "/", 3)',, '>=', 5)
+check( 'Dividing 15 by 3 < 6', 'calc(15, "/", 3)',, '<', 6)
+check( 'Dividing 15 by 3 <= 6', 'calc(15, "/", 3)',, '<=', 6)
+check( 'Dividing 15 by 3 <= 5', 'calc(15, "/", 3)',, '<=', 5)
+check( 'Dividing 15 by 3 > 6 - must fail', 'calc(15, "/", 3)',, '>', 6)
+check( 'Dividing 15 by 3 >= 6 - must fail', 'calc(15, "/", 3)',, '>=', 6)
+check( 'Dividing 15 by 3 < 6 - must fail', 'calc(15, "/", 3)',, '<', 5)
+
+localmock('sayCalcResultWithReturn', "say 'call to sayCalcResultWithReturn mocked #1'")
+localmock('sayCalcResult', "say 'call to sayCalcResult mocked #1'")
+check( 'Dividing 15 by 3 <= 6 - must fail', 'calcWithoutAnyReturn 15, "/", 3','calcResult', '<=', 4)
+
+localmock('sayCalcResult', "say 'call to sayCalcResult mocked #1'")
+check( 'Dividing 15 by 3 = 5', 'calcWithoutAnyReturn 15, "/", 3', 'calcResult', '=', 5)
+
+localmock('sayCalcResult', "say 'call to sayCalcResult mocked #1'; say 'call to sayCalcResult mocked #2';")
+check( 'Dividing 15 by 3 >= 4', 'calcWithoutAnyReturn 15, "/", 3', 'calcResult', '>=', 4)
+
+localmock('sayCalcResult', "say 'call to sayCalcResult mocked #1'; say 'call to sayCalcResult mocked #2'; say 'call to sayCalcResult mocked #3';")
+check( 'Dividing 15 by 3 != 4',, 
+       'calcWithoutAnyReturn 15, "/", 3',, 
+       'calcResult',,
+       '>=',, 
+       4)
+

calc.rexx

@@ -1,8 +1,44 @@
 /* a rexx application to demonstrate the unit test framework */
 
 calc:
-parse arg val1, op, val2
-if op == '+' then return val1 + val2
-if op == '-' then return val1 - val2
-if op == '*' then return val1 * val2
-if op == '/' then return val1 / val2
+  parse arg val1, op, val2
+  if op == '+' then 
+    calcResult = val1 + val2
+  if op == '-' then 
+    calcResult = val1 - val2
+  if op == '*' then 
+    calcResult = val1 * val2
+  if op == '/' then 
+    calcResult = val1 / val2
+  call sayCalcResult2 calcResult
+return calcResult
+
+calcWithoutAnyReturn:
+  parse arg val1, op, val2
+  if op == '+' then 
+    calcResult = val1 + val2
+  if op == '-' then 
+    calcResult = val1 - val2
+  if op == '*' then 
+    calcResult = val1 * val2
+  if op == '/' then 
+    calcResult = val1 / val2
+  call sayCalcResult calcResult
+  rc = sayCalcResultWithReturn(calcResult)
+return
+
+sayCalcResult: procedure
+  arg lineToPrint
+  say 'sayCalcResult printing:' lineToPrint
+return
+
+sayCalcResult2: procedure
+  arg lineToPrint
+  say 'sayCalcResult2 printing:' lineToPrint
+return
+
+sayCalcResultWithReturn: procedure
+  arg lineToPrint
+  say 'sayCalcResultWithReturn printing:' lineToPrint
+return 8
+

runt

@@ -6,7 +6,7 @@
 # $2 -> the application to test (rexx)
 #
 # This script concatenates the files:
-# t1 + $1 + t2 + $2 + t3
+# t1.rexx + $1 + t2.rexx + $2 + t3.rexx
 #
 # and executes the resulting file.
 #
@@ -15,5 +15,5 @@
 # 03 Apr 2015
 #----------------------------------------------------------------------------
 
-cat t1 "${1}.rexx" t2 "${2}.rexx" t3 > t.rexx
+cat t1.rexx "${1}.rexx" t2.rexx "${2}.rexx" t3.rexx > t.rexx
 rexx t.rexx

runt.bat

@@ -6,7 +6,7 @@ rem %1 -> the test script (rexx)
 rem %2 -> the application to test (rexx)
 rem
 rem This script concatenates the files:
-rem t1 + $1 + t2 + $2 + t3
+rem t1.rexx + $1 + t2.rexx + $2 + t3.rexx
 rem
 rem and executes the resulting file.
 rem
@@ -15,5 +15,5 @@ rem Version 0.0.1
 rem 03 Apr 2015
 rem ----------------------------------------------------------------------------
 
-type t1 %1.rexx t2 %2.rexx t3 > t.rexx
+type t1.rexx %1.rexx t2.rexx %2.rexx t3.rexx > t.rexx
 rexx t.rexx

t1.rexx

@@ -0,0 +1,11 @@
+/* rexx unit test framework
+   concatenate these files:
+   t1.rexx test-script t2.rexx rexx-file-to-test t3.rexx > t.rexx
+   then execute t.rexx
+   this file is t1.rexx
+*/
+
+call init(arg(1))
+
+/* Test script below *********************************************************/
+

t2.rexx

@@ -0,0 +1,32 @@
+/* rexx unit test framework
+   concatenate these files:
+   t1.rexx test-script t2.rexx rexx-file-to-test t3.rexx > t.rexx
+   then execute t.rexx
+   this file is t2.rexx
+*/
+
+/* display the test results */
+
+if areWeMocking then
+  return assertion
+else do
+  say divider
+  say contextdesc
+  say spacer
+
+  do i = 1 to checkresult.0
+    say checkresult.i
+  end    
+
+  say spacer
+
+  text = counts()
+  do i = 1 to text.0
+    say text.i
+  end
+
+  say divider
+
+  exit
+end
+