Overview

ezTest is a unit test framework for standalone C++, Python or any command-line tests.

It includes a Python suite manager that allows coordination of any combination of the C++/Python/Console tests to be invoked from a single driver. Reports test number, name and duration in optional tty colors. Supports custom test order to logically structure test execution from simple cases to most complex (anti-thesis to auto test discovery). The command line interface also allows selective test cases to be run to focus on and isolate failures. Only an import (Python) or include (C++) is needed to use ezTest.

ezTest image

Features

Pretty printed results with colors, test names, numbers and duration.
Choose to run specific tests from command line.
Custom order of test execution that is not imposed by unordered auto-discovery.

Download

Source code

Testing

make examples
make test
make memtest
make clean

Installation

# For C++.
sudo make install PREFIX=/usr/local

# For Python (uses pip).
make python_install

C++ Usage

This shows how to structure test functions and how to access command-line options:

#include "ezTest.hpp"

bool test_clean(eztest::ezTestRunner& runner) {
  // If assertion fails, returns false and prints
  // the file, line number and code that failed.
  ezassert( runner.clean == true );
  return true;
}

bool test_tmpdir(eztest::ezTestRunner& runner) {
  ezassert( runner.tmpdir.compare("/tmp") == 0);
  return true;
}

bool test_verboseIsFalse(eztest::ezTestRunner& runner) {
  ezassert( runner.verbose == false );
  return true;
}

int main(int argc, const char* argv[]) {
  eztest::ezTestRunner runner;
  runner.getopt(argc, argv);

  runner.add(&test_clean, "test_clean. See if --clean is on.");
  runner.add(&test_tmpdir, "test_tmpdir. See if --tmpdir is set to \"/tmp\".");
  runner.add(&test_verboseIsFalse, "test_verboseIsFalse. See if --verbose was not set.");

  // Do setup here and/or in functions.

  int status = runner.run();

  // Do tear down here and/or in functions.

  return status;
}

Save that to ezTestDemo.cpp and build and run as follows from your command-line:

# Use any c++ compiler.
g++ ezTestDemo.cpp -o ezTestDemo
./ezTestDemo --color --verbose --tmpdir /tmp

# Run only the second and third tests:
./ezTestDemo --color --verbose --tmpdir /tmp 2 3

Python Usage

Extend ezTestSuite as shown here:

from ezTest import *

class ezTestDemo(ezTestSuite):
  def __init__(self):
    self.name = 'ezTest Demo Suite'

    # Ordered list of functions to run and description.
    # The runner will assign a test number from 1 upwards.
    # Each test function should return True or False.
    self.tests = [
      [self.testExample1, 'First example test.'],
      [self.testExample2, 'Second example test that fails.'],
      [self.testExample3, 'Third example test.'],
      [self.testExample4, 'Fourth example test.'],
    ]

  def testExample1(self): return True
  def testExample2(self): return False
  def testExample3(self): return True
  def testExample4(self): return True

  if __name__=='__main__':
    # Create list of suites.
    suites = [ezTestDemo(),]

    # Get command-line options.
    opt = ezTestOpt()

    runner = ezTestRunner(suites, opt=opt)
    runner.run()

Save that to ezTestDemo.py and run it from the command-line:

# Be sure to install ezTest for Python, or run within src/py.
python ezTestDemo.py --color --verbose

# Run only the second through the fourth tests:
python ezTestDemo.py --color --verbose 2:4

Mixed Console Usage

If you have tests in another program or script that can be executed from the command-line, then you can have them all driven by ezTest. This examples shows the C++ and Python examples above run from a single driver:

from ezTest import *
from ezTestDemo import ezTestDemo

if __name__=='__main__':
  suites = [
    ezTestDemo(),
    # The C++ test offers 3 tests.
    ezConsoleSuite("./ezTestDemo", 3),
    ezTestDemo(),
  ]

  ezTestRunner(suites, opt=ezTestOpt()).run()

Save this as test_mixed.py and run it from the command-line. The command-line options are forwarded to the suites:

# Runs all the possible tests.
python test_mixed.py --color --verbose

# Runs specific tests per suite.
# The first suite tests 2 tests, and so does the second suite.
# The last suite skips all its tests.
python test_mixed.py --color --verbose 1,2/3:4/none

Supported Command-line Options

To see the options, run either:

./ezTestDemo --help
python ezTestDemo.py --help

--clean FLAG

This is a boolean that your test harness can look at if it should remove any temporary files. Cleaning is optional because you may need to inspect temporary results if a test case is failing.

--color

If printed messages should use tty colors (not always portable).

--dryrun

Don't run the tests. Just print as failures. Useful to see what the tests are and their numbers.

--help

Prints the runner syntax and options available.

--memory

Report memory usage.

--tmpdir PATH

Specify a path where temporary files should be written. If cleaning is disabled, you will find your files there.

--verbose

A convenient flag to tell your harness if verbose messages should be printed. Also enables extra printing of test case progress like duration and PASS/FAIL.

Distribution

make html
make clean
make dist VER=0.3.1

Publishing

ssh -t rsz,eztest@shell.sourceforge.net create
scp html/* rsz,eztest@shell.sourceforge.net:/home/project-web/eztest/htdocs
scp ../ezTest-0.3.1.tar.gz rsz,eztest@shell.sourceforge.net:/home/frs/project/e/ez/eztest