2 Bug Detection and Reporting

2.1 Functions and Variables for Bug Detection and Reporting

Function: run_testsuite ([options])

Run the Maxima test suite. Tests producing the desired answer are considered “passes,” as are tests that do not produce the desired answer, but are marked as known bugs.

run_testsuite takes the following optional keyword arguments

display_all

Display all tests. Normally, the tests are not displayed, unless the test fails. (Defaults to false).

display_known_bugs

Displays tests that are marked as known bugs. (Default is false).

tests

This is a single test or a list of tests that should be run. Each test can be specified by either a string or a symbol. By default, all tests are run. The complete set of tests is specified by testsuite_files.

time

Display time information. If true, the time taken for each test file is displayed. If all, the time for each individual test is shown if display_all is true. The default is false, so no timing information is shown.

share_tests

Load additional tests for the share directory. If true, these additional tests are run as a part of the testsuite. If false, no tests from the share directory are run. If only, only the tests from the share directory are run. Of course, the actual set of test that are run can be controlled by the tests option. The default is false.

For example run_testsuite(display_known_bugs = true, tests=[rtest5]) runs just test rtest5 and displays the test that are marked as known bugs.

run_testsuite(display_all = true, tests=["rtest1", rtest1a]) will run tests rtest1 and rtest2, and displays each test.

run_testsuite changes the Maxima environment. Typically a test script executes kill to establish a known environment (namely one without user-defined functions and variables) and then defines functions and variables appropriate to the test.

run_testsuite returns done.

Categories:  Debugging

Option variable: testsuite_files

testsuite_files is the set of tests to be run by run_testsuite. It is a list of names of the files containing the tests to run. If some of the tests in a file are known to fail, then instead of listing the name of the file, a list containing the file name and the test numbers that fail is used.

For example, this is a part of the default set of tests:

 ["rtest13s", ["rtest14", 57, 63]]

This specifies the testsuite consists of the files "rtest13s" and "rtest14", but "rtest14" contains two tests that are known to fail: 57 and 63.

Categories:  Debugging Global variables

Option variable: share_testsuite_files

share_testsuite_files is the set of tests from the share directory that is run as a part of the test suite by run_testsuite..

Categories:  Debugging Global variables

Function: bug_report ()

Prints out Maxima and Lisp version numbers, and gives a link to the Maxima project bug report web page. The version information is the same as reported by build_info.

When a bug is reported, it is helpful to copy the Maxima and Lisp version information into the bug report.

bug_report returns an empty string "".

Categories:  Debugging

Function: build_info ()

Returns a summary of the parameters of the Maxima build, as a Maxima structure (defined by defstruct). The fields of the structure are: version, timestamp, host, lisp_name, and lisp_version. When the pretty-printer is enabled (via display2d), the structure is displayed as a short table.

See also bug_report.

Examples:

(%i1) build_info ();
(%o1) 
Maxima version: "5.36.1"
Maxima build date: "2015-06-02 11:26:48"
Host type: "x86_64-unknown-linux-gnu"
Lisp implementation type: "GNU Common Lisp (GCL)"
Lisp implementation version: "GCL 2.6.12"

(%i2) x : build_info ()$

(%i3) x@version;
(%o3)                               5.36.1

(%i4) x@timestamp;
(%o4)                         2015-06-02 11:26:48

(%i5) x@host;
(%o5)                      x86_64-unknown-linux-gnu

(%i6) x@lisp_name;
(%o6)                        GNU Common Lisp (GCL)

(%i7) x@lisp_version;
(%o7)                             GCL 2.6.12

(%i8) x;
(%o8) 
Maxima version: "5.36.1"
Maxima build date: "2015-06-02 11:26:48"
Host type: "x86_64-unknown-linux-gnu"
Lisp implementation type: "GNU Common Lisp (GCL)"
Lisp implementation version: "GCL 2.6.12"

The Maxima version string can (here 5.36.1) can look very different:

(%i1) build_info();
(%o1) 
Maxima version: "branch_5_37_base_331_g8322940_dirty"
Maxima build date: "2016-01-01 15:37:35"
Host type: "x86_64-unknown-linux-gnu"
Lisp implementation type: "CLISP"
Lisp implementation version: "2.49 (2010-07-07) (built 3605577779) (memory 3660647857)"

In that case, Maxima was not build from a released sourcecode, but directly from the GIT-checkout of the sourcecode. In the example, the checkout is 331 commits after the latest GIT tag (usually a Maxima (major) release (5.37 in our example)) and the abbreviated commit hash of the last commit was "8322940".

Categories:  Debugging