/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */

/*

 * Copyright (c) 2009 University of Washington

 *

 * This program is free software; you can redistribute it and/or modify

 * it under the terms of the GNU General Public License version 2 as

 * published by the Free Software Foundation;

 *

 * 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, write to the Free Software

 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

 */

#ifndef NS3_TEST_H

#define NS3_TEST_H

#include <iostream>

#include <fstream>

#include <sstream>

#include <string>

#include <vector>

#include <list>

#include <limits>

#include <stdint.h>

#include "non-copyable.h"

#include "system-wall-clock-ms.h"

/**

 * \file

 * \ingroup testing

 * \brief Definition of the testing macros and declaration of

 * the testing classes.

 */

/**

 * \ingroup core

 * \defgroup testing Testing

 * \brief Tools to define and execute unit tests.

 *

 * This module lists the normal Testing API.  Most of these

 * macros forward to the implementation macros in testingimpl.

 * You should generally use these macros only.

 */

/**

 * \ingroup testing

 * \defgroup testingimpl Testing Implementation

 * \brief Internal implementation of the Testing system.

 */

// 

// Note on below macros:

//

// When multiple statements are used in a macro, they should be bound

// together in a loop syntactically, so the macro can appear safely

// inside if clauses or other places that expect a single statement or

// a statement block.  The "strange" do while construct is a generally

// expected best practice for defining a robust macro.

//

/**

 * \ingroup testing

 * \brief Check if we should assert on errors, and do so

 */

#define ASSERT_ON_FAILURE                       \

  do {                                          \

    if (MustAssertOnFailure ())                 \

      {                                         \

        *(volatile int *)0 = 0;                 \

      }                                         \

  } while (false)

/**

 * \ingroup testing

 * \brief If we shouldn't continue on errors, return

 */

#define CONTINUE_ON_FAILURE                                             \

  do {                                                                  \

    if (!MustContinueOnFailure ())                                      \

      {                                                                 \

        return;                                                         \

      }                                                                 \

  } while (false)

/**

 * \ingroup testing

 * \brief If we shouldn't continue on errors, return test status

 */

#define CONTINUE_ON_FAILURE_RETURNS_BOOL                                \

  do {                                                                  \

    if (!MustContinueOnFailure ())                                      \

      {                                                                 \

        return IsStatusFailure ();                                      \

      }                                                                 \

  } while (false)

// ===========================================================================

// Test for equality (generic version)

// ===========================================================================

/**

 * \ingroup testingimpl

 * \brief Test that an actual and expected (limit) value are equal and report

 * and abort if not.

 */

#define NS_TEST_ASSERT_MSG_EQ_INTERNAL(actual, limit, msg, file, line)  \

  do {                                                                  \

    if (!((actual) == (limit)))                                         \

      {                                                                 \

        ASSERT_ON_FAILURE;                                              \

        std::ostringstream msgStream;                                   \

        msgStream << msg;                                               \

        std::ostringstream actualStream;                                \

        actualStream << actual;                                         \

        std::ostringstream limitStream;                                 \

        limitStream << limit;                                           \

        ReportTestFailure (std::string (#actual) + " (actual) == " +    \

                           std::string (#limit) + " (limit)",           \

                           actualStream.str (), limitStream.str (),     \

                           msgStream.str (), file, line);               \

        CONTINUE_ON_FAILURE;                                            \

      }                                                                 \

  } while (false)

/**

 * \ingroup testing

 *

 * \brief Test that an actual and expected (limit) value are equal and

 * report and abort if not.

 *

 * Check to see if the expected (limit) value is equal to the actual

 * value found in a test case.  If the two values are equal nothing

 * happens, but if the comparison fails, an error is reported in a

 * consistent way and the execution of the current test case is

 * aborted.

 *

 * The message is interpreted as a stream, for example:

 *

 * \code

 * NS_TEST_ASSERT_MSG_EQ (result, true, 

 *      "cannot open file " << filename << " in test");

 * \endcode

 *

 * is legal.

 * 

 * \param [in] actual Expression for the actual value found during the test.

 * \param [in] limit Expression for the expected value of the test.

 * \param [in] msg Message that is output if the test does not pass.

 *

 * \warning Do not use this macro if you are comparing floating point

 * numbers (float or double) as it is unlikely to do what you expect.

 * Use NS_TEST_ASSERT_MSG_EQ_TOL instead.

 */

#define NS_TEST_ASSERT_MSG_EQ(actual, limit, msg) \

  NS_TEST_ASSERT_MSG_EQ_INTERNAL (actual, limit, msg, __FILE__, __LINE__)

/**

 * \ingroup testingimpl

 * \brief Test that an actual and expected (limit) value are equal and report

 * and abort if not.

 */

#define NS_TEST_ASSERT_MSG_EQ_RETURNS_BOOL_INTERNAL(actual, limit, msg, file, line) \

  do {                                                                  \

    if (!((actual) == (limit)))                                         \

      {                                                                 \

        ASSERT_ON_FAILURE;                                              \

        std::ostringstream msgStream;                                   \

        msgStream << msg;                                               \

        std::ostringstream actualStream;                                \

        actualStream << actual;                                         \

        std::ostringstream limitStream;                                 \

        limitStream << limit;                                           \

        ReportTestFailure (std::string (#actual) + " (actual) == " +    \

                       std::string (#limit) + " (limit)",               \

                       actualStream.str (), limitStream.str (),         \

                       msgStream.str (), file, line);                   \

        CONTINUE_ON_FAILURE_RETURNS_BOOL;                               \

      }                                                                 \

  } while (false)

/**

 * \ingroup testing

 *

 * \brief Test that an actual and expected (limit) value are equal and

 * report and abort if not.

 *

 * Check to see if the expected (limit) value is equal to the actual

 * value found in a test case.  If the two values are equal nothing

 * happens, but if the comparison fails, an error is reported in a

 * consistent way and the execution of the current test case is

 * aborted.

 *

 * The message is interpreted as a stream, for example:

 *

 * \code

 * NS_TEST_ASSERT_MSG_EQ_RETURNS_BOOL (result, true, 

 *      "cannot open file " << filename << " in test");

 * \endcode

 *

 * is legal.

 * 

 * \param [in] actual Expression for the actual value found during the test.

 * \param [in] limit Expression for the expected value of the test.

 * \param [in] msg Message that is output if the test does not pass.

 *

 * \warning Do not use this macro if you are comparing floating point

 * numbers (float or double) as it is unlikely to do what you expect.

 * Use NS_TEST_ASSERT_MSG_EQ_RETURNS_BOOL_TOL instead.

 *

 * This function returns a boolean value.

 *

 */

#define NS_TEST_ASSERT_MSG_EQ_RETURNS_BOOL(actual, limit, msg) \

  NS_TEST_ASSERT_MSG_EQ_RETURNS_BOOL_INTERNAL (actual, limit, msg, __FILE__, __LINE__)

/**

 * \ingroup testingimpl

 * \brief Test that an actual and expected (limit) value are equal and

 * report if not.

 * 

 * Required to avoid use of return statement which allows use in

 * methods (esp. callbacks) returning void.

 */

#define NS_TEST_EXPECT_MSG_EQ_INTERNAL(actual, limit, msg, file, line)  \

  do {                                                                  \

    if (!((actual) == (limit)))                                         \

      {                                                                 \

        ASSERT_ON_FAILURE;                                              \

        std::ostringstream msgStream;                                   \

        msgStream << msg;                                               \

        std::ostringstream actualStream;                                \

        actualStream << actual;                                         \

        std::ostringstream limitStream;                                 \

        limitStream << limit;                                           \

        ReportTestFailure (std::string (#actual) + " (actual) == " +    \

                       std::string (#limit) + " (limit)",               \

                       actualStream.str (), limitStream.str (),         \

                       msgStream.str (), file, line);                   \

      }                                                                 \

  } while (false)

/**

 * \ingroup testing

 *

 * \brief Test that an actual and expected (limit) value are equal and

 * report if not.

 *

 * Check to see if the expected (lmit) value is equal to the actual

 * value found in a test case.  If the two values are equal nothing

 * happens, but if the comparison fails, an error is reported in a

 * consistent way.  EXPECT* macros do not return if an error is

 * detected.

 *

 * The message is interpreted as a stream, for example:

 *

 * \code

 * NS_TEST_EXPECT_MSG_EQUAL (result, true, 

 *      "cannot open file " << filename << " in test");

 * \endcode

 *

 * is legal.

 * 

 * \param [in] actual Expression for the actual value found during the test.

 * \param [in] limit Expression for the expected value of the test.

 * \param [in] msg Message that is output if the test does not pass.

 *

 * \warning Do not use this macro if you are comparing floating point

 * numbers (float or double) as it is unlikely to do what you expect.

 * Use NS_TEST_EXPECT_MSG_EQ_TOL instead.

 */

#define NS_TEST_EXPECT_MSG_EQ(actual, limit, msg) \

  NS_TEST_EXPECT_MSG_EQ_INTERNAL (actual, limit, msg, __FILE__, __LINE__)

// ===========================================================================

// Test for equality with a provided tolerance (use for floating point 

// comparisons -- both float and double)

// ===========================================================================

/**

 * \ingroup testingimpl

 * \brief Test that actual and expected (limit) values are equal to

 * plus or minus some tolerance and report and abort if not.

 */

#define NS_TEST_ASSERT_MSG_EQ_TOL_INTERNAL(actual, limit, tol, msg, file, line) \

  do {                                                                  \

    if ((actual) > (limit) + (tol) || (actual) < (limit) - (tol))       \

      {                                                                 \

        ASSERT_ON_FAILURE;                                              \

        std::ostringstream msgStream;                                   \

        msgStream << msg;                                               \

        std::ostringstream actualStream;                                \

        actualStream << actual;                                         \

        std::ostringstream limitStream;                                 \

        limitStream << limit << " +- " << tol;                          \

        std::ostringstream condStream;                                  \

        condStream << #actual << " (actual) < " << #limit               \

                   << " (limit) + " << #tol << " (tol) && "             \

                   << #actual << " (actual) > " << #limit               \

                   << " (limit) - " << #tol << " (tol)";                \

        ReportTestFailure (condStream.str (), actualStream.str (),      \

                       limitStream.str (), msgStream.str (),            \

                       file, line);                                     \

        CONTINUE_ON_FAILURE;                                            \

      }                                                                 \

  } while (false)

/**

 * \ingroup testing

 *

 * \brief Test that actual and expected (limit) values are equal to

 * plus or minus some tolerance and report and abort if not.

 *

 * Check to see if the expected (limit) value is equal to the actual

 * value found in a test case to some tolerance.  This is not the same

 * thing as asking if two floating point are equal to within some

 * epsilon, but is useful for that case.  This assertion is geared

 * toward more of a measurement problem.  Consider measuring a

 * physical rod of some kind that you have ordered.  You need to

 * determine if it is "good."  You want to measure the rod to an

 * arbitrary precision of sixteen significant figures, you will

 * measure the rod to determine if its length is within the tolerances

 * you provided.  For example, 12.00 inches plus or minus .005 inch

 * may be just fine.

 * 

 * In ns-3, you might want to measure a signal to noise ratio and

 * check to see if the answer is what you expect.  If you naively

 * measure (double)1128.93 and compare this number with a constant

 * 1128.93 you are almost certainly going to have your test fail

 * because of floating point rounding errors.  We provide a floating

 * point comparison function ns3::TestDoubleIsEqual() but you will

 * probably quickly find that is not what you want either.  It may

 * turn out to be the case that when you measured an snr that printed

 * as 1128.93, what was actually measured was something more like

 * 1128.9287653857625442 for example.  Given that the double epsilon

 * is on the order of 0.0000000000000009, you would need to provide

 * sixteen significant figures of expected value for this kind of test

 * to pass even with a typical test for floating point "approximate

 * equality."  That is clearly not required or desired.  You really

 * want to be able to provide 1128.93 along with a tolerance just like

 * you provided 12 inches +- 0.005 inch above.

 *

 * This assertion is designed for real measurements by taking into

 * account measurement tolerances.  By doing so it also automatically

 * compensates for floating point rounding errors.  If you really want

 * to check floating point equality down to the

 * numeric_limits<double>::epsilon () range, consider using

 * ns3::TestDoubleIsEqual().

 *

 * \note Mixing signed and unsigned types can lead to misleading

 * results.

 *

 * The message is interpreted as a stream, for example:

 *

 * \code

 *   NS_TEST_ASSERT_MSG_EQ_TOL (snr, 1128.93, 0.005,

 *                              "wrong snr (" << snr << ") in test");

 * \endcode

 *

 * is legal.

 * 

 * \param [in] actual Expression for the actual value found during the test.

 * \param [in] limit Expression for the expected value of the test.

 * \param [in] tol Tolerance of the test.

 * \param [in] msg Message that is output if the test does not pass.

 */

#define NS_TEST_ASSERT_MSG_EQ_TOL(actual, limit, tol, msg)                 \

  NS_TEST_ASSERT_MSG_EQ_TOL_INTERNAL (actual, limit, tol, msg, __FILE__, __LINE__)

/**

 * \ingroup testingimpl

 * \brief Test that actual and expected (limit) values are equal to

 * plus or minus some tolerance and report and abort if not.

 */

#define NS_TEST_ASSERT_MSG_EQ_TOL_RETURNS_BOOL_INTERNAL(actual, limit, tol, msg, file, line) \

  do {                                                                  \

    if ((actual) > (limit) + (tol) || (actual) < (limit) - (tol))       \

      {                                                                 \

        ASSERT_ON_FAILURE;                                              \

        std::ostringstream msgStream;                                   \

        msgStream << msg;                                               \

        std::ostringstream actualStream;                                \

        actualStream << actual;                                         \

        std::ostringstream limitStream;                                 \

        limitStream << limit << " +- " << tol;                          \

        std::ostringstream condStream;                                  \

        condStream << #actual << " (actual) < " << #limit               \

                   << " (limit) + " << #tol << " (tol) && "             \

                   << #actual << " (actual) > " << #limit               \

                   << " (limit) - " << #tol << " (tol)";                \

        ReportTestFailure (condStream.str (), actualStream.str (),      \

                       limitStream.str (), msgStream.str (),            \

                       file, line);                                     \

        CONTINUE_ON_FAILURE_RETURNS_BOOL;                               \

      }                                                                 \

  } while (false)

/**

 * \ingroup testing

 *

 * \brief Test that actual and expected (limit) values are equal to

 * plus or minus some tolerance and report and abort if not.

 *

 * Check to see if the expected (limit) value is equal to the actual

 * value found in a test case to some tolerance.  This is not the same

 * thing as asking if two floating point are equal to within some

 * epsilon, but is useful for that case.  This assertion is geared

 * toward more of a measurement problem.  Consider measuring a

 * physical rod of some kind that you have ordered.  You need to

 * determine if it is "good."  You want to measure the rod to an

 * arbitrary precision of sixteen significant figures, you will

 * measure the rod to determine if its length is within the tolerances

 * you provided.  For example, 12.00 inches plus or minus .005 inch

 * may be just fine.

 * 

 * In ns-3, you might want to measure a signal to noise ratio and

 * check to see if the answer is what you expect.  If you naively

 * measure (double)1128.93 and compare this number with a constant

 * 1128.93 you are almost certainly going to have your test fail

 * because of floating point rounding errors.  We provide a floating

 * point comparison function ns3::TestDoubleIsEqual() but you will

 * probably quickly find that is not what you want either.  It may

 * turn out to be the case that when you measured an snr that printed

 * as 1128.93, what was actually measured was something more like

 * 1128.9287653857625442 for example.  Given that the double epsilon

 * is on the order of 0.0000000000000009, you would need to provide

 * sixteen significant figures of expected value for this kind of test

 * to pass even with a typical test for floating point "approximate

 * equality."  That is clearly not required or desired.  You really

 * want to be able to provide 1128.93 along with a tolerance just like

 * you provided 12 inches +- 0.005 inch above.

 *

 * This assertion is designed for real measurements by taking into

 * account measurement tolerances.  By doing so it also automatically

 * compensates for floating point rounding errors.  If you really want

 * to check floating point equality down to the

 * numeric_limits<double>::epsilon () range, consider using

 * ns3::TestDoubleIsEqual().

 *

 * \note Mixing signed and unsigned types can lead to misleading

 * results.

 *

 * The message is interpreted as a stream, for example:

 *

 * \code

 *   NS_TEST_ASSERT_MSG_EQ_TOL_RETURNS_BOOL (snr, 1128.93, 0.005,

 *                                           "wrong snr (" << snr << ") in test");

 * \endcode

 *

 * is legal.

 * 

 * \param [in] actual Expression for the actual value found during the test.

 * \param [in] limit Expression for the expected value of the test.

 * \param [in] tol Tolerance of the test.

 * \param [in] msg Message that is output if the test does not pass.

 *

 * This function returns a boolean value.

 *

 */

#define NS_TEST_ASSERT_MSG_EQ_TOL_RETURNS_BOOL(actual, limit, tol, msg)  \

  NS_TEST_ASSERT_MSG_EQ_TOL_RETURNS_BOOL_INTERNAL (actual, limit, tol, msg, __FILE__, __LINE__)

/**

 * \ingroup testingimpl

 * \brief Test that actual and expected (limit) values are equal to

 * plus or minus some tolerance and report if not.

 * 

 * Required to avoid use of return statement which allows use in

 * methods (esp. callbacks) returning void.

 */

#define NS_TEST_EXPECT_MSG_EQ_TOL_INTERNAL(actual, limit, tol, msg, file, line) \

  do {                                                                  \

    if ((actual) > (limit) + (tol) || (actual) < (limit) - (tol))       \

      {                                                                 \

        ASSERT_ON_FAILURE;                                              \

        std::ostringstream msgStream;                                   \

        msgStream << msg;                                               \

        std::ostringstream actualStream;                                \

        actualStream << actual;                                         \

        std::ostringstream limitStream;                                 \

        limitStream << limit << " +- " << tol;                          \

        std::ostringstream condStream;                                  \