.. Mars Documentation
   Copyright (C) 2008 Matt Giuca
   3/9/2008

.. This program is free software: you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation, either version 3 of the License, or
   (at your option) any later version.

.. This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

.. You should have received a copy of the GNU General Public License
   along with this program.  If not, see <http://www.gnu.org/licenses/>.

:mod:`unittest` --- Testing user code
=====================================

.. sectionauthor:: Matt Giuca <matt.giuca@gmail.com>
.. moduleauthor::  Matt Giuca <matt.giuca@gmail.com>

.. module:: unittest
   :synopsis: Provides functions to facilitate testing of user code.

This module provides functions to facilitate testing of user code. It provides
an interface for writing unit tests and printing out the results. (The
printouts are not "pretty"; they are designed to be interpreted by a
wrapping script such as the :ref:`Mars Test Framework <testing>`.)

The test framework communicates with a wrapper by printing messages to
standard output. Such messages are single lines beginning with "``:test:``".

A "test case" is a single unit, which can be as big or small as the caller
wishes. Zero or more asserts can be made within a single case. The case fails
if any one of the asserts fails. The reason for this two-tiered system is so
you can try a whole bunch of cascading asserts in a single case, and not have
a mountain of failures if one fails.

Test cases must be explicitly begun and ended, in order to make sure rogue
assert statements in between test cases are reported by the wrapper (rather
than simply being believed to be in the most recent test case).

An "assert" is a test of a single condition. Each assert has a message, which
describes what might go wrong. The message of the first failing assert will be
printed if a test case fails.

Note once again that the output of this module is not meant to be viewed by a
human, but processed by a wrapper and displayed in a nicer format.

.. function:: begin_case(name :: Array(Num)) :: io Num

   Begin a new test case. The *name* of the test case is for output purposes
   only, and does not have to be unique. It will be printed if the case fails.

   .. note::

      *name* should not contain newlines (this restriction may be relaxed).

.. function:: begin_case_pending(name :: Array(Num)) :: io Num

   Same as :func:`begin_case`, but flag the case as expected to fail (as a
   temporary measure, so that you may check in code which is broken but which
   you intend to fix).

   Will report an explicit "pass" if none of the asserts fail. Will not report
   anything if at least one assert fails.

.. function:: end_case(name :: Array(Num)) :: io Num

   End the current test case. Must use same name as most recent begin.

.. function:: assert(value :: Num, message :: Array(Num)) :: io Num

   Checks that *value* is nonzero. If *value* is nonzero, returns 1.
   Otherwise, prints an assert error with *message* and returns 0.

   Describe in *message* what went wrong if the case fails. For example,
   ``assert_(4 == 9, "4 != 9")``.

   .. note::

      *message* should not contain newlines (this restriction may be relaxed).

.. function:: assert_eq(x :: a, y :: a, _message :: Array(Num)) :: io Num

   Checks that *x* equals *y*, according to :func:`eq`. If *x* equals *y*,
   returns 1. Otherwise, prints an assert error with the values of *x* and *y*
   and returns 0. (*_message* is ignored, and is included for historical
   reasons.)

.. function:: assert_near(x :: Num, y :: Num, message :: Array(Num)) :: io Num

   Checks that *x* and *y* are within *ϵ* of one another, where *ϵ* is a small
   value (currently, 2^-16). Use this to test the result of floating point
   arithmetic. If *x* is within *ϵ* of *y*, returns 1.  Otherwise, prints an
   assert error with *message* and returns 0.