Tester APIs

The Tester class provides the following methods:

General comparison of arbitrary objects that user can invoke:

// determine the extensional equality of the two given objects

public boolean same(Object obj1, Object obj2)

Basic tests:

// Run a test that only reports success or failure

public boolean checkExpect(boolean result)

// -- optional testname provided --

public  boolean checkExpect(boolean result, String testname)

// Run a test that compares two objects of any kind

public <T> boolean checkExpect(T actual, T expected)

// -- optional testname arg --

public <T> boolean checkExpect(T actual, T expected,

String testname)

// Run a test that only reports success or failure

// and allows the comparison of inexact values

public  <T> boolean checkInexact(T actual, T expected,

double tolerance)

// -- optional testname arg --

public <T> boolean checkInexactt(T actual, T expected,

double tolerance, String testname)

// Run a test that compares two objects of any kind

// and expects a failure

public <T> boolean checkFail(T actual, T expected)

// -- optional testname provided --

public  <T> boolean checkFail(T actual, T expected,

String testname)

// Run a test that compares two objects of any kind

// and expects a failure

// but allows the comparison of inexact values

public  <T> boolean checkInexactFail(T actual, T expected,

double tolerance)

// -- optional testname provided --

public  <T> boolean checkInexactFail(T actual, T expected,

double tolerance, String testname)

Checking whether the given value matches one of several options:

Warning: If the actual and expected values are String-s, the programmer must provide the test name — there is no way the tester can determine whether or not the test name has been included.

// Run a test that determines whether the value of the actual

// is the same as one of the possible expected values

// For each pair of values invokes the same comparison

// as for checkExpect

public  <T>  boolean checkOneOf(T actual, T... expected)

// -- optional testname provided --

public  <T>  boolean checkOneOf(String testname,

T actual, T... expected)

// Run a test that determines whether the value of the actual

// is the same as one of the possible expected values

// and allow the comparison of inexact values

// For each pair of values invokes the same comparison

// as for checkInexactExpect

public  <T>  boolean checkInexactOneOf(double tolerance,

T actual, T... expected)

// -- optional testname provided --

public  <T>  boolean checkInexactOneOf(String testname,

double tolerance, T actual, T... expected)

// Run a test that determines whether the value of the actual

// is the none of the possible expected values

// For each pair of values invokes the same comparison

// as for checkExpect

public  <T>  boolean checkNoneOf(T actual, T.. expected)

// -- optional testname provided --

public  <T>  boolean checkNoneOf(String testname,

T actual, T... expected)

// Run a test that determines whether the value of the actual

// is the none of the possible expected values

// and allow the comparison of inexact values

// For each pair of values invokes the same comparison

// as for checkInexactExpect

public  <T>  boolean checkInexactNoneOf(double tolerance,

T actual, T.. expected)

// -- optional testname provided --

public  <T>  boolean checkInexactNoneOf(String testname,

double tolerance, T actual, T... expected)

Checking whether the given value is within the given range:

// Run a test that determines whether the value of the actual

// is within the bounds given by the (inclusive) low value and

// (exclusive) high value for any numeric type

// (wrapper class extends Number)

public <T>  boolean checkNumRange(Number actual,

Number low, Number high)

// -- optional testname provided --

public  <T>  boolean checkNumRange(Number actual,

Number low, Number high, String testname)

// specify whether low and high bounds are inclusive

public  <T>  boolean checkNumRange(Number actual,

Number low, Number high, boolen low, boolean high)

// specify whether low and high bounds are inclusive

// -- optional testname provided --

public  <T>  boolean checkNumRange(Number actual,

Number low, Number high, boolen low, boolean high, String testname)

// Run a test that determines whether the value of the actual

// is within the bounds given by the (inclusive) low value and

// (exclusive) high value.

// Ordering is given by the class of actual that implements

// the Comparable interface.

public  <T>  boolean checkRange(Comparable<T> actual,

T low, T high)

// -- optional testname provided --

public  <T>  boolean checkRange(Comparable<T> actual,

T low, T high, String testname)

// specify whether low and high bounds are inclusive

public  <T>  boolean checkRange(Comparable<T> actual,

T low, T high, boolen low, boolean high)

// specify whether low and high bounds are inclusive

// -- optional testname provided --

public  <T>  boolean checkRange(Comparable<T> actual,

T low, T high, boolen low, boolean high, String testname)

// Run a test that determines whether the value of the actual

// is within the bounds given by the (inclusive) low value and

// (exclusive) high value.

// Ordering is given by providing an argument that implments

// the  Comparator interface.

public  <T>  boolean checkRange(T actual, T low, T high,

Comparator<T>)

// -- optional testname provided --

public  <T>  boolean checkRange(T actual, T low, T high,

Comparator<T>, String testname)

// specify whether low and high bounds are inclusive

public  <T>  boolean checkRange(T actual, T low, T high,

Comparator<T>, , boolen low, boolean high)

// -- optional testname provided --

public  <T>  boolean checkRange(T actual, T low, T high,

Comparator<T>, , boolen low, boolean high, String testname)

Checking whether the two value match using user-defined equivalence:

// Run a test that determines the equivalence

// of the two given objects

// as specified by the given Equivalence function object.

public <T>  boolean checkEquivalent(T obj1, T obj2,

Equivalence<T>)

// -- optional testname provided --

public <T>  boolean checkEquivalent(T obj1, T obj2,

Equivalence<T>, String testname)

Checking whether a method invocation throws the desired exception:

// Run a test that verifies that when the given object

// invokes the given method with the given arguments,

// it throws the expected exception with the expected message

public <T>  boolean checkException(Exception e, T object,

String methodName, Object... args)

// -- optional testname provided --

public <T>  boolean checkException(String testname,

Exception e, T object,  String methodName, Object... args)

Checking whether a constructor invocation throws the desired exception:

// Run a test that verifies that when the constructor

// for the given class

// is invoked with the given arguments,

// it throws the expected exception with the expected message

public <T>  boolean checkConstructorException(Exception e,

String className, Object... args)

// -- optional testname provided --

public <T>  boolean checkConstructorException(String testname,

Exception e, String className, Object... args)

Invoke a method with the given object and arguments – check the result:

// Run a test that invokes the method with the given name

// on a given object with the given arguments -

// check if it produces the expected value

public <T>  boolean checkMethod(Object expected, T object,

String method, Object... args)

//  -- optional testname provided --

public <T>  boolean checkMethod(String testname, Object expected,

T object, String method, Object... args)

// Run a test that invokes the method with the given name

// on a given object with the given arguments -

// check if it produces the expected value

// the result may involve inexact values

public <T>  boolean checkInexactMethod(Object expected,

double tolerance, T object, String method, Object... args)

//  -- optional testname provided --

public <T>  boolean checkInexactMethod(String testname,

Object expected, double tolerance, T object, String method,

Object... args)

Methods for comparing compound data (the Set interface):

The method checkExpect on two objects in the same class that implements the Set interface compares the objects as sets, using equals method for comparing the elements of the sets.

The method checkSet compares two objects that represent the same sets in different classes.

The equals method is again used to compare the elements of the two sets.

// Compare two objects that implement the Set interface

// by examining the data elements -

// use equals method for the  comparison

public <T>  boolean checkSet(Set<T>, Set<T>)

// -- optional testname provided --

public <T>  boolean checkSet(Set<T>, Set<T>,

String testname)

Methods for comparing compound data (the Iterable interface):

The methods checkExcpect and checkInexact on Iterable classes within the Java Collections Library always iterate over the data.

These methods allow the user to check the correct implementation of the iterators.

// Compare two objects that implement the Iterable interface

// by traversing over the data - use exact comparison for the members

public <T>  boolean checkIterable(Iterable<T>, Iterable<T>)

// -- optional testname provided --

public <T>  boolean checkIterable(Iterable<T>, Iterable<T>,

String testname)

// Compare two inexact objects that implement the Iterable interface

// by traversing over the data - use inexact comparison for the members

public <T>  boolean checkInexactIterable(Iterable<T>, Iterable<T>)

// -- optional testname provided --

public <T>  boolean checkInexactIterable(Iterable<T>, Iterable<T>,

String testname)

Methods for comparing compound data (the Traversal interface that represents a functional iterator):

// Compare two objects that implement the Traversal interface

// by traversing over the data - use exact comparison for the members

public <T>  boolean checkTraversal(Traversal<T>, Traversal<T>)

// -- optional testname provided --

public <T>  boolean checkTraversal(Traversal<T>, Traversal<T>,

String testname)

// Compare two inexact objects that implement the Traversal interface

// by traversing over the data - use inexact comparison for the members

public <T>  boolean checkInexactTraversal(Traversal<T>, Traversal<T>)

// -- optional testname provided --

public <T>  boolean checkInexactTraversal(Traversal<T>, Traversal<T>,

String testname)

Methods for reporting results:

// Run the tester for any object

// obj the 'Examples' class instance where the tests are defined

public static void run(Object obj)

// Run the tester for any object producing full report

// obj the 'Examples' class instance where the tests are defined

public static void runFullReport(Object obj)

// Run the tester as desired for any object

// obj the 'Examples' class instance where the tests are defined

// if full is true, full report of all tests is printed

// if printall is true all fields in Examples class are shown

// The run method behaves like runReport with

// full == false, printall = true

public static void runReport(Object obj,

boolean full, boolean printall)

// Run the tester as desired for a collection of objects

// obj several 'Examples' class instances where the tests are defined

// if full is true, full report of all tests is printed

// if printall is true all fields in Examples class are shown

// The run method behaves like runReport with

// full == false, printall = true

public static void runReports(boolean full, boolean printall,

Object... obj)

Methods defined in the Printer class

// Print the values of the given object

public static void print(Object obj)

// Produce a String representation of the values

// of the given object

public static String produceString(Object obj)

If the user defines toString method, the display includes both, the user’s result and the object rendition generated through reflection.

Method defined in the Main class

// Run the test cases defined in the 'test' class

// By default the class is named 'Examples'

// A different class name can be given as argument

public static void main(String[] argv)

Method defined in the Inspector class.

Compares the values of the given objects outside of the test methods.

// A public constructor

public Inspector()

// did the last comparison involve inexact values?

public boolean inexactCompares();

// return true if the two given object are the same

// the comparison rules are the same

// as for the checkExpect

public boolean isSame(Object obj1, Object obj2)

Interface ISame:

public interface ISame<T>{

// Is this object the same as that?

public boolean same(T that); }

Interface Equivalence:

public interface Equivalence<T>{

//Determine whether the two given object of the type T are equivalent.

public boolean equivalent(T t1, T t2);}

Interface IExamples:

public interface IExamples {

// The method implemented by the user

// that invokes the test cases

// and the report generator methods in the Tester class

public void tests(Tester t); }

Interface Traversal:

public interface Traversal<T>{

// Produce true if the dataset

// given by this Traversal is empty

public boolean isEmpty();

// Produce the first element in the dataset

// given by this Traversal

// Throws IllegalUseOfTraversalException

// if the dataset is empty.

public T getFirst();

// Produce a Traversal for the rest of the dataset

// Throws IllegalUseOfTraversalException

// if the dataset is empty.

public Traversal <T> getRest();

}

The tester package defines two Exception classes:

// Exception to be raised on an attempt

// to advance a traversal over an empty collection

// or to produce the first element

// of an empty collection.

public class IllegalUseOfTraversalException

extends RuntimeException

// Exception to be raised when a test case fails,

// so that we can record

// and report the stack trace at that point.

public class ErrorReport

extends RuntimeException