0029083: Samples - specify multiple Make jobs within make.sh for Qt sample
[occt.git] / dox / dev_guides / tests / tests.md
CommitLineData
ba06f8bb 1 Automated Testing System {#occt_dev_guides__tests}
72b7576f 2======================================
3
e5bd0d98 4@tableofcontents
5
dcc0a33e 6@section testmanual_intro Introduction
72b7576f 7
504a8968 8This document provides OCCT developers and contributors with an overview and practical guidelines for work with OCCT automatic testing system.
9
6d368502 10Reading the Introduction should be sufficient for developers to use the test system to control non-regression of the modifications they implement in OCCT. Other sections provide a more in-depth description of the test system, required for modifying the tests and adding new test cases.
72b7576f 11
dcc0a33e 12@subsection testmanual_intro_basic Basic Information
72b7576f 13
9d99d3c1 14OCCT automatic testing system is organized around @ref occt_user_guides__test_harness "DRAW Test Harness", a console application based on Tcl (a scripting language) interpreter extended by OCCT-related commands.
e5bd0d98 15
504a8968 16Standard OCCT tests are included with OCCT sources and are located in subdirectory *tests* of the OCCT root folder. Other test folders can be included in the test system, e.g. for testing applications based on OCCT.
e5bd0d98 17
504a8968 18The tests are organized in three levels:
72b7576f 19
504a8968 20 * Group: a group of related test grids, usually testing a particular OCCT functionality (e.g. blend);
21 * Grid: a set of test cases within a group, usually aimed at testing some particular aspect or mode of execution of the relevant functionality (e.g. buildevol);
22 * Test case: a script implementing an individual test (e.g. K4).
23
67d7f07f 24See @ref testmanual_5_1 "Test Groups" chapter for the current list of available test groups and grids.
72b7576f 25
d3013f55 26@note Many tests involve data files (typically CAD models) which are located separately and (except a few) are not included with OCCT code.
27These tests will be skipped if data files are not available.
72b7576f 28
29@subsection testmanual_1_2 Intended Use of Automatic Tests
30
31Each modification made in OCCT code must be checked for non-regression
6d368502 32by running the whole set of tests. The developer who makes the modification
504a8968 33is responsible for running and ensuring non-regression for the tests available to him.
34
6d368502 35Note that many tests are based on data files that are confidential and thus available only at OPEN CASCADE.
36The official certification testing of each change before its integration to master branch of official OCCT Git repository (and finally to the official release) is performed by OPEN CASCADE to ensure non-regression on all existing test cases and supported platforms.
504a8968 37
38Each new non-trivial modification (improvement, bug fix, new feature) in OCCT should be accompanied by a relevant test case suitable for verifying that modification. This test case is to be added by the developer who provides the modification.
72b7576f 39
504a8968 40If a modification affects the result of an existing test case, either the modification should be corrected (if it causes regression) or the affected test cases should be updated to account for the modification.
72b7576f 41
504a8968 42The modifications made in the OCCT code and related test scripts should be included in the same integration to the master branch.
72b7576f 43
44@subsection testmanual_1_3 Quick Start
45
46@subsubsection testmanual_1_3_1 Setup
47
504a8968 48Before running tests, make sure to define environment variable *CSF_TestDataPath* pointing to the directory containing test data files.
504a8968 49
50For this it is recommended to add a file *DrawAppliInit* in the directory which is current at the moment of starting DRAWEXE (normally it is OCCT root directory, <i>$CASROOT </i>). This file is evaluated automatically at the DRAW start.
51
52Example (Windows)
72b7576f 53
6d368502 54~~~~~{.tcl}
504a8968 55set env(CSF_TestDataPath) $env(CSF_TestDataPath)\;d:/occt/test-data
6d368502 56~~~~~
504a8968 57
504a8968 58Note that variable *CSF_TestDataPath* is set to default value at DRAW start, pointing at the folder <i>$CASROOT/data</i>.
87f42a3f 59In this example, subdirectory <i>d:/occt/test-data</i> is added to this path. Similar code could be used on Linux and Mac OS X except that on non-Windows platforms colon ":" should be used as path separator instead of semicolon ";".
72b7576f 60
936f43da 61All tests are run from DRAW command prompt (run *draw.bat* or *draw.sh* to start it).
72b7576f 62
63@subsubsection testmanual_1_3_2 Running Tests
64
504a8968 65To run all tests, type command *testgrid*
72b7576f 66
67Example:
68
504a8968 69~~~~~
70Draw[]> testgrid
71~~~~~
72b7576f 72
ae3eaf7b 73To run only a subset of test cases, give masks for group, grid, and test case names to be executed.
74Each argument is a list of file masks separated with commas or spaces; by default "*" is assumed.
72b7576f 75
504a8968 76Example:
72b7576f 77
504a8968 78~~~~~
87f42a3f 79Draw[]> testgrid bugs caf,moddata*,xde
504a8968 80~~~~~
72b7576f 81
72b7576f 82As the tests progress, the result of each test case is reported.
504a8968 83At the end of the log a summary of test cases is output,
84including the list of detected regressions and improvements, if any.
72b7576f 85
86
504a8968 87Example:
88
72b7576f 89~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
90 Tests summary
91
92 CASE 3rdparty export A1: OK
93 ...
94 CASE pipe standard B1: BAD (known problem)
95 CASE pipe standard C1: OK
96 No regressions
97 Total cases: 208 BAD, 31 SKIPPED, 3 IMPROVEMENT, 1791 OK
98 Elapsed time: 1 Hours 14 Minutes 33.7384512019 Seconds
99 Detailed logs are saved in D:/occt/results_2012-06-04T0919
100~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
101
dcc0a33e 102The tests are considered as non-regressive if only OK, BAD (i.e. known problem), and SKIPPED (i.e. not executed, typically because of lack of a data file) statuses are reported. See @ref testmanual_details_results "Interpretation of test results" for details.
72b7576f 103
936f43da 104The results and detailed logs of the tests are saved by default to a new subdirectory of the subdirectory *results* in the current folder, whose name is generated automatically using the current date and time, prefixed by Git branch name (if Git is available and current sources are managed by Git).
3f812249 105If necessary, a non-default output directory can be specified using option <i> -outdir</i> followed by a path to the directory. This directory should be new or empty; use option <i>-overwrite</i> to allow writing results in the existing non-empty directory.
72b7576f 106
504a8968 107Example:
108~~~~~
87f42a3f 109Draw[]> testgrid -outdir d:/occt/last_results -overwrite
504a8968 110~~~~~
ae3eaf7b 111In the output directory, a cumulative HTML report <i>summary.html</i> provides links to reports on each test case. An additional report in JUnit-style XML format can be output for use in Jenkins or other continuous integration system.
504a8968 112
dcb359e0 113To re-run the test cases, which were detected as regressions on the previous run, option <i>-regress dirname</i> should be used.
114<i>dirname</i> is a path to the directory containing the results of the previous run. Only the test cases with *FAILED* and *IMPROVEMENT* statuses will be tested.
b502ddc1 115
116Example:
117~~~~~
118Draw[]> testgrid -regress d:/occt/last_results
119~~~~~
120
936f43da 121Type <i>help testgrid</i> in DRAW prompt to get help on options supported by *testgrid* command:
72b7576f 122
504a8968 123~~~~~
124Draw[3]> help testgrid
125testgrid: Run all tests, or specified group, or one grid
87f42a3f 126 Use: testgrid [groupmask [gridmask [casemask]]] [options...]
504a8968 127 Allowed options are:
128 -parallel N: run N parallel processes (default is number of CPUs, 0 to disable)
129 -refresh N: save summary logs every N seconds (default 60, minimal 1, 0 to disable)
130 -outdir dirname: set log directory (should be empty or non-existing)
131 -overwrite: force writing logs in existing non-empty directory
132 -xml filename: write XML report for Jenkins (in JUnit-like format)
936f43da 133 -beep: play sound signal at the end of the tests
dcb359e0 134 -regress dirname: re-run only a set of tests that have been detected as regressions on the previous run.
135 Here "dirname" is a path to the directory containing the results of the previous run.
136 Groups, grids, and test cases to be executed can be specified by the list of file
137 masks separated by spaces or commas; default is all (*).
504a8968 138~~~~~
72b7576f 139
504a8968 140@subsubsection testmanual_1_3_3 Running a Single Test
141
87f42a3f 142To run a single test, type command *test* followed by names of group, grid, and test case.
72b7576f 143
144Example:
145
146~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
147 Draw[1]> test blend simple A1
148 CASE blend simple A1: OK
149 Draw[2]>
150~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
151
504a8968 152Note that normally an intermediate output of the script is not shown. The detailed log of the test can be obtained after the test execution by running command <i>"dlog get"</i>.
153
154To see intermediate commands and their output during the test execution, add one more argument
155<i>"echo"</i> at the end of the command line. Note that with this option the log is not collected and summary is not produced.
156
ae3eaf7b 157Type <i>help test</i> in DRAW prompt to get help on options supported by *test* command:
936f43da 158
159~~~~~
160Draw[3]> help test
161test: Run specified test case
162 Use: test group grid casename [options...]
163 Allowed options are:
164 -echo: all commands and results are echoed immediately,
165 but log is not saved and summary is not produced
166 It is also possible to use "1" instead of "-echo"
167 If echo is OFF, log is stored in memory and only summary
168 is output (the log can be obtained with command "dlog get")
169 -outfile filename: set log file (should be non-existing),
170 it is possible to save log file in text file or
171 in html file(with snapshot), for that "filename"
172 should have ".html" extension
173 -overwrite: force writing log in existing file
174 -beep: play sound signal at the end of the test
175 -errors: show all lines from the log report that are recognized as errors
176 This key will be ignored if the "-echo" key is already set.
177~~~~~
178
dcc0a33e 179@subsubsection testmanual_intro_quick_create Creating a New Test
504a8968 180
67d7f07f 181The detailed rules of creation of new tests are given in @ref testmanual_3 "Creation and modification of tests" chapter. The following short description covers the most typical situations:
504a8968 182
6d368502 183Use prefix <i>bug</i> followed by Mantis issue ID and, if necessary, additional suffixes, for naming the test script, data files, and DRAW commands specific for this test case.
504a8968 184
6d368502 1851. If the test requires C++ code, add it as new DRAW command(s) in one of files in *QABugs* package.
67d7f07f 1862. Add script(s) for the test case in the subfolder corresponding to the relevant OCCT module of the group *bugs* <i>($CASROOT/tests/bugs)</i>. See @ref testmanual_5_2 "the correspondence map".
504a8968 1873. In the test script:
188 * Load all necessary DRAW modules by command *pload*.
189 * Use command *locate_data_file* to get a path to data files used by test script. (Make sure to have this command not inside catch statement if it is used.)
251a7984 190 * Use DRAW commands to reproduce the tested situation.
191 * Make sure that in case of failure the test produces a message containing word "Error" or other recognized by the test system as error (add new error patterns in file parse.rules if necessary).
192 * If the test case reports error due to an existing problem and the fix is not available, add @ref testmanual_3_6 "TODO" statement for each error to mark it as a known problem. The TODO statements must be specific so as to match the actually generated messages but not all similar errors.
193 * To check expected output which should be obtained as the test result, add @ref testmanual_3_7 "REQUIRED" statement for each line of output to mark it as required.
194 * If the test case produces error messages (contained in parse.rules), which are expected in that test and should not be considered as its failure (e.g. test for *checkshape* command), add REQUIRED statement for each error to mark it as required output.
1954. If the test uses data file(s) that are not yet present in the test database, it is possible to put them to (sub)directory pointed out by *CSF_TestDataPath* variable for running test. The files should be attached to the Mantis issue corresponding to the tested modification.
1965. Check that the test case runs as expected (test for fix: OK with the fix, FAILED without the fix; test for existing problem: BAD), and integrate it to the Git branch created for the issue.
504a8968 197
198Example:
199
200* Added files:
936f43da 201
504a8968 202~~~~~
3f812249 203git status -short
6d368502 204A tests/bugs/heal/data/bug210_a.brep
205A tests/bugs/heal/data/bug210_b.brep
504a8968 206A tests/bugs/heal/bug210_1
207A tests/bugs/heal/bug210_2
208~~~~~
209
210* Test script
211
6d368502 212~~~~~{.tcl}
504a8968 213puts "OCC210 (case 1): Improve FixShape for touching wires"
214
6d368502 215restore [locate_data_file bug210_a.brep] a
504a8968 216
217fixshape result a 0.01 0.01
218checkshape result
219~~~~~
72b7576f 220
221@section testmanual_2 Organization of Test Scripts
222
223@subsection testmanual_2_1 General Layout
224
225Standard OCCT tests are located in subdirectory tests of the OCCT root folder ($CASROOT).
72b7576f 226
504a8968 227Additional test folders can be added to the test system by defining environment variable *CSF_TestScriptsPath*. This should be list of paths separated by semicolons (*;*) on Windows
6d368502 228or colons (*:*) on Linux or Mac. Upon DRAW launch, path to *tests* subfolder of OCCT is added at the end of this variable automatically.
504a8968 229
230Each test folder is expected to contain:
6d368502 231 * Optional file *parse.rules* defining patterns for interpretation of test results, common for all groups in this folder
72b7576f 232 * One or several test group directories.
233
234Each group directory contains:
235
504a8968 236 * File *grids.list* that identifies this test group and defines list of test grids in it.
237 * Test grids (sub-directories), each containing set of scripts for test cases, and optional files *cases.list*, *parse.rules*, *begin* and *end*.
72b7576f 238 * Optional sub-directory data
72b7576f 239
504a8968 240By convention, names of test groups, grids, and cases should contain no spaces and be lower-case.
241The names *begin, end, data, parse.rules, grids.list* and *cases.list* are reserved.
72b7576f 242
504a8968 243General layout of test scripts is shown in Figure 1.
244
d6b4d3d0 245@figure{/dev_guides/tests/images/tests_image001.png,"Layout of tests folder",400}
72b7576f 246
72b7576f 247
248@subsection testmanual_2_2 Test Groups
249
250@subsubsection testmanual_2_2_1 Group Names
251
504a8968 252The names of directories of test groups containing systematic test grids correspond to the functionality tested by each group.
253
72b7576f 254Example:
255
504a8968 256~~~~~
72b7576f 257 caf
258 mesh
259 offset
504a8968 260~~~~~
72b7576f 261
504a8968 262Test group *bugs* is used to collect the tests coming from bug reports. Group *demo* collects tests of the test system, DRAW, samples, etc.
72b7576f 263
504a8968 264@subsubsection testmanual_2_2_2 File "grids.list"
265
266This test group contains file *grids.list*, which defines an ordered list of grids in this group in the following format:
72b7576f 267
268~~~~~~~~~~~~~~~~~
269001 gridname1
270002 gridname2
271...
272NNN gridnameN
273~~~~~~~~~~~~~~~~~
274
275Example:
276
277~~~~~~~~~~~~~~~~~
278 001 basic
279 002 advanced
280~~~~~~~~~~~~~~~~~
281
504a8968 282@subsubsection testmanual_2_2_3 File "begin"
72b7576f 283
504a8968 284This file is a Tcl script. It is executed before every test in the current group.
72b7576f 285Usually it loads necessary Draw commands, sets common parameters and defines
286additional Tcl functions used in test scripts.
504a8968 287
72b7576f 288Example:
289
290~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
291 pload TOPTEST ;# load topological command
292 set cpulimit 300 ;# set maximum time allowed for script execution
293~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
294
504a8968 295@subsubsection testmanual_2_2_4 File "end"
72b7576f 296
504a8968 297This file is a TCL script. It is executed after every test in the current group. Usually it checks the results of script work, makes a snap-shot of the viewer and writes *TEST COMPLETED* to the output.
72b7576f 298
504a8968 299Note: *TEST COMPLETED* string should be present in the output to indicate that the test is finished without crash.
300
67d7f07f 301See @ref testmanual_3 "Creation and modification of tests" chapter for more information.
504a8968 302
303Example:
304~~~~~
72b7576f 305 if { [isdraw result] } {
306 checkshape result
307 } else {
4ee1bdf4 308 puts "Error: The result shape can not be built"
72b7576f 309 }
4ee1bdf4 310 puts "TEST COMPLETED"
504a8968 311~~~~~
312
313@subsubsection testmanual_2_2_5 File "parse.rules"
314
315The test group may contain *parse.rules* file. This file defines patterns used for analysis of the test execution log and deciding the status of the test run.
316
317Each line in the file should specify a status (single word), followed by a regular expression delimited by slashes (*/*) that will be matched against lines in the test output log to check if it corresponds to this status.
318
251a7984 319The regular expressions should follow <a href="http://www.tcl.tk/man/tcl/TclCmd/re_syntax.htm">Tcl syntax</a>, with a special exception that "\b" is considered as word limit (Perl-style), in addition to "\y" used in Tcl.
504a8968 320
321The rest of the line can contain a comment message, which will be added to the test report when this status is detected.
72b7576f 322
72b7576f 323Example:
324
504a8968 325~~~~~
6d368502 326 FAILED /\b[Ee]xception\b/ exception
327 FAILED /\bError\b/ error
72b7576f 328 SKIPPED /Cannot open file for reading/ data file is missing
329 SKIPPED /Could not read file .*, abandon/ data file is missing
504a8968 330~~~~~
72b7576f 331
332Lines starting with a *#* character and blank lines are ignored to allow comments and spacing.
72b7576f 333
dcc0a33e 334See @ref testmanual_details_results "Interpretation of test results" chapter for details.
504a8968 335
336If a line matches several rules, the first one applies. Rules defined in the grid are checked first, then rules in the group, then rules in the test root directory. This allows defining some rules on the grid level with status *IGNORE* to ignore messages that would otherwise be treated as errors due to the group level rules.
337
72b7576f 338Example:
339
340~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
e5bd0d98 341 FAILED /\\bFaulty\\b/ bad shape
72b7576f 342 IGNORE /^Error [23]d = [\d.-]+/ debug output of blend command
343 IGNORE /^Tcl Exception: tolerance ang : [\d.-]+/ blend failure
344~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
345
504a8968 346@subsubsection testmanual_2_2_6 Directory "data"
67d7f07f 347The test group may contain subdirectory *data*, where test scripts shared by different test grids can be put. See also @ref testmanual_2_3_5 "Directory data".
504a8968 348
72b7576f 349@subsection testmanual_2_3 Test Grids
350
351@subsubsection testmanual_2_3_1 Grid Names
352
504a8968 353The folder of a test group can have several sub-directories (Grid 1… Grid N) defining test grids.
354Each directory contains a set of related test cases. The name of a directory should correspond to its contents.
72b7576f 355
356Example:
357
504a8968 358~~~~~
72b7576f 359caf
360 basic
361 bugs
362 presentation
504a8968 363~~~~~
72b7576f 364
504a8968 365Here *caf* is the name of the test group and *basic*, *bugs*, *presentation*, etc. are the names of grids.
72b7576f 366
504a8968 367@subsubsection testmanual_2_3_2 File "begin"
368
369This file is a TCL script executed before every test in the current grid.
72b7576f 370
72b7576f 371Usually it sets variables specific for the current grid.
504a8968 372
72b7576f 373Example:
374
375~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
376 set command bopfuse ;# command tested in this grid
377~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
378
504a8968 379@subsubsection testmanual_2_3_3 File "end"
380
381This file is a TCL script executed after every test in current grid.
382
383Usually it executes a specific sequence of commands common for all tests in the grid.
72b7576f 384
72b7576f 385Example:
386
387~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
936f43da 388 vdump $imagedir/${casename}.png ;# makes a snap-shot of AIS viewer
72b7576f 389~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
390
504a8968 391@subsubsection testmanual_2_3_4 File "cases.list"
72b7576f 392
393The grid directory can contain an optional file cases.list
504a8968 394defining an alternative location of the test cases.
395This file should contain a single line defining the relative path to the collection of test cases.
72b7576f 396
397Example:
398
504a8968 399~~~~~
72b7576f 400../data/simple
504a8968 401~~~~~
402
403This option is used for creation of several grids of tests with the same data files and operations but performed with differing parameters. The common scripts are usually located place in the common
404subdirectory of the test group, <i>data/simple</i> for example.
72b7576f 405
504a8968 406If file *cases.list* exists, the grid directory should not contain any test cases.
72b7576f 407The specific parameters and pre- and post-processing commands
504a8968 408for test execution in this grid should be defined in the files *begin* and *end*.
409
410
411@subsubsection testmanual_2_3_5 Directory "data"
412
413The test grid may contain subdirectory *data*, containing data files used in tests (BREP, IGES, STEP, etc.) of this grid.
72b7576f 414
415@subsection testmanual_2_4 Test Cases
416
504a8968 417The test case is a TCL script, which performs some operations using DRAW commands
418and produces meaningful messages that can be used to check the validity of the result.
419
72b7576f 420Example:
421
422~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
423 pcylinder c1 10 20 ;# create first cylinder
424 pcylinder c2 5 20 ;# create second cylinder
425 ttranslate c2 5 0 10 ;# translate second cylinder to x,y,z
426 bsection result c1 c2 ;# create a section of two cylinders
427 checksection result ;# will output error message if result is bad
428~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
429
504a8968 430The test case can have any name (except for the reserved names *begin, end, data, cases.list* and *parse.rules*).
72b7576f 431For systematic grids it is usually a capital English letter followed by a number.
432
433Example:
434
504a8968 435~~~~~
72b7576f 436 A1
437 A2
438 B1
439 B2
504a8968 440~~~~~
72b7576f 441
504a8968 442Such naming facilitates compact representation of tests execution results in tabular format within HTML reports.
72b7576f 443
72b7576f 444
445@section testmanual_3 Creation And Modification Of Tests
446
447This section describes how to add new tests and update existing ones.
448
449@subsection testmanual_3_1 Choosing Group, Grid, and Test Case Name
450
504a8968 451The new tests are usually added in the frame of processing issues in OCCT Mantis tracker.
72b7576f 452Such tests in general should be added to group bugs, in the grid
67d7f07f 453corresponding to the affected OCCT functionality. See @ref testmanual_5_2 "Mapping of OCCT functionality to grid names in group bugs".
504a8968 454
455New grids can be added as necessary to contain tests for the functionality not yet covered by existing test grids.
456The test case name in the bugs group should be prefixed by the ID of the corresponding issue in Mantis (without leading zeroes) with prefix *bug*. It is recommended to add a suffix providing a hint on the tested situation. If more than one test is added for a bug, they should be distinguished by suffixes; either meaningful or just ordinal numbers.
72b7576f 457
458Example:
459
460~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~{.tcl}
504a8968 461 bug12345_coaxial
462 bug12345_orthogonal_1
463 bug12345_orthogonal_2
72b7576f 464~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
465
504a8968 466If the new test corresponds to a functionality already covered by the existing systematic test grid (e.g. group *mesh* for *BRepMesh* issues), this test can be added (or moved later by OCC team) to that grid.
72b7576f 467
468@subsection testmanual_3_2 Adding Data Files Required for a Test
469
ae3eaf7b 470It is advisable to make self-contained test scripts whenever possible, so as they could be used in the environments where data files are not available. For that simple geometric objects and shapes can be created using DRAW commands in the test script itself.
504a8968 471
ae3eaf7b 472If the test requires a data file, it should be put to the directory listed in environment variable *CSF_TestDataPath*.
936f43da 473Alternatively, it can be put to subdirectory *data* of the test grid.
474It is recommended to prefix the data file with the corresponding issue id prefixed by *bug*, e.g. *bug12345_face1.brep*, to avoid possible conflicts with names of existing data files.
504a8968 475
ae3eaf7b 476Note that when the test is integrated to the master branch, OCC team will move the data file to the data files repository, to keep OCCT sources repository clean from data files.
504a8968 477
ae3eaf7b 478When you prepare a test script, try to minimize the size of involved data model. For instance, if the problem detected on a big shape can be reproduced on a single face extracted from that shape, use only that face in the test.
504a8968 479
480
481@subsection testmanual_3_3 Adding new DRAW commands
482
483If the test cannot be implemented using available DRAW commands, consider the following possibilities:
484* If the existing DRAW command can be extended to enable possibility required for a test in a natural way (e.g. by adding an option to activate a specific mode of the algorithm), this way is recommended. This change should be appropriately documented in a relevant Mantis issue.
485* If the new command is needed to access OCCT functionality not exposed to DRAW previously, and this command can be potentially reused (for other tests), it should be added to the package where similar commands are implemented (use *getsource* DRAW command to get the package name). The name and arguments of the new command should be chosen to keep similarity with the existing commands. This change should be documented in a relevant Mantis issue.
486* Otherwise the new command implementing the actions needed for this particular test should be added in *QABugs* package. The command name should be formed by the Mantis issue ID prefixed by *bug*, e.g. *bug12345*.
487
488Note that a DRAW command is expected to return 0 in case of a normal completion, and 1 (Tcl exception) if it is incorrectly used (e.g. a wrong number of input arguments). Thus if the new command needs to report a test error, this should be done by outputting an appropriate error message rather than by returning a non-zero value.
ae3eaf7b 489File names must be encoded in the script rather than in the DRAW command and passed to the DRAW command as an argument.
504a8968 490
491@subsection testmanual_3_4 Script Implementation
492
493The test should run commands necessary to perform the tested operations, in general assuming a clean DRAW session. The required DRAW modules should be loaded by *pload* command, if it is not done by *begin* script. The messages produced by commands in a standard output should include identifiable messages on the discovered problems if any.
494
495Usually the script represents a set of commands that a person would run interactively to perform the operation and see its results, with additional comments to explain what happens.
496
72b7576f 497Example:
504a8968 498~~~~~
499# Simple test of fusing box and sphere
500box b 10 10 10
501sphere s 5
502bfuse result b s
503checkshape result
504~~~~~
72b7576f 505
504a8968 506Make sure that file *parse.rules* in the grid or group directory contains a regular expression to catch possible messages indicating the failure of the test.
507
508For instance, for catching errors reported by *checkshape* command relevant grids define a rule to recognize its report by the word *Faulty*:
509
510~~~~~
511FAILED /\bFaulty\b/ bad shape
512~~~~~
513
514For the messages generated in the script it is recommended to use the word 'Error' in the error message.
72b7576f 515
72b7576f 516Example:
517
504a8968 518~~~~~
519set expected_length 11
520if { [expr $actual_length - $expected_length] > 0.001 } {
521 puts "Error: The length of the edge should be $expected_length"
522}
523~~~~~
524
525At 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.
526
527When 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.
72b7576f 528
72b7576f 529Example:
530
504a8968 531~~~~~
532stepread [locate_data_file CAROSKI_COUPELLE.step] a *
533~~~~~
534
936f43da 535When the test needs to produce some snapshots or other artefacts, use Tcl variable *imagedir* as the location where such files should be put.
ae3eaf7b 536* Command *testgrid* sets this variable to the subdirectory of the results folder corresponding to the grid.
537* Command *test* by default creates a dedicated temporary directory in the system temporary folder (normally the one specified by environment variable *TempDir*, *TEMP*, or *TMP*) for each execution, and sets *imagedir* to that location.
538
539However if variable *imagedir* is defined on the top level of Tcl interpretor, command *test* will use it instead of creating a new directory.
936f43da 540
541Use Tcl variable *casename* to prefix all files produced by the test.
542This variable is set to the name of the test case.
ae3eaf7b 543
544The test system can recognize an image file (snapshot) and include it in HTML log and differences if its name starts with the name of the test case (use variable *casename*), optionally followed by underscore or dash and arbitrary suffix.
545
936f43da 546The image format (defined by extension) should be *png*.
72b7576f 547
72b7576f 548Example:
504a8968 549~~~~~
936f43da 550xwd $imagedir/${casename}.png
504a8968 551vdisplay result; vfit
936f43da 552vdump $imagedir/${casename}-axo.png
504a8968 553vfront; vfit
936f43da 554vdump $imagedir/${casename}-front.png
504a8968 555~~~~~
72b7576f 556
504a8968 557would produce:
558~~~~~
559A1.png
560A1-axo.png
561A1-front.png
562~~~~~
72b7576f 563
504a8968 564Note that OCCT must be built with FreeImage support to be able to produce usable images.
72b7576f 565
936f43da 566Other Tcl variables defined during the test execution are:
ae3eaf7b 567- *groupname*: name of the test group;
568- *gridname*: name of the test grid;
569- *dirname*: path to the root directory of the current set of test scripts.
936f43da 570
504a8968 571In order to ensure that the test works as expected in different environments, observe the following additional rules:
572* 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.
3f812249 573* 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.
6d368502 574* Do not use commands *decho* and *dlog* in the test script, to avoid interference with use of these commands by the test system.
72b7576f 575
dcc0a33e 576@subsection testmanual_details_results Interpretation of test results
72b7576f 577
504a8968 578The result of the test is evaluated by checking its output against patterns defined in the files *parse.rules* of the grid and group.
72b7576f 579
504a8968 580The OCCT test system recognizes five statuses of the test execution:
581* SKIPPED: reported if a line matching SKIPPED pattern is found (prior to any FAILED pattern). This indicates that the test cannot be run in the current environment; the most typical case is the absence of the required data file.
6d368502 582* FAILED: reported if a line matching pattern with status FAILED is found (unless it is masked by the preceding IGNORE pattern or a TODO or REQUIRED statement), or if message TEST COMPLETED or at least one of REQUIRED patterns is not found. This indicates that the test has produced a bad or unexpected result, and usually means a regression.
583* BAD: reported if the test script output contains one or several TODO statements and the corresponding number of matching lines in the log. This indicates a known problem. The lines matching TODO statements are not checked against other patterns and thus will not cause a FAILED status.
504a8968 584* IMPROVEMENT: reported if the test script output contains a TODO statement for which no corresponding line is found. This is a possible indication of improvement (a known problem has disappeared).
585* OK: reported if none of the above statuses have been assigned. This means that the test has passed without problems.
72b7576f 586
504a8968 587Other statuses can be specified in *parse.rules* files, these will be classified as FAILED.
72b7576f 588
504a8968 589For integration of the change to OCCT repository, all tests should return either OK or BAD status.
590The new test created for an unsolved problem should return BAD. The new test created for a fixed problem should return FAILED without the fix, and OK with the fix.
72b7576f 591
504a8968 592@subsection testmanual_3_6 Marking BAD cases
72b7576f 593
ae3eaf7b 594If the test produces an invalid result at a certain moment then the corresponding bug should be created in the OCCT issue tracker located at http://tracker.dev.opencascade.org, and the problem should be marked as TODO in the test script.
72b7576f 595
504a8968 596The following statement should be added to such a test script:
597~~~~~
598puts "TODO BugNumber ListOfPlatforms: RegularExpression"
599~~~~~
600
601Here:
602* *BugNumber* is the bug ID in the tracker. For example: #12345.
863f782a 603* *ListOfPlatforms* is a list of platforms, at which the bug is reproduced (Linux, Windows, MacOS, or All). Note that the platform name is custom for the OCCT test system; Use procedure *checkplatform* to get the platform name.
72b7576f 604
605Example:
504a8968 606~~~~~
863f782a 607Draw[2]> checkplatform
608Windows
504a8968 609~~~~~
72b7576f 610
ae3eaf7b 611* RegularExpression is a regular expression, which should be matched against the line indicating the problem in the script output.
72b7576f 612
72b7576f 613Example:
504a8968 614~~~~~
615puts "TODO #22622 Mandriva2008: Abort .* an exception was raised"
616~~~~~
72b7576f 617
504a8968 618The parser checks the test output and if an output line matches the *RegularExpression* then it will be assigned a BAD status instead of FAILED.
72b7576f 619
504a8968 620A separate TODO line must be added for each output line matching an error expression to mark the test as BAD. If not all TODO messages are found in the test log, the test will be considered as possible improvement.
621
622To mark the test as BAD for an incomplete case (when the final *TEST COMPLETE* message is missing) the expression *TEST INCOMPLETE* should be used instead of the regular expression.
72b7576f 623
624Example:
625
504a8968 626~~~~~
627puts "TODO OCC22817 All: exception.+There are no suitable edges"
628puts "TODO OCC22817 All: \\*\\* Exception \\*\\*"
629puts "TODO OCC22817 All: TEST INCOMPLETE"
630~~~~~
72b7576f 631
6d368502 632@subsection testmanual_3_7 Marking required output
633
251a7984 634To check the obtained test output matches the expected results considered correct, add REQUIRED statement for each specific message.
635For that, the following statement should be added to the corresponding test script:
6d368502 636
637~~~~~
638puts "REQUIRED ListOfPlatforms: RegularExpression"
639~~~~~
640
641Here *ListOfPlatforms* and *RegularExpression* have the same meaning as in TODO statements described above.
642
251a7984 643The REQUIRED statement can also be used to mask the message that would normally be interpreted as error (according to the rules defined in *parse.rules*) but should not be considered as such within the current test.
6d368502 644
645Example:
646~~~~~
b502ddc1 647puts "REQUIRED Linux: Faulty shapes in variables faulty_1 to faulty_5"
6d368502 648~~~~~
649
650This statement notifies test system that errors reported by *checkshape* command are expected in that test case, and test should be considered as OK if this message appears, despite of presence of general rule stating that 'Faulty' signals failure.
504a8968 651
6d368502 652If output does not contain required statement, test case will be marked as FAILED.
504a8968 653
654@section testmanual_4 Advanced Use
72b7576f 655
656@subsection testmanual_4_1 Running Tests on Older Versions of OCCT
657
ae3eaf7b 658Sometimes it might be necessary to run tests on the previous versions of OCCT (<= 6.5.4) that do not include this test system. This can be done by adding DRAW configuration file *DrawAppliInit* in the directory, which is current by the moment of DRAW start-up, to load test commands and to define the necessary environment.
72b7576f 659
504a8968 660Note: in OCCT 6.5.3, file *DrawAppliInit* already exists in <i>$CASROOT/src/DrawResources</i>, new commands should be added to this file instead of a new one in the current directory.
661
662For example, let us assume that *d:/occt* contains an up-to-date version of OCCT sources with tests, and the test data archive is unpacked to *d:/test-data*):
663
664~~~~~
665set env(CASROOT) d:/occt
666set env(CSF_TestScriptsPath) $env(CASROOT)/tests
667source $env(CASROOT)/src/DrawResources/TestCommands.tcl
668set env(CSF_TestDataPath) $env(CASROOT)/data;d:/test-data
669return
670~~~~~
671
ae3eaf7b 672Note that on older versions of OCCT the tests are run in compatibility mode and thus not all output of the test command can be captured; this can lead to absence of some error messages (can be reported as either a failure or an improvement).
504a8968 673
674@subsection testmanual_4_2 Adding custom tests
675
676You can extend the test system by adding your own tests. For that it is necessary to add paths to the directory where these tests are located, and one or more additional data directories, to the environment variables *CSF_TestScriptsPath* and *CSF_TestDataPath*. The recommended way for doing this is using DRAW configuration file *DrawAppliInit* located in the directory which is current by the moment of DRAW start-up.
677
4ee1bdf4 678Use Tcl command <i>_path_separator</i> to insert a platform-dependent separator to the path list.
504a8968 679
680For example:
681~~~~~
682set env(CSF_TestScriptsPath) \
683 $env(TestScriptsPath)[_path_separator]d:/MyOCCTProject/tests
684set env(CSF_TestDataPath) \
685 d:/occt/test-data[_path_separator]d:/MyOCCTProject/data
686return ;# this is to avoid an echo of the last command above in cout
687~~~~~
688
689@subsection testmanual_4_3 Parallel execution of tests
690
691For better efficiency, on computers with multiple CPUs the tests can be run in parallel mode. This is default behavior for command *testgrid* : the tests are executed in parallel processes (their number is equal to the number of CPUs available on the system). In order to change this behavior, use option parallel followed by the number of processes to be used (1 or 0 to run sequentially).
72b7576f 692
87f42a3f 693Note that the parallel execution is only possible if Tcl extension package *Thread* is installed.
694If this package is not available, *testgrid* command will output a warning message.
72b7576f 695
504a8968 696@subsection testmanual_4_4 Checking non-regression of performance, memory, and visualization
72b7576f 697
504a8968 698Some test results are very dependent on the characteristics of the workstation, where they are performed, and thus cannot be checked by comparison with some predefined values. These results can be checked for non-regression (after a change in OCCT code) by comparing them with the results produced by the version without this change. The most typical case is comparing the result obtained in a branch created for integration of a fix (CR***) with the results obtained on the master branch before that change is made.
699
700OCCT test system provides a dedicated command *testdiff* for comparing CPU time of execution, memory usage, and images produced by the tests.
701
702~~~~~
703testdiff dir1 dir2 [groupname [gridname]] [options...]
704~~~~~
705Here *dir1* and *dir2* are directories containing logs of two test runs.
706
707Possible options are:
3f812249 708* <i>-save \<filename\> </i> -- saves the resulting log in a specified file (<i>$dir1/diff-$dir2.log</i> by default). HTML log is saved with the same name and extension .html;
709* <i>-status {same|ok|all}</i> -- allows filtering compared cases by their status:
710 * *same* -- only cases with same status are compared (default);
711 * *ok* -- only cases with OK status in both logs are compared;
712 * *all* -- results are compared regardless of status;
713* <i>-verbose \<level\> </i> -- defines the scope of output data:
714 * 1 -- outputs only differences;
715 * 2 -- additionally outputs the list of logs and directories present in one of directories only;
716 * 3 -- (by default) additionally outputs progress messages;
44fae8b1 717* <i>-image [filename]</i> - compare images and save the resulting log in specified file (<i>$dir1/diffimage-$dir2.log</i> by default)
718* <i>-cpu [filename]</i> - compare overall CPU and save the resulting log in specified file (<i>$dir1/diffcpu-$dir2.log</i> by default)
719* <i>-memory [filename]</i> - compare memory delta and save the resulting log in specified file (<i>$dir1/diffmemory-$dir2.log</i> by default)
720* <i>-highlight_percent \<value\></i> - highlight considerable (>value in %) deviations of CPU and memory (default value is 5%)
72b7576f 721
72b7576f 722Example:
504a8968 723
724~~~~~
44fae8b1 725Draw[]> testdiff results/CR12345-2012-10-10T08:00 results/master-2012-10-09T21:20
726~~~~~
727
728Particular tests can generate additional data that need to be compared by *testdiff* command.
729For that, for each parameter to be controlled, the test should produce the line containing keyword "COUNTER* followed by arbitrary name of the parameter, then colon and numeric value of the parameter.
730
731Example of test code:
732
733~~~~~
734puts "COUNTER Memory heap usage at step 5: [meminfo h]"
504a8968 735~~~~~
736
737@section testmanual_5 APPENDIX
738
739@subsection testmanual_5_1 Test groups
740
741@subsubsection testmanual_5_1_1 3rdparty
742
743This group allows testing the interaction of OCCT and 3rdparty products.
744
745DRAW module: VISUALIZATION.
746
747| Grid | Commands | Functionality |
748| :---- | :----- | :------- |
749| export | vexport | export of images to different formats |
750| fonts | vtrihedron, vcolorscale, vdrawtext | display of fonts |
751
752
753@subsubsection testmanual_5_1_2 blend
754
755This group allows testing blends (fillets) and related operations.
756
757DRAW module: MODELING.
758
759| Grid | Commands | Functionality |
760| :---- | :----- | :------- |
761| simple | blend | fillets on simple shapes |
762| complex | blend | fillets on complex shapes, non-trivial geometry |
763| tolblend_simple | tolblend, blend | |
764| buildevol | buildevol | |
765| tolblend_buildvol | tolblend, buildevol | use of additional command tolblend |
766| bfuseblend | bfuseblend | |
767| encoderegularity | encoderegularity | |
768
769@subsubsection testmanual_5_1_3 boolean
770
771This group allows testing Boolean operations.
772
773DRAW module: MODELING (packages *BOPTest* and *BRepTest*).
774
775Grids names are based on name of the command used, with suffixes:
3f812249 776* <i>_2d</i> -- for tests operating with 2d objects (wires, wires, 3d objects, etc.);
777* <i>_simple</i> -- for tests operating on simple shapes (boxes, cylinders, toruses, etc.);
778* <i>_complex</i> -- for tests dealing with complex shapes.
504a8968 779
780| Grid | Commands | Functionality |
781| :---- | :----- | :------- |
782| bcommon_2d | bcommon | Common operation (old algorithm), 2d |
783| bcommon_complex | bcommon | Common operation (old algorithm), complex shapes |
784| bcommon_simple | bcommon | Common operation (old algorithm), simple shapes |
785| bcut_2d | bcut | Cut operation (old algorithm), 2d |
786| bcut_complex | bcut | Cut operation (old algorithm), complex shapes |
787| bcut_simple | bcut | Cut operation (old algorithm), simple shapes |
788| bcutblend | bcutblend | |
789| bfuse_2d | bfuse | Fuse operation (old algorithm), 2d |
790| bfuse_complex | bfuse | Fuse operation (old algorithm), complex shapes |
791| bfuse_simple | bfuse | Fuse operation (old algorithm), simple shapes |
792| bopcommon_2d | bopcommon | Common operation, 2d |
793| bopcommon_complex | bopcommon | Common operation, complex shapes |
794| bopcommon_simple | bopcommon | Common operation, simple shapes |
795| bopcut_2d | bopcut | Cut operation, 2d |
796| bopcut_complex | bopcut | Cut operation, complex shapes |
797| bopcut_simple | bopcut | Cut operation, simple shapes |
798| bopfuse_2d | bopfuse | Fuse operation, 2d |
799| bopfuse_complex | bopfuse | Fuse operation, complex shapes |
800| bopfuse_simple | bopfuse | Fuse operation, simple shapes |
801| bopsection | bopsection | Section |
802| boptuc_2d | boptuc | |
803| boptuc_complex | boptuc | |
804| boptuc_simple | boptuc | |
805| bsection | bsection | Section (old algorithm) |
806
807@subsubsection testmanual_5_1_4 bugs
808
809This group allows testing cases coming from Mantis issues.
810
811The grids are organized following OCCT module and category set for the issue in the Mantis tracker.
67d7f07f 812See @ref testmanual_5_2 "Mapping of OCCT functionality to grid names in group bugs" chapter for details.
504a8968 813
814@subsubsection testmanual_5_1_5 caf
815
816This group allows testing OCAF functionality.
817
818DRAW module: OCAFKERNEL.
819
820| Grid | Commands | Functionality |
821| :---- | :----- | :------- |
822| basic | | Basic attributes |
823| bugs | | Saving and restoring of document |
824| driver | | OCAF drivers |
825| named_shape | | *TNaming_NamedShape* attribute |
826| presentation | | *AISPresentation* attributes |
827| tree | | Tree construction attributes |
828| xlink | | XLink attributes |
829
830@subsubsection testmanual_5_1_6 chamfer
831
832This group allows testing chamfer operations.
833
834DRAW module: MODELING.
835
836The test grid name is constructed depending on the type of the tested chamfers. Additional suffix <i>_complex</i> is used for test cases involving complex geometry (e.g. intersections of edges forming a chamfer); suffix <i>_sequence</i> is used for grids where chamfers are computed sequentially.
837
838| Grid | Commands | Functionality |
839| :---- | :----- | :------- |
840| equal_dist | | Equal distances from edge |
841| equal_dist_complex | | Equal distances from edge, complex shapes |
842| equal_dist_sequence | | Equal distances from edge, sequential operations |
843| dist_dist | | Two distances from edge |
844| dist_dist_complex | | Two distances from edge, complex shapes |
845| dist_dist_sequence | | Two distances from edge, sequential operations |
846| dist_angle | | Distance from edge and given angle |
847| dist_angle_complex | | Distance from edge and given angle |
848| dist_angle_sequence | | Distance from edge and given angle |
849
850@subsubsection testmanual_5_1_7 demo
851
852This group allows demonstrating how testing cases are created, and testing DRAW commands and the test system as a whole.
853
854| Grid | Commands | Functionality |
855| :---- | :----- | :------- |
856| draw | getsource, restore | Basic DRAW commands |
857| testsystem | | Testing system |
858| samples | | OCCT samples |
859
860
861@subsubsection testmanual_5_1_8 draft
862
863This group allows testing draft operations.
864
865DRAW module: MODELING.
866
867| Grid | Commands | Functionality |
868| :---- | :----- | :------- |
869| Angle | depouille | Drafts with angle (inclined walls) |
870
871
872@subsubsection testmanual_5_1_9 feat
873
874This group allows testing creation of features on a shape.
875
876DRAW module: MODELING (package *BRepTest*).
877
878| Grid | Commands | Functionality |
879| :---- | :----- | :------- |
880| featdprism | | |
881| featlf | | |
882| featprism | | |
883| featrevol | | |
884| featrf | | |
885
886@subsubsection testmanual_5_1_10 heal
887
888This group allows testing the functionality provided by *ShapeHealing* toolkit.
889
890DRAW module: XSDRAW
891
892| Grid | Commands | Functionality |
893| :---- | :----- | :------- |
894| fix_shape | fixshape | Shape healing |
895| fix_gaps | fixwgaps | Fixing gaps between edges on a wire |
896| same_parameter | sameparameter | Fixing non-sameparameter edges |
b60e8432 897| same_parameter_locked | sameparameter | Fixing non-sameparameter edges |
504a8968 898| fix_face_size | DT_ApplySeq | Removal of small faces |
899| elementary_to_revolution | DT_ApplySeq | Conversion of elementary surfaces to revolution |
900| direct_faces | directfaces | Correction of axis of elementary surfaces |
901| drop_small_edges | fixsmall | Removal of small edges |
902| split_angle | DT_SplitAngle | Splitting periodic surfaces by angle |
903| split_angle_advanced | DT_SplitAngle | Splitting periodic surfaces by angle |
904| split_angle_standard | DT_SplitAngle | Splitting periodic surfaces by angle |
905| split_closed_faces | DT_ClosedSplit | Splitting of closed faces |
906| surface_to_bspline | DT_ToBspl | Conversion of surfaces to b-splines |
907| surface_to_bezier | DT_ShapeConvert | Conversion of surfaces to bezier |
908| split_continuity | DT_ShapeDivide | Split surfaces by continuity criterion |
909| split_continuity_advanced | DT_ShapeDivide | Split surfaces by continuity criterion |
910| split_continuity_standard | DT_ShapeDivide | Split surfaces by continuity criterion |
911| surface_to_revolution_advanced | DT_ShapeConvertRev | Convert elementary surfaces to revolutions, complex cases |
912| surface_to_revolution_standard | DT_ShapeConvertRev | Convert elementary surfaces to revolutions, simple cases |
b60e8432 913| update_tolerance_locked | updatetolerance | Update the tolerance of shape so that it satisfy the rule: toler(face)<=toler(edge)<=toler(vertex) |
504a8968 914
915@subsubsection testmanual_5_1_11 mesh
916
4ee1bdf4 917This group allows testing shape tessellation (*BRepMesh*) and shading.
504a8968 918
919DRAW modules: MODELING (package *MeshTest*), VISUALIZATION (package *ViewerTest*)
920
921| Grid | Commands | Functionality |
922| :---- | :----- | :------- |
923| advanced_shading | vdisplay | Shading, complex shapes |
924| standard_shading | vdisplay | Shading, simple shapes |
925| advanced_mesh | mesh | Meshing of complex shapes |
926| standard_mesh | mesh | Meshing of simple shapes |
927| advanced_incmesh | incmesh | Meshing of complex shapes |
928| standard_incmesh | incmesh | Meshing of simple shapes |
929| advanced_incmesh_parallel | incmesh | Meshing of complex shapes, parallel mode |
930| standard_incmesh_parallel | incmesh | Meshing of simple shapes, parallel mode |
931
932@subsubsection testmanual_5_1_12 mkface
933
934This group allows testing creation of simple surfaces.
935
936DRAW module: MODELING (package *BRepTest*)
937
938| Grid | Commands | Functionality |
939| :---- | :----- | :------- |
940| after_trim | mkface | |
941| after_offset | mkface | |
942| after_extsurf_and_offset | mkface | |
943| after_extsurf_and_trim | mkface | |
944| after_revsurf_and_offset | mkface | |
945| mkplane | mkplane | |
946
947@subsubsection testmanual_5_1_13 nproject
948
949This group allows testing normal projection of edges and wires onto a face.
950
951DRAW module: MODELING (package *BRepTest*)
952
953| Grid | Commands | Functionality |
954| :---- | :----- | :------- |
955| Base | nproject | |
956
957@subsubsection testmanual_5_1_14 offset
958
959This group allows testing offset functionality for curves and surfaces.
960
961DRAW module: MODELING (package *BRepTest*)
962
963| Grid | Commands | Functionality |
964| :---- | :----- | :------- |
965| compshape | offsetcompshape | Offset of shapes with removal of some faces |
966| faces_type_a | offsetparameter, offsetload, offsetperform | Offset on a subset of faces with a fillet |
967| faces_type_i | offsetparameter, offsetload, offsetperform | Offset on a subset of faces with a sharp edge |
968| shape_type_a | offsetparameter, offsetload, offsetperform | Offset on a whole shape with a fillet |
969| shape_type_i | offsetparameter, offsetload, offsetperform | Offset on a whole shape with a fillet |
970| shape | offsetshape | |
971| wire_closed_outside_0_005, wire_closed_outside_0_025, wire_closed_outside_0_075, wire_closed_inside_0_005, wire_closed_inside_0_025, wire_closed_inside_0_075, wire_unclosed_outside_0_005, wire_unclosed_outside_0_025, wire_unclosed_outside_0_075 | mkoffset | 2d offset of closed and unclosed planar wires with different offset step and directions of offset ( inside / outside ) |
972
973@subsubsection testmanual_5_1_15 pipe
974
975This group allows testing construction of pipes (sweeping of a contour along profile).
976
977DRAW module: MODELING (package *BRepTest*)
978
979| Grid | Commands | Functionality |
980| :---- | :----- | :------- |
981| Standard | pipe | |
982
983@subsubsection testmanual_5_1_16 prism
984
985This group allows testing construction of prisms.
986
987DRAW module: MODELING (package *BRepTest*)
988
989| Grid | Commands | Functionality |
990| :---- | :----- | :------- |
991| seminf | prism | |
992
993@subsubsection testmanual_5_1_17 sewing
994
995This group allows testing sewing of faces by connecting edges.
996
997DRAW module: MODELING (package *BRepTest*)
998
999| Grid | Commands | Functionality |
1000| :---- | :----- | :------- |
1001| tol_0_01 | sewing | Sewing faces with tolerance 0.01 |
1002| tol_1 | sewing | Sewing faces with tolerance 1 |
1003| tol_100 | sewing | Sewing faces with tolerance 100 |
1004
1005@subsubsection testmanual_5_1_18 thrusection
1006
1007This group allows testing construction of shell or a solid passing through a set of sections in a given sequence (loft).
1008
1009| Grid | Commands | Functionality |
1010| :---- | :----- | :------- |
1011| solids | thrusection | Lofting with resulting solid |
1012| not_solids | thrusection | Lofting with resulting shell or face |
1013
1014@subsubsection testmanual_5_1_19 xcaf
1015
1016This group allows testing extended data exchange packages.
1017
1018| Grid | Commands | Functionality |
1019| :---- | :----- | :------- |
1020| dxc, dxc_add_ACL, dxc_add_CL, igs_to_dxc, igs_add_ACL, brep_to_igs_add_CL, stp_to_dxc, stp_add_ACL, brep_to_stp_add_CL, brep_to_dxc, add_ACL_brep, brep_add_CL | | Subgroups are divided by format of source file, by format of result file and by type of document modification. For example, *brep_to_igs* means that the source shape in brep format was added to the document, which was saved into igs format after that. The postfix *add_CL* means that colors and layers were initialized in the document before saving and the postfix *add_ACL* corresponds to the creation of assembly and initialization of colors and layers in a document before saving. |
1021
1022
1023@subsection testmanual_5_2 Mapping of OCCT functionality to grid names in group *bugs*
1024
1025| OCCT Module / Mantis category | Toolkits | Test grid in group bugs |
1026| :---------- | :--------- | :---------- |
1027| Application Framework | PTKernel, TKPShape, TKCDF, TKLCAF, TKCAF, TKBinL, TKXmlL, TKShapeSchema, TKPLCAF, TKBin, TKXml, TKPCAF, FWOSPlugin, TKStdLSchema, TKStdSchema, TKTObj, TKBinTObj, TKXmlTObj | caf |
1028| Draw | TKDraw, TKTopTest, TKViewerTest, TKXSDRAW, TKDCAF, TKXDEDRAW, TKTObjDRAW, TKQADraw, DRAWEXE, Problems of testing system | draw |
1029| Shape Healing | TKShHealing | heal |
1030| Mesh | TKMesh, TKXMesh | mesh |
1031| Data Exchange | TKIGES | iges |
1032| Data Exchange | TKSTEPBase, TKSTEPAttr, TKSTEP209, TKSTEP | step |
1033| Data Exchange | TKSTL, TKVRML | stlvrml |
1034| Data Exchange | TKXSBase, TKXCAF, TKXCAFSchema, TKXDEIGES, TKXDESTEP, TKXmlXCAF, TKBinXCAF | xde |
6268cc68 1035| Foundation Classes | TKernel, TKMath | fclasses |
504a8968 1036| Modeling_algorithms | TKGeomAlgo, TKTopAlgo, TKPrim, TKBO, TKBool, TKHLR, TKFillet, TKOffset, TKFeat, TKXMesh | modalg |
1037| Modeling Data | TKG2d, TKG3d, TKGeomBase, TKBRep | moddata |
6ce0df1e 1038| Visualization | TKService, TKV2d, TKV3d, TKOpenGl, TKMeshVS, TKNIS | vis |
504a8968 1039
1040
5ae01c85 1041@subsection testmanual_5_3 Recommended approaches to checking test results
504a8968 1042
1043@subsubsection testmanual_5_3_1 Shape validity
1044
1045Run command *checkshape* on the result (or intermediate) shape and make sure that *parse.rules* of the test grid or group reports bad shapes (usually recognized by word "Faulty") as error.
1046
1047Example
1048~~~~~
1049checkshape result
1050~~~~~
1051
5ae01c85 1052To check the number of faults in the shape command *checkfaults* can be used.
1053
1054Use: checkfaults shape source_shape [ref_value=0]
1055
1056The default syntax of *checkfaults* command:
1057~~~~~
1058checkfaults results a_1
1059~~~~~
1060
1061The command will check the number of faults in the source shape (*a_1*) and compare it
1062with number of faults in the resulting shape (*result*). If shape *result* contains
1063more faults, you will get an error:
1064~~~~~
1065checkfaults results a_1
1066Error : Number of faults is 5
1067~~~~~
1068It is possible to set the reference value for comparison (reference value is 4):
1069
1070~~~~~
1071checkfaults results a_1 4
1072~~~~~
1073
1074If number of faults in the resulting shape is unstable, reference value should be set to "-1".
1075As a result command *checkfaults* will return the following error:
1076
1077~~~~~
1078checkfaults results a_1 -1
1079Error : Number of faults is UNSTABLE
1080~~~~~
1081
504a8968 1082@subsubsection testmanual_5_3_2 Shape tolerance
dcb359e0 1083
504a8968 1084The maximal tolerance of sub-shapes of each kind of the resulting shape can be extracted from output of tolerance command as follows:
1085
1086~~~~~
1087set tolerance [tolerance result]
1088regexp { *FACE +: +MAX=([-0-9.+eE]+)} $tolerance dummy max_face
1089regexp { *EDGE +: +MAX=([-0-9.+eE]+)} $tolerance dummy max_edgee
1090regexp { *VERTEX +: +MAX=([-0-9.+eE]+)} $tolerance dummy max_vertex
1091~~~~~
1092
5ae01c85 1093It is possible to use command *checkmaxtol* to check maximal tolerance of shape and compare it with reference value.
1094
fb60057d 1095Use: checkmaxtol shape [options...]
5ae01c85 1096
1097Allowed options are:
dcb359e0 1098 * <i>-ref</i> -- reference value of maximum tolerance;
1099 * <i>-source</i> -- list of shapes to compare with;
1100 * <i>-min_tol</i> -- minimum tolerance for comparison;
1101 * <i>-multi_tol</i> -- tolerance multiplier.
5ae01c85 1102
5ae01c85 1103The default syntax of *checkmaxtol* command for comparison with the reference value:
1104~~~~~
fb60057d 1105checkmaxtol result -ref 0.00001
5ae01c85 1106~~~~~
1107
1108There is an opportunity to compare max tolerance of resulting shape with max tolerance of source shape.
1109In the following example command *checkmaxtol* gets max tolerance among objects *a_1* and *a_2*.
1110Then it chooses the maximum value between founded tolerance and value -min_tol (0.000001)
1111and multiply it on the coefficient -multi_tol (i.e. 2):
1112
1113~~~~~
fb60057d 1114checkmaxtol result -source {a_1 a_2} -min_tol 0.000001 -multi_tol 2
5ae01c85 1115~~~~~
1116
1117If the value of maximum tolerance more than founded tolerance for comparison, the command will return an error.
1118
fb60057d 1119Also, command *checkmaxtol* can be used to get max tolerance of the shape:
1120
1121~~~~~
1122set maxtol [checkmaxtol result]
1123~~~~~
1124
504a8968 1125@subsubsection testmanual_5_3_3 Shape volume, area, or length
1126
1127Use command *vprops, sprops,* or *lprops* to correspondingly measure volume, area, or length of the shape produced by the test. The value can be extracted from the result of the command by *regexp*.
1128
1129Example:
1130~~~~~
1131# check area of shape result with 1% tolerance
1132regexp {Mass +: +([-0-9.+eE]+)} [sprops result] dummy area
1133if { abs($area - $expected) > 0.1 + 0.01 * abs ($area) } {
1134 puts "Error: The area of result shape is $area, while expected $expected"
1135}
1136~~~~~
1137
1138@subsubsection testmanual_5_3_4 Memory leaks
1139
dcb359e0 1140The test system measures the amount of memory used by each test case. Considerable deviations (as well as the overall difference) in comparison with reference results can be reported by command *testdiff* (see @ref testmanual_4_4).
504a8968 1141
dcb359e0 1142To check memory leak on a particular operation, run it in a cycle, measure the memory consumption at each step and compare it with a threshold value.
1143The command *checktrend* (defined in *tests/bugs/begin*) can be used to analyze a sequence of memory measurements and to get a statistically based evaluation of the leak presence.
504a8968 1144
1145Example:
1146~~~~~
1147set listmem {}
1148for {set i 1} {$i < 100} {incr i} {
1149 # run suspect operation
1150
1151 # check memory usage (with tolerance equal to half page size)
1152 lappend listmem [expr [meminfo w] / 1024]
1153 if { [checktrend $listmem 0 256 "Memory leak detected"] } {
1154 puts "No memory leak, $i iterations"
1155 break
1156 }
1157}
1158~~~~~
1159
1160@subsubsection testmanual_5_3_5 Visualization
1161
dcb359e0 1162The following command sequence allows you to take a snapshot of the viewer, give it the name of the test case, and save in the directory indicated by Tcl variable *imagedir*.
504a8968 1163
1164~~~~~
1165vinit
1166vclear
1167vdisplay result
1168vsetdispmode 1
1169vfit
1170vzfit
1171vdump $imagedir/${casename}_shading.png
1172~~~~~
1173
1174This image will be included in the HTML log produced by *testgrid* command and will be checked for non-regression through comparison of images by command *testdiff*.
5ae01c85 1175
5747059b 1176Also it is possible to use command *checkview* to make a snapshot of the viewer.
1177
1178Use: checkview [options...]
1179Allowed options are:
dcb359e0 1180* <i>-display shapename </i> -- displays shape with name *shapename*;
1181* <i>-3d </i> -- displays shape in 3d viewer;
1182* <i>-2d [ v2d / smallview ] </i> - displays shape in 2d viewer (the default viewer is *smallview*);
1183* <i>-path PATH</i> -- sets the location of the saved viewer screenshot;
1184* <i>-vdispmode N</i> -- sets *vdispmode* for 3d viewer (default value is 1)
1185* <i>-screenshot</i> -- makes a screenshot of already created viewer
1186* The procedure can check a property of shape (length, area or volume) and compare it with value *N*:
1187 * <i>-l [N]</i>
1188 * <i>-s [N]</i>
1189 * <i>-v [N]</i>
1190 * If the current property is equal to value *N*, the shape is marked as valid in the procedure.
1191 * If value *N* is not given, the procedure will mark the shape as valid if the current property is non-zero.
1192* <i>-with {a b c}</i> -- displays shapes *a, b* and *c* together with the shape (if the shape is valid)
1193* <i>-otherwise {d e f}</i> -- displays shapes *d, e* and *f* instead of the shape (if the shape is NOT valid)
1194
1195Note that is required to use either option <i> -2d </i> or option <i> -3d</i>.
5747059b 1196
1197Examples:
1198~~~~~
1199checkview -display result -2d -path ${imagedir}/${test_image}.png
1200checkview -display result -3d -path ${imagedir}/${test_image}.png
1201checkview -display result_2d -2d v2d -path ${imagedir}/${test_image}.png
1202~~~~~
dcb359e0 1203
5747059b 1204~~~~~
1205box a 10 10 10
1206box b 5 5 5 10 10 10
1207bcut result b a
1208set result_vertices [explode result v]
1209checkview -display result -2d -with ${result_vertices} -otherwise { a b } -l -path ${imagedir}/${test_image}.png
1210~~~~~
dcb359e0 1211
5747059b 1212~~~~~
1213box a 10 10 10
1214box b 5 5 5 10 10 10
1215bcut result b a
1216vinit
1217vdisplay a b
1218vfit
1219checkview -screenshot -3d -path ${imagedir}/${test_image}.png
1220~~~~~
1221
5ae01c85 1222@subsubsection testmanual_5_3_6 Number of free edges
1223
dcb359e0 1224Procedure *checkfreebounds* compares the number of free edges with a reference value.
5ae01c85 1225
1226Use: checkfreebounds shape ref_value [options...]
1227
1228Allowed options are:
dcb359e0 1229 * <i>-tol N</i> -- used tolerance (default -0.01);
1230 * <i>-type N</i> -- used type, possible values are "closed" and "opened" (default "closed").
5ae01c85 1231
1232~~~~~
1233checkfreebounds result 13
1234~~~~~
1235
dcb359e0 1236Option <i>-tol N</i> defines tolerance for command *freebounds*, which is used within command *checkfreebounds*.
5ae01c85 1237
dcb359e0 1238Option <i>-type N</i> is used to select the type of counted free edges: closed or open.
5ae01c85 1239
dcb359e0 1240If the number of free edges in the resulting shape is unstable, the reference value should be set to "-1".
5ae01c85 1241As a result command *checkfreebounds* will return the following error:
1242
1243~~~~~
1244checkfreebounds result -1
1245Error : Number of free edges is UNSTABLE
1246~~~~~
1247
1248@subsubsection testmanual_5_3_7 Compare numbers
1249
dcb359e0 1250Procedure *checkreal* checks the equality of two reals with a tolerance (relative and absolute).
5ae01c85 1251
1252Use: checkreal name value expected tol_abs tol_rel
1253
1254~~~~~
1255checkreal "Some important value" $value 5 0.0001 0.01
1256~~~~~
1257
1258@subsubsection testmanual_5_3_8 Check number of sub-shapes
1259
dcb359e0 1260Procedure *checknbshapes* compares the number of sub-shapes in "shape" with the given reference data.
5ae01c85 1261
1262Use: checknbshapes shape [options...]
dcb359e0 1263
5ae01c85 1264Allowed options are:
dcb359e0 1265 * <i>-vertex N
5ae01c85 1266 * -edge N
1267 * -wire N
1268 * -face N
1269 * -shell N
1270 * -solid N
1271 * -compsolid N
1272 * -compound N
1273 * -shape N
dcb359e0 1274 * -t</i> -- compares the number of sub-shapes in "shape" counting
5ae01c85 1275 the same sub-shapes with different location as different sub-shapes.
dcb359e0 1276 * <i>-m msg</i> -- prints "msg" in case of error
5ae01c85 1277
1278~~~~~
1279checknbshapes result -vertex 8 -edge 4
1280~~~~~
1281
1282@subsubsection testmanual_5_3_9 Check pixel color
1283
dcb359e0 1284Command *checkcolor* can be used to check pixel color.
5ae01c85 1285
1286Use: checkcolor x y red green blue
1287
dcb359e0 1288where:
1289 * <i>x, y</i> -- pixel coordinates;
1290 * <i>red green blue</i> -- expected pixel color (values from 0 to 1).
5ae01c85 1291
dcb359e0 1292This procedure checks color with tolerance (5x5 area).
5ae01c85 1293
1294Next example will compare color of point with coordinates x=100 y=100 with RGB color R=1 G=0 B=0.
1295If colors are not equal, procedure will check the nearest ones points (5x5 area)
1296~~~~~
1297checkcolor 100 100 1 0 0
1298~~~~~
728ae8f9 1299
1300@subsubsection testmanual_5_3_10 Compute length, area and volume of input shape
1301
dcb359e0 1302Procedure *checkprops* computes length, area and volume of the input shape.
728ae8f9 1303
1304Use: checkprops shapename [options...]
1305
1306Allowed options are:
dcb359e0 1307 * <i>-l LENGTH</i> -- command *lprops*, computes the mass properties of all edges in the shape with a linear density of 1;
1308 * <i>-s AREA</i> -- command *sprops*, computes the mass properties of all faces with a surface density of 1;
1309 * <i>-v VOLUME</i> -- command *vprops*, computes the mass properties of all solids with a density of 1;
1310 * <i>-eps EPSILON</i> -- the epsilon defines relative precision of computation;
4d597f3e 1311 * <i>-deps DEPSILON</i> -- the epsilon defines relative precision to compare corresponding values;
dcb359e0 1312 * <i>-equal SHAPE</i> -- compares area, volume and length of input shapes. Puts error if they are not equal;
1313 * <i>-notequal SHAPE</i> -- compares area, volume and length of input shapes. Puts error if they are equal.
728ae8f9 1314
dcb359e0 1315Options <i> -l, -s </i> and <i> -v</i> are independent and can be used in any order. Tolerance *epsilon* is the same for all options.
728ae8f9 1316
1317~~~~~
1318checkprops result -s 6265.68
1319checkprops result -s -equal FaceBrep
1320~~~~~
1321
1322@subsubsection testmanual_5_3_11 Parse output dump and compare it with reference values
1323
1324Procedure *checkdump* is used to parse output dump and compare it with reference values.
1325
1326Use: checkdump shapename [options...]
1327
1328Allowed options are:
dcb359e0 1329 * <i>-name NAME</i> -- list of parsing parameters (e.g. Center, Axis, etc.);
1330 * <i>-ref VALUE</i> -- list of reference values for each parameter in *NAME*;
1331 * <i>-eps EPSILON</i> -- the epsilon defines relative precision of computation.
728ae8f9 1332
1333~~~~~
1334checkdump result -name {Center Axis XAxis YAxis Radii} -ref {{-70 0} {-1 -0} {-1 -0} {0 -1} {20 10}} -eps 0.01
1335~~~~~
1336
1337@subsubsection testmanual_5_3_12 Compute length of input curve
1338
dcb359e0 1339Procedure *checklength* computes length of the input curve.
728ae8f9 1340
1341Use: checklength curvename [options...]
1342
1343Allowed options are:
dcb359e0 1344 * <i>-l LENGTH</i> -- command *length*, computes the length of the input curve with precision of computation;
1345 * <i>-eps EPSILON</i> -- the epsilon defines a relative precision of computation;
1346 * <i>-equal CURVE</i> -- compares the length of input curves. Puts error if they are not equal;
1347 * <i>-notequal CURVE</i> -- compares the length of input curves. Puts error if they are equal.
728ae8f9 1348
1349~~~~~
1350checklength cp1 -l 7.278
1351checklength res -l -equal ext_1
1352~~~~~
5d7a0489 1353@subsubsection testmanual_5_3_13 Check maximum deflection, number of triangles and nodes in mesh
1354
dcb359e0 1355Command *checktrinfo* can be used to to check the maximum deflection, as well as the number of nodes and triangles in mesh.
5d7a0489 1356
1357Use: checktrinfo shapename [options...]
1358
1359Allowed options are:
dcb359e0 1360 * <i>-tri [N]</i> -- compares the current number of triangles in *shapename* mesh with the given reference data.
1361 If reference value N is not given and the current number of triangles is equal to 0, procedure *checktrinfo* will print an error.
1362 * <i>-nod [N]</i> -- compares the current number of nodes in *shapename* mesh with the given reference data.
1363 If reference value N is not given and the current number of nodes is equal to 0, procedure *checktrinfo* will print an error.
1364 * <i>-defl [N]</i> -- compares the current value of maximum deflection in *shapename* mesh with the given reference data.
1365 If reference value N is not given and current maximum deflection is equal to 0, procedure *checktrinfo* will print an error.
1366 * <i>-max_defl N</i> -- compares the current value of maximum deflection in *shapename* mesh with the max possible value.
1367 * <i>-tol_abs_tri N</i> -- absolute tolerance for comparison of number of triangles (default value 0).
1368 * <i>-tol_rel_tri N</i> -- relative tolerance for comparison of number of triangles (default value 0).
1369 * <i>-tol_abs_nod N</i> -- absolute tolerance for comparison of number of nodes (default value 0).
1370 * <i>-tol_rel_nod N</i> -- relative tolerance for comparison of number of nodes (default value 0).
1371 * <i>-tol_abs_defl N</i> -- absolute tolerance for deflection comparison (default value 0).
1372 * <i>-tol_rel_defl N</i> -- relative tolerance for deflection comparison (default value 0).
1373 * <i>-ref [trinfo a]</i> -- compares deflection, number of triangles and nodes in *shapename* and *a*.
1374
1375Note that options <i> -tri, -nod </i> and <i> -defl </i> do not work together with option <i> -ref</i>.
5d7a0489 1376
1377Examples:
1378
dcb359e0 1379Comparison with some reference values:
5d7a0489 1380~~~~~
1381checktrinfo result -tri 129 -nod 131 -defl 0.01
1382~~~~~
1383
dcb359e0 1384Comparison with another mesh:
5d7a0489 1385~~~~~
1386checktrinfo result -ref [tringo a]
1387~~~~~
1388
dcb359e0 1389Comparison of deflection with the max possible value:
5d7a0489 1390~~~~~
1391checktrinfo result -max_defl 1
1392~~~~~
1393
dcb359e0 1394Check that the current values are not equal to zero:
5d7a0489 1395~~~~~
1396checktrinfo result -tri -nod -defl
1397~~~~~
1398
dcb359e0 1399Check that the number of triangles and the number of nodes are not equal to some specific values:
5d7a0489 1400~~~~~
1401checktrinfo result -tri !10 -nod !8
1402~~~~~
1403
dcb359e0 1404It is possible to compare current values with reference values with some tolerances.
1405Use options <i>-tol_\* </i> for that.
5d7a0489 1406~~~~~
1407checktrinfo result -defl 1 -tol_abs_defl 0.001
1408~~~~~
d6b4d3d0 1409