@menu
* Functions and Variables for Bug Detection and Reporting::
@end menu

@c -----------------------------------------------------------------------------
@node Functions and Variables for Bug Detection and Reporting
@section Functions and Variables for Bug Detection and Reporting
@c -----------------------------------------------------------------------------

@c -----------------------------------------------------------------------------
@anchor{run_testsuite}
@deffn {Function} run_testsuite ([@var{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.

@code{run_testsuite} takes the following optional keyword arguments

@table @code
@item display_all
Display all tests.  Normally, the tests are not displayed, unless the test
fails.  (Defaults to @code{false}).
@item display_known_bugs
Displays tests that are marked as known bugs.  (Default is @code{false}).
@item 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 @mrefdot{testsuite_files}
@item time
Display time information.  If @code{true}, the time taken for each
test file is displayed.  If @code{all}, the time for each individual
test is shown if @code{display_all} is @code{true}.  The default is
@code{false}, so no timing information is shown.
@end table

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

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

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

@code{run_testsuite} returns @code{done}.

@opencatbox
@category{Debugging}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{testsuite_files}
@defvr {Option variable} testsuite_files

@code{testsuite_files} is the set of tests to be run by
@mrefdot{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:

@example
 ["rtest13s", ["rtest14", 57, 63]]
@end example

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

@opencatbox
@category{Debugging} @category{Global variables}
@closecatbox
@end defvr

@c -----------------------------------------------------------------------------
@anchor{bug_report}
@deffn {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 @mrefdot{build_info}

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

@code{bug_report} returns an empty string @code{""}.

@opencatbox
@category{Debugging}
@closecatbox
@end deffn

@c -----------------------------------------------------------------------------
@anchor{build_info}
@deffn {Function} build_info ()

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

See also @mrefdot{bug_report}

Examples:

@c ===beg===
@c build_info ();
@c x : build_info ()$
@c x@version;
@c x@timestamp;
@c x@host;
@c x@lisp_name;
@c x@lisp_version;
@c x;
@c ===end===
@example
@group
(%i1) build_info ();
(%o1) 
Maxima version: "5.26.0_16_gb72c64c_dirty"
Maxima build date: "2012-01-29 12:29:04"
Host type: "i686-pc-linux-gnu"
Lisp implementation type: "CMU Common Lisp"
Lisp implementation version: "CVS release-19a 19a-release-20040728 + minimal debian patches"
@end group
(%i2) x : build_info ()$
@group
(%i3) x@@version;
(%o3)               5.26.0_16_gb72c64c_dirty
@end group
@group
(%i4) x@@timestamp;
(%o4)                  2012-01-29 12:29:04
@end group
@group
(%i5) x@@host;
(%o5)                   i686-pc-linux-gnu
@end group
@group
(%i6) x@@lisp_name;
(%o6)                    CMU Common Lisp
@end group
@group
(%i7) x@@lisp_version;
(%o7) 
    CVS release-19a 19a-release-20040728 + minimal debian patches
@end group
@group
(%i8) x;
(%o8) 
Maxima version: "5.26.0_16_gb72c64c_dirty"
Maxima build date: "2012-01-29 12:29:04"
Host type: "i686-pc-linux-gnu"
Lisp implementation type: "CMU Common Lisp"
Lisp implementation version: "CVS release-19a 19a-release-20040728 + minimal debian patches"
@end group
@end example

@opencatbox
@category{Debugging}
@closecatbox
@end deffn

