TestCoverageWorksheet - Maple Help

Home : Support : Online Help : Programming : CodeTools : Profiling : Coverage : TestCoverageWorksheet

CodeTools[Profiling][Coverage]

 TestCoverageWorksheet
 create a worksheet to determine coverage

 Calling Sequence TestCoverageWorksheet(p, paths, opts)

Parameters

 p - the name of a module or procedure, or a set or list of such names paths - (optional) string or list or set of strings; paths to test files opts - (optional) keyword options, see below

Options

 • setlibname : truefalse or the symbol auto, default is auto
 If set to true, Maple will insert a statement setting libname to its value in the current session. If set to false, Maple will not insert such a statement. If set to auto, Maple will behave as setlibname = true if libname has more than one component.
 • basedir : string or symbol, default currentdir()
 Path relative to which paths is understood. The worksheet will contain a currentdir() command to go into this directory before reading the given paths, if any. If this is a string, it's understood as a literal path. If it is a symbol, it is expected that this is a symbol understood by kernelopts; e.g., mapledir.
 • newsheet : truefalse, default true
 Whether to insert the content as a new worksheet.
 • insert : truefalse, default false
 Whether to insert the content into the current worksheet.
 • returnxml : truefalse, default false
 Whether to return the content as xml. Otherwise, return NULL.
 • useshowstat : truefalse, default false
 To show the results, you can use either showstat or CodeTools:-Profiling:-Coverage:-Print. The worksheet will include both commands but one will be commented out; by default that's the showstat command. This option allows you to switch that around.
 • testfilemarkers : truefalse or the symbol auto, default is auto
 If set to true, Maple will insert a call of the form CodeTools:-Test(1, 0, 'label' = str, 'quiet', 'boolout') before each read command. The string str indicates the file name that Maple is about to read. This makes it easier to interpret the result of the call to CodeTools:-TestFailures at the end of the worksheet: it will contain a test failure marking the start of each test file. Setting the option to false will omit these calls. If set to auto, the calls will be included if the number of test files specified is greater than one. If no test files are specified, this option is ignored.

Description

 • This command creates a worksheet that can be used to examine test coverage of some code by some test files. This can then be used in the following cycle:
 1 Run the worksheet by hitting the Execute Worksheet button (!!!).
 2 See if all tests pass: if so, skip ahead to step 6.
 3 Find which test fails. Because the read statements have semicolons after them, failure results will be shown in the worksheet. You should be able to search for them with Ctrl + F (Command+F, Mac), searching for failed.
 5 Restart from step 1.
 6 Find somewhere you want to improve test coverage. If you do not find such a place, you're done.
 7 Add a test case that covers that code.
 8 Restart from step 1.
 • The worksheet will contain commands to execute the following steps:
 1 A restart command.
 2 If so directed by the setting of the setlibname option, set the libname variable.
 3 The definition of a command to recursively list the members of a module.
 4 Calls to this command to find all recursive members of the given module, and select the procedures among them.
 5 Calls to CodeTools:-Profiling:-Profile to turn on profiling of all these procedures.
 6 Calls to read in order to read the test files. These test files should have calls to the CodeTools:-Test command to do their tests. They should not include restart commands. If you do not specify the paths argument, Maple will insert instructions where to include the read statements.
 7 Calls to showstat and to CodeTools:-Profiling:-Coverage:-Print. One of these will be commented out. The advantage of the latter is that you can quickly see if there are lines in the procedure that aren't covered; the advantage of the former is that you see all lines of code, so you have context and can understand the code better.
 8 A call to print all entries of CodeTools:-TestFailures(), so that if there are any failures, you are informed of them explicitly. It's useful to have this at the bottom of the worksheet, so that you see it immediately after you have run it with the Execute Worksheet button.

Examples

It is typically more useful to use the default options newsheet=true and insert=false, but using the opposite here allows for easier demonstration of what the result looks like in this help page.

 > $\mathrm{CodeTools}:-\mathrm{Profiling}:-\mathrm{Coverage}:-\mathrm{TestCoverageWorksheet}\left(\mathrm{NewPackage},\left\{"test/mpl/123456.tst","lib/NewPackage/tst/bar.tst","lib/NewPackage/tst/foo.tst"\right\},\mathrm{basedir}=\mathrm{mapledir},\mathrm{newsheet}=\mathrm{false},\mathrm{insert}\right)$
 > $\mathrm{restart}$
 > $\mathrm{libname}≔"/maple/cbat/active/169462/lib","/maple/cbat/active/169462/toolbox/BlockImporter/lib","/maple/cbat/active/169462/toolbox/GlobalOptimization/lib","/maple/cbat/active/169462/toolbox/Grid/lib","/maple/cbat/active/169462/toolbox/MatlabSymbolicToolbox/lib"$
 > $\mathrm{all_entries}≔\mathrm{CodeTools}:-\mathrm{RecursiveMembers}\left(\mathrm{NewPackage},'\mathrm{output}'='\mathrm{members}'\right):$
 > $\mathrm{procs}≔\mathrm{select}\left(\mathrm{type},\mathrm{all_entries},\mathrm{procedure}\right)$
 > $\mathrm{map}\left(\mathrm{CodeTools}:-\mathrm{Profiling}:-\mathrm{Profile},\mathrm{procs}\right):$
 > $\mathrm{currentdir}\left(\mathrm{kernelopts}\left(\mathrm{mapledir}\right)\right):$
 > $\mathrm{CodeTools}:-\mathrm{Test}\left(1,0,'\mathrm{label}'="next test file: test/mpl/123456.tst",'\mathrm{quiet}','\mathrm{boolout}'\right):$
 > $\mathbf{read}\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}"test/mpl/123456.tst"$
 > $\mathrm{CodeTools}:-\mathrm{Test}\left(1,0,'\mathrm{label}'="next test file: lib/NewPackage/tst/bar.tst",'\mathrm{quiet}','\mathrm{boolout}'\right):$
 > $\mathbf{read}\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}"lib/NewPackage/tst/bar.tst"$
 > $\mathrm{CodeTools}:-\mathrm{Test}\left(1,0,'\mathrm{label}'="next test file: lib/NewPackage/tst/foo.tst",'\mathrm{quiet}','\mathrm{boolout}'\right):$
 > $\mathbf{read}\phantom{\rule[-0.0ex]{0.3em}{0.0ex}}"lib/NewPackage/tst/foo.tst"$
 > $\text{#map(showstat, procs):}$
 > $\mathrm{map}\left(\mathrm{CodeTools}:-\mathrm{Profiling}:-\mathrm{Coverage}:-\mathrm{Print},\mathrm{procs}\right):$
 > $\mathrm{map2}\left(\mathrm{printf},"%s\n",\mathrm{CodeTools}:-\mathrm{TestFailures}\left(\right)\right):$

Compatibility

 • The CodeTools:-Profiling:-Coverage:-TestCoverageWorksheet command was introduced in Maple 2021.