0031575: Tests - make location of source test folder available in test

Documentation of global variables available for the test script during test execution is improved.

Off-topic: mark-up error is fixed in DRAW user guide

dox/contribution/tests/tests.md

@@ -555,7 +555,31 @@ if { [expr $actual_length - $expected_length] > 0.001 } {
 
 At the end, the test script should output *TEST COMPLETED* string to mark a successful completion of the script. This is often done by the *end* script in the grid.
 
-When the test script requires a data file, use Tcl procedure *locate_data_file* to get a path to it, instead of putting the path explicitly. This will allow easy move of the data file from OCCT sources repository to the data files repository without the need to update the test script.
+During execution of a test, the following Tcl variables are defined on global level:
+
+| Variable  | Value |
+|-----------|-------|
+| dirname   | Path to the root directory of the current set of test scripts |
+| groupname | Name of the test group (subfolder of $dirname) |
+| gridname  | Name of the test grid (subfolder of $dirname/$gridname) |
+| casename  | Name of the test |
+| imagedir  | Path to folder where test log and other artifacts are saved |
+
+The test script can use some data stored in a separate file (e.g. reference results of the test execution).
+Such file can be put in subfolder *data* of the test grid directory.
+During execution of the test, location of such data file can be constructed using the variables listed above.
+
+Example:
+
+~~~~~
+checkresult $result $::dirname/$::groupname/$::gridname/data/${::casename}.txt
+~~~~~
+
+CAD models and other data files which are not going to change over time should be stored separately from the source repository.
+Use Tcl procedure *locate_data_file* to get a path to such data files, instead of coding the path explicitly. 
+For the file to be found by that procedure, add directory that contains it into the environment variable *CSF_TestDataPath* (list of paths separated by semicolons on Windows or colons on other platforms).
+The search is recursive, thus adding only root folder of a directory containing data files is sufficient.
+If the file is not found, *locate_data_file* will raise exception, and the test will be reported as SKIPPED.
 
 Example:
 
@@ -578,11 +602,11 @@ The image format (defined by extension) should be *png*.
 
 Example:
 ~~~~~
-xwd $imagedir/${casename}.png
+xwd $::imagedir/${::casename}.png
 vdisplay result; vfit
-vdump $imagedir/${casename}-axo.png
+vdump $::imagedir/${::casename}-axo.png
 vfront; vfit
-vdump $imagedir/${casename}-front.png
+vdump $::imagedir/${::casename}-front.png
 ~~~~~
 
 would produce:
@@ -594,11 +618,6 @@ A1-front.png
 
 Note that OCCT must be built with FreeImage support to be able to produce usable images.
 
-Other Tcl variables defined during the test execution are:
-- *groupname*: name of the test group;
-- *gridname*: name of the test grid;
-- *dirname*: path to the root directory of the current set of test scripts.
-
 In order to ensure that the test works as expected in different environments, observe the following additional rules:
 * Avoid using external commands such as *grep, rm,* etc., as these commands can be absent on another system (e.g. on Windows); use facilities provided by Tcl instead.
 * Do not put call to *locate_data_file* in catch statement -- this can prevent correct interpretation of the missing data file by the test system.

dox/user_guides/draw_test_harness/draw_test_harness.md

@@ -10989,8 +10989,6 @@ DT_SplitSurface <result> <Surface|GridSurf> <tol> <split(0|1)>
 Divides surface with C1 criterion and returns the result of splitting of a given surface into surface, which is given as parameter result. If the surface has been divided into segments, then each segment is put to an individual result.  This command can correct a given C0 surface at a knot with a given tolerance, if it is impossible, then the given surface is split at that knot. If the last parameter is 1, then 5 knots are added to the given surface, and its surface is split by segments, but this will be performed not for all parametric spaces. 
 
 **Example:** 
-~~~~~
-
 ~~~~~
 # split surface with name "su"
 DT_SplitSurface res su 0.1 1 
@@ -11003,7 +11001,6 @@ DT_SplitSurface res su 0.1 1
 ==> transfert resultat 
 ==> res1_1_1 res1_2_1 res1_3_1 res1_4_1 res1_5_1 res1_6_1 
 ~~~~~
-~~~~~
 
 @subsubsection occt_draw_9_2_8 DT_ToBspl
 

tests/demo/testsystem/contextvars

@@ -0,0 +1,30 @@
+puts "# Check presence and consistency of global variables that define context for the test"
+
+puts ""
+puts "dirname = $::dirname"
+puts "groupname = $::groupname"
+puts "gridname = $::gridname"
+puts "casename = $::casename"
+puts "imagedir = $::imagedir"
+puts ""
+
+puts "# 1. Check that variables dirname, groupname, gridname, casename are defined correctly"
+
+set path_var $::dirname/$::groupname/$::gridname/$casename
+set path_act [info script]
+if { [file normalize $path_var] != [file normalize $path_act] } {
+    puts "Error: path to this script ($path_act) is not recovered correctly ($path_var)"
+}
+
+puts "# 2. Check that path to data file is correctly recovered"
+set path_data $::dirname/$::groupname/$::gridname/tests_data/file4.empty
+if { ! [file exists $path_data] } {
+    puts "Error: cannot find data file at expected location ($path_data)"
+}
+
+puts "# 3. Check that directory indicated by imagedir is writable"
+if { ! [file isdirectory $::imagedir] || ! [file writable $::imagedir] } {
+    puts "Error: imagedir variable ($::imagedir) does not point to writable directory"
+}
+
+puts "TEST COMPLETED"

tests/demo/testsystem/testfile

@@ -49,4 +49,4 @@ puts "REQUIRED ALL: Warning: shape contains triangulation"
 
 testfile [list ${imagedir}/bottle.brep ${imagedir}/_hammer_copy.igs ${imagedir}/_square.brep]
 
-puts "TEST COMPLETED"
+puts "TEST COMPLETED"