A template for the test files with a lot of comments/explanations

test/test_file_template

@@ -0,0 +1,124 @@
+!! ------------------------------------------------------------------------------------
+!! Create a test_<location> for every location you want to test. If the location is too 
+!! long, there are a lot of tests, break it up into several test_<location>_<description> 
+!! files. The <description> should be something meaningful, not just 1, 2 or 3.
+!! It should be something like test_NPCChat_HatesPlayer, test_NPCChat_SecondQuestChat or 
+!! something similar to give an idea to people of what is in the file.
+   
+!! IMPORTANT: 
+!! 1. Do not remove the @.... tags.
+!! 2. Add a value to all the CAPITALISED variables 
+!!   a. $FUNCTIONNAME can take an empty string in some cases.
+!!   b. $ARGUMENTS can also be empty if no arguments are passed in the call
+!! 4. ACTUAL and EXPECTED can be String or Number depending on what you test. 
+!!    Both are Strings ($) by default because that is safer. $ACTUAL = 2 will work,
+!!    ACTUAL = 'something' will throw an error.
+!! 3. Set up the necessary variables that the tested code will check.
+!! 4. The 'testframework', 'testsetup' sets up a lot of things dates, PC attributes, etc. 
+!! 5. Do not forget to clean up the variables you set: put that code after 
+!!    the 'testframework', 'cleanUpDefault' call
+!! 6. Do not be afraid to ask, I am happy to help.
+!!    Either on the discord or on https://git.tfgames.site/netuttki/qsp_unit_test_proof_of_concept/issues
+
+!! ------------------------------------------------------------------------------------
+!! $LOCATIONNAME = the tested location with the test_ prefix.
+!! E.g.: test_korrPar, test_internet_mobile, test_prostitution_functions, etc.
+!! ------------------------------------------------------------------------------------
+!! @locationsetup
+   
+_ISTEST = 1
+$LOCATIONNAME = ''
+   
+!! ------------------------------------------------------------------------------------
+!! Run the tests - add the calls to the tests for the location that have to be run.
+!! ------------------------------------------------------------------------------------
+  
+!! List the tests defined below, i.e. the $ARGS[0] value. The @run tag tells the framework
+!! that the test has to be executed.
+
+!! @run test_1  <- this test will run.  'test_1', "test_1" and test_1 are all valid
+!! test_2 <- this test will not run
+   
+!! ------------------------------------------------------------------------------------
+!! The actual test. For each ($)ARGS[0] you want to test write a separate one, ideally 
+!! testing only one thing at a time - the value of one variable.
+!! Never test more than one ($)ARGS[0] values in one test. 
+!! Even if 'location, 'event2' follow 'location', 'event2' immediately in the game do not do this:
+!! 	gs 'location', 'event1'
+!!	gs 'location', 'event2
+!! 
+!! If the result of 'event2' turns out to be incorrect you will not know whether the problem is in
+!! 'event1' or in 'event2'.
+!! ------------------------------------------------------------------------------------
+!! @tests
+   
+!! Test Function Template
+!! Comment if needed about the test
+if $ARGS[0] = '':
+    !! $TESTNAME: 'A relatively short but descriptive name for the test explaining what is tested.'
+    !! For example "If mainQuest['stage'] = 2 the Archenemy should be Kevin"
+    $TESTNAME = ''
+    !! $FUNCTIONNAME: The value of $ARGS[0] 
+    !! For example 'setArchenemy'             
+    $FUNCTIONNAME = ''
+
+    !! Checks if the $LOCATIONNAME, $FUNCTIONNAME pair is valid.
+    if _ISVALIDCALL['<<$LOCATIONNAME>>,<<$FUNCTIONNAME>>'] ! 0:
+        !! Setup
+        gs 'testframework', 'testsetup'
+ 
+        !! Under setup the test has to assign the values to every variable that is used by the tested code.
+        !! For example:
+        !! mainQuest['stage'] = 2
+
+        !! $EXPECTED = or EXPECTED = is the value that the test is expecting after the test runs. 
+        !! For example:
+        !! $EXPECTED = 'Kevin' 
+        !! $EXPECTED_MESSAGE = "$nameOfArchenemy = <<$EXPECTED>>"
+        $EXPECTED = ''
+        $EXPECTED_MESSAGE = ""
+        
+        !! Add the argument values if any as a string.
+        !! For example $ARGUMENTS = "'archenemy', 1" - Right now $ARGUMENTS is used only to display the arguments 
+        !! in the test result reports.
+        $ARGUMENTS = ''
+
+        !! Add the same arguments after the $FUNCTIONNAME
+        gs $LOCATIONNAME, $FUNCTIONNAME
+        *clr & cla 
+        !! The variable in the tested code that we are checking here. 
+        !! For example $nameofArchenemy.
+        !! $ACTUAL = $nameOfArchenemy
+        !! $ACTUAL_MESSAGE = "$nameOfArchenemy = '<<$ACTUAL>>'"
+        $ACTUAL
+        $ACTUAL_MESSAGE = ""
+  
+        !! Assertion of the outcome. 
+        !! Compare the EXPECTED and ACTUAL values - adding some functions later for more complicated assertions,
+        !! like comparing arrays and whatever comes up.
+        TESTRESULT = $EXPECTED = $ACTUAL
+  
+    else:
+        !! If the $LOCATIONNAME - $FUNCTIONNAME pair is an invalid call then the $ACTUAL_MESSAGE is set to convey this message.
+        $ACTUAL_MESSAGE = '<<$LOCATIONNAME>> <<$FUNCTIONNAME>> does not exist.'
+    end
+  
+    !! ------------------------------------------------------------------------------------
+    !! Add testresult to the reports.
+    !! ------------------------------------------------------------------------------------
+  
+    gs 'testframework', 'addTestResult'
+   
+    !! ------------------------------------------------------------------------------------
+    !! Clean up the variables for the next test.
+    !! ------------------------------------------------------------------------------------
+   
+    gs 'testframework', 'testCleanUpDefault'
+    !! add cleanup for any variables that you used for the test.
+    !! For example:
+    !! killvar 'mainQuest'
+    !! killvar 'nameOfArchenemy'
+end
+  
+killvar 'LOCATIONNAME'
+killvar '_ISTEST'