## 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".

  Front-ends for maxima can add information about currently being used by setting the variables `maxima_frontend` and `maxima_frontend_version` accordingly.

  ·

  Categories: Debugging