Unit Testing Frameworks

1.3.1 Set up the project.

package mailinglist;
/**
 * A contact is a name and address.
 * <p>
 * For the purpose of this example, I have simplified matters 
 * a bit by making both of these components simple strings. 
 * In practice, we would expect Address, at least, to be a
 * more structured type.
 * 
 * @author zeil
 *
 */
public class Contact 
  implements Cloneable, Comparable<Contact> {

 private String theName;
 private String theAddress;

 /**
  * Create a contact with empty name and address.
  *
  */
 public Contact ()
 {
  theName = "";
  theAddress = "";
 }

 /**
  * Create a contact
  * @param nm  name 
  * @param addr address
  */
 public Contact (String nm, String addr)
 {
  theName = nm;
  theAddress = addr;
 }


 /**
  * Get the name of the contact
  * @return the name
  */
 public String getName()
 {
  return theName;
 }
 
 /**
  * Change the name of the contact
  * @param nm new name
  */
 public void setName (String nm) 
 {
  theName= nm;
 }

 /**
  * Get the address of the contact
  * @return the address
  */
 public String getAddress()
 {
  return theAddress;
 }
 
 /**
  * Change the address of the contact 
  * @param addr new address
  */
 public void setAddress (String addr) 
 {
  theAddress = addr;
 }

 /**
  * True if the names and addresses are equal 
  */
 public boolean equals (Object right)
 {
  Contact r = (Contact)right;
  return theName.equals(r.theName)
     && theAddress.equals(r.theAddress);
 }

 public int hashCode ()
 {
  return theName.hashCode() + 3 * theAddress.hashCode();
 }

 public String toString()
 {
  return theName + ": " + theAddress;
 }
 
 public Object clone()
 {
  return new Contact(theName, theAddress);
 }

 /**
  * Compare this contact to another.
  * Return value > 0 if this contact precedes the other,
  * == 0 if the two are equal, and < 0 if this contact
  * follows the other.  
  */
 public int compareTo (Contact c)
 {
  int nmcomp = theName.compareTo(c.theName);
  if (nmcomp != 0)
   return nmcomp;
  else
   return theAddress.compareTo(c.theAddress);
 }
}

MailingList.java

package mailinglist;

import java.util.Iterator;
import java.util.LinkedList;
import java.util.ListIterator;

/**
 * A collection of names and addresses
 */
public class MailingList implements Cloneable {

    private LinkedList<Contact> theContacts;

    /**
	 * Create an empty mailing list
	 *
	 */
	public MailingList() {
	    theContacts = new LinkedList<Contact>();
	}

	/**
	 *  Add a new contact to the list. Contacts should be kept in ascending
	 *  order with no duplicates.
	 *  
	 *  @param contact new contact to add
	 */
	public void addContact(Contact contact) {
	    ListIterator<Contact> it = theContacts.listIterator();
	    while (it.hasNext()) {
	        Contact c = it.next();
	        int compared = c.compareTo(contact); 
	        if (compared > 0) {
	            it.previous();
	            it.add(contact);
	            return;
	        } else if (compared == 0) {
	            return;
	        }
	    }
	    theContacts.add(contact);
	}

	/**
	 *  Remove one matching contact 
	 *  @param contact remove a contact equal to contact
	 */
	public void removeContact(Contact contact) {
        ListIterator<Contact> it = theContacts.listIterator();
        while (it.hasNext()) {
            Contact c = it.next();
            int compared = c.compareTo(contact); 
            if (compared > 0) {
                return;
            } else if (compared == 0) {
                it.remove();
                return;
            }
        }
	}

	/**
	 * Remove a contact with the indicated name
	 * @param name name of contact to remove
	 */
	public void removeContact(String name) {
        ListIterator<Contact> it = theContacts.listIterator();
        while (it.hasNext()) {
            Contact c = it.next();
            int compared = c.getName().compareTo(name); 
            if (compared > 0) {
                return;
            } else if (compared == 0) {
                it.remove();
                return;
            }
        }
	}

	/**
	 * Search for contacts
	 * @param name name to search for
	 * @return true if a contact with an equal name exists
	 */
	public boolean contains(String name) {
        ListIterator<Contact> it = theContacts.listIterator();
        while (it.hasNext()) {
            Contact c = it.next();
            int compared = c.getName().compareTo(name); 
            if (compared > 0) {
                return false;
            } else if (compared == 0) {
                return true;
            }
        }
        return false;
	}

	/**
	 * Search for contacts
	 * @param name name to search for
	 * @return contact with that name if found, null if not found
	 */
	public Contact getContact(String name) {
        ListIterator<Contact> it = theContacts.listIterator();
        while (it.hasNext()) {
            Contact c = it.next();
            int compared = c.getName().compareTo(name); 
            if (compared > 0) {
                return null;
            } else if (compared == 0) {
                return c;
            }
        }
        return null;
	}

	/**
	 * combine two mailing lists
	 *
	 */
	public void merge(MailingList anotherList) {
		// For a quick merge, we will loop around, checking the 
		// first item in each list, and always copying the smaller
		// of the two items into result
		LinkedList<Contact> result = new LinkedList<Contact>();
		ListIterator<Contact> thisPos = theContacts.listIterator();
        ListIterator<Contact> otherPos = anotherList.theContacts.listIterator();
        while (thisPos.hasNext() && otherPos.hasNext()) {
            Contact thisContact = thisPos.next();
            Contact otherContact = otherPos.next();
            int comp = thisContact.compareTo(otherContact);
            if (comp == 0) {
                result.add(thisContact);
            } else if (comp < 0) {
                result.add(thisContact);
                otherPos.previous();
            } else {
                result.add(otherContact);
                thisPos.previous();
            }           
        }
        // Now, one of the two lists has been entirely copied. 
        // The other might still have stuff to copy. So we just copy
        // any remaining items from the two lists. Note that one of these
        // two loops will execute zero times.
        while (thisPos.hasNext()) {
            result.add(thisPos.next());
        }
        while (otherPos.hasNext()) {
            result.add(otherPos.next());
        }
        // Now result contains the merged list. Transfer that into this list.
		theContacts = result;
	}

	/**
	 * How many contacts in list?
	 */
	public int size() {
		return theContacts.size();
	}

	/**
	 * Return true if mailing lists contain equal contacts
	 */
	public boolean equals(Object anotherList) {
	    if (!(anotherList instanceof MailingList)) {
	        return false;
	    }
		MailingList right = (MailingList) anotherList;
		if (size() != right.size()) { // (easy test first!)
			return false;
		}
        ListIterator<Contact> thisPos = theContacts.listIterator();
        ListIterator<Contact> otherPos = right.theContacts.listIterator();
        while (thisPos.hasNext() && otherPos.hasNext()) {
            Contact thisContact = thisPos.next();
            Contact otherContact = otherPos.next();
            if (!thisContact.equals(otherContact)) {
                return false;
            }
        }
        return true;
	}

	public int hashCode() {
	    return theContacts.hashCode();
	}

	public String toString() {
		StringBuffer buf = new StringBuffer("{");
		boolean first = true;
		for (Contact c: theContacts) {
		    if (!first) {
		        buf.append(", ");
		    }
		    first = false;
		    buf.append(c.toString());
		}
		buf.append("}");
		return buf.toString();
	}

	/**
	 * Deep copy of contacts
	 */
	public Object clone() {
		MailingList result = new MailingList();
		for (Contact c: theContacts) {
		    result.theContacts.add((Contact)c.clone());
		}
		return result;
	}
	
}

Set up an Eclipse project with these two files
- Make sure that these compile successfully with no errors.
In the Eclipse Build Path, add a library: JUnit,
- Choose JUnit5 from the list of versions

1.3.2 Set up the MailingList tests

Right-click on the project. Select New...Junit Test Case

Make sure JUnit Jupiter is selected. Fill in the name (TestMailingList) and the “Class Under Test” (mailinglist.MailingList). Click Next.

For reasons we will explain later, we select the functions that initialize or make changes to the MailingList: the constructor, addContact, removeContact, merge, and clone. Click Finish.
- These functions are known as the mutators of the class.

1.3.3 Structure of a JUnit test

We wind up with something like this:

package mailinglist;

import static org.junit.jupiter.api.Assertions.*;

import org.junit.jupiter.api.Test;

class TestMailingList ➀ {

	@Test  ➁
	void testMailingList() {
		fail("Not yet implemented");
	}

	@Test
	void testAddContact() {
		fail("Not yet implemented");
	}

	@Test
	void testRemoveContactContact() {
		fail("Not yet implemented");
	}

	@Test
	void testRemoveContactString() {
		fail("Not yet implemented");
	}

	@Test
	void testMerge() {
		fail("Not yet implemented");
	}

	@Test
	void testClone() {
		fail("Not yet implemented");
	}

}

➀ A JUnit test is a class.
➁ It contains one or more “test cases” or “test functions” – member functions that return void, take no parameters, and are marked with @Test.
Each test case needs to
1. Sets up any necessary test data.
2. Runs the code to be tested on that data.
3. Examines the results of the test via one or more assertions.
  But, of course, right now none of that has been written yet.
A test case can
1. Succeed if all assertions are true.
2. Fail if any assertion is false (or if the fail(...) function is called explicitly).
3. Terminate with an error if the test case itself throws an exception.

1.3.4 Our first test case - the constructor

Let’s think about testing the MailingList constructor:

MailingList() {
    ⋮
}

What do we think should be true when this has completed?

reveal

We go to our skeleton testMailingList() and try to express those ideas:

	@Test
	void testMailingList() {
		MailingList ml = new MailingList();
		assertEquals (0, ml.size());
	}

Is that enough?

To be thorough, we should look at all of the MailingList functions that we did not select to create separate tests for.
These are the functions that examine the value of the MailingList without changing it: contains, getContact, size, equals, hashCode, and toString.
- These are known as the accessors of the class.
For each of these, we ask what it should tell us about the newly created MailingList.

After construction…

contains should return false for all names.
getContact should return null for all names.
size should be zero.
equals should return true when compared to another freshly-constructed list.
hashCodes should be equal whenever equals is true.
can’t really say anything about toString, as the documentation does not require a specific output format. (The primary role of toString in most classes is to provide debugging output.) But it should return some kind of string.

    @Test
    void testMailingList() {
        MailingList ml = new MailingList(); ➀
        assertEquals (0, ml.size());        ➁
        assertFalse (ml.contains("Jones"));
        assertNull (ml.getContact("Smith"));
        MailingList ml2 = new MailingList();
        assertEquals (ml2, ml);
        assertEquals (ml2.hashCode(), ml.hashCode());
        assertNotNull(ml.toString());
    }

Every good JUnit test can be read as

➀ A demo of how to use the function being tested,
➁ followed by a description of that function’s effects.

Reading the unit tests is often one of the easiest ways to discover how to use an unfamiliar class.

1.3.5 Running the test

Now would be a good time to run the test.

In Eclipse, right-click on the TestMailinglist.java file and select Run as...JUnit test.

1.4 Assertions

We’ve now seen several examples of JUnit assertions.

These are fundamental, but not as descriptive as other options:

assertTrue( condition ): condition should be true.
assertFalse( condition ): condition should be false.

More common basic assertions:

assertEquals( x , y): x and y should be equal. (For objects, this is tested using the equals(...) function. For primitives like int, the == operator is used.)
assertEquals( x , y , delta): Floating point numbers x and y should be approximately equal, within plus or minus delta.
assertNotEquals( x , y): x and y should not be equal.
assertSame( obj1 , obj2): obj1 and obj2 should hold the same address.
assertNotSame( obj1 , obj2): obj1 and obj2 should not hold the same address.
assertNull( obj1 ): obj1 should be a null reference.
assertNotNull( obj1 ): obj1 should not be a null reference.

More specialized assertions:

assertArrayEquals( array1 , array2): array1 and array2 should have the same length and corresponding elements in these arrays should be equal.
assertLinesMatch( expectedList , actualListOfStrings): compares a list of expected strings/regular expressions against a list of actual strings.
assertIterablesEquals( expectedContainer , actualContainer): compares two containers of objects to see if their contents are equal.

“Meta-” assertions:

fail( message ): always fails
assertThrows( exception, Executable ): asserts that code will throw an exception
assertTimeout( timeLimit , Executable): asserts that code will finish within a stated time.
assertTimeoutPreemptively( timeLimit , Executable): asserts that code will finish within a stated time, and kills the code if it doesn’t.

In these, the Executable is likely to be a Java lambda expression.

e.g.,

 assertTimeout(Duration.ofSeconds(1), 
          () -> {longMailingList1.merge(longMailingList2);});

Each assertion can have an optional final argument of a string that will be printed when the assertion fails. For example,

Integer pos = search(arr, x);
assertNotNull (pos);
assertNotNull (pos, "Could not find x in arr");

1.5 Resuming the example…

Now let’s look at addContact.

Remember the basic pattern:

Setup the parameters we need to the call to the function we want to test.
Call the function.
Use assertions to examine the effects of that call.

We can carryout the first two steps pretty easily.

    @Test
    void testAddContact() {
        Contact holmes = new Contact("Holmes", "21B Baker St.");
        MailingList ml = new MailingList();
        ml.addContact(holmes);
          ⋮
    }

1.5.1 Examining the mailing list after adding a contact

Again we look at out list of accessors:

After adding holmes…

contains should return true for “Holmes” but false for other names.
getContact should return a contact equal to holmes when given “Holmes”, null for all other names.
size should be 1.
equals should return false when compared to a freshly-constructed list, true when compared to one containing only holmes.
hashCodes should be equal whenever equals is true.
“Holmes” should appear somewhere in the output of toString.

    @Test
    void testAddContact() {
        Contact holmes = new Contact("Holmes", "21B Baker St.");
        MailingList ml = new MailingList();
        ml.addContact(holmes);
        assertEquals(1, ml.size());
        assertTrue(ml.contains("Holmes"));
        assertFalse(ml.contains("Jones"));
        assertEquals (holmes, ml.getContact("Holmes"));
        assertNull (ml.getContact("Jones"));
        assertNotEquals(ml, new MailingList());
        MailingList ml2 = new MailingList();
        ml2.addContact(holmes);
        assertEquals (ml2, ml);
        assertEquals (ml2.hashCode(), ml.hashCode());
        assertTrue(ml.toString().contains("Holmes"));
    }

Run this and see if we pass.

1.5.2 Testing for multiple adds

Of course, adding a single contact to an empty mailing list is not much of a test.

It’s a special case for most data structures we might use, and we need to test the “mainstream” cases as well.
We can’t explore the question of whether the mailing list is keeping the contacts in the desired order.
We can’t check on what happens when we add duplicate contacts.

We could make our existing test case for addContact longer, or we can add additional cases to explore these possibilities:

testContactMulti

@Test
void testAddContactMulti() {
    Contact holmes = new Contact("Holmes", "21B Baker St.");       ➀
    Contact adams = new Contact("Adams", "21 Pennsylvania Ave.");
    Contact baker = new Contact("Baker", "Drury Ln.");
    Contact charles = new Contact("Charles", "100 1st St.");
    Contact dickens = new Contact("Dickens", "200 2nd St.");

    Contact[] inputs = {dickens, adams, charles, holmes, baker};    ➁

    MailingList ml = new MailingList();

        for (int testSize = 1; testSize <= inputs.length; ++testSize) {
            MailingList ml0 = (MailingList)ml.clone();              ➂
            ml.addContact(inputs[testSize-1]);
            assertEquals(testSize, ml.size());
            for (int j = 0; j <= testSize-1; ++j) {                 ➃
                assertTrue (ml.contains(inputs[j].getName()), 
                        "failed after adding " + inputs[testSize-1].getName()); ➄
                assertEquals (inputs[j], ml.getContact(inputs[j].getName()),
                        "failed after adding " + inputs[testSize-1].getName());
                assertTrue(ml.toString().contains(inputs[j].getName()),
                        "failed after adding " + inputs[testSize-1].getName());
            }
            for (int j = testSize+1; j < inputs.length; ++j) {        ➅
                assertFalse (ml.contains(inputs[j].getName()), 
                        "failed after adding " + inputs[testSize-1].getName());
                assertNull (ml.getContact(inputs[j].getName()),
                        "failed after adding " + inputs[testSize-1].getName());
                assertFalse(ml.toString().contains(inputs[j].getName()),
                        "failed after adding " + inputs[testSize-1].getName());
            }
            assertNotEquals(ml, ml0);
        }
}

➀ We need to set up a bunch of contacts.

➁ This is the order in which we will add them to to our mailing list.

➂ ml0 sets up the “preserve-and-compare” idiom.
➃ Each of the first i contacts should be in the mailing list.
- ➄ It’s worth adding a specialized message on failure to help us know which iteration of the loop a failure occurs on.
➅ Each of the remaining contacts after the first i ones should not be in the mailing list.

1.5.3 Adding a duplicate contact

The documentation for addContact says that duplicates are not added. We should test for that as well:

testAddDuplicateContact

    @Test
    void testAddDuplicateContact() {
        Contact holmes = new Contact("Holmes", "21B Baker St.");       ➀
        Contact adams = new Contact("Adams", "21 Pennsylvania Ave.");
        Contact baker = new Contact("Baker", "Drury Ln.");
        Contact charles = new Contact("Charles", "100 1st St.");
        Contact dickens = new Contact("Dickens", "200 2nd St.");
        
        Contact[] inputs = {dickens, adams, charles, holmes, baker};   ➁
        
        MailingList ml = new MailingList();
        
        for (int i = 0; i < inputs.length; ++i) {
            ml.addContact(inputs[i]);
        }
        MailingList ml0 = (MailingList)ml.clone();
        
        // Add a duplicate
        ml.addContact(baker);                                          ➂
        assertEquals(ml0.size(), ml.size());
        assertEquals(ml0, ml);                                         ➃
        assertEquals(ml0.hashCode(), ml.hashCode());
        assertTrue (ml.contains(baker.getName()));
        assertEquals (baker, ml.getContact(baker.getName()));
        assertTrue(ml.toString().contains(baker.getName()));
    }

➀ Again, we set up a bunch of contacts and ➁ establish an order in which we will add them.
➂ It’s not until we get here that we actually invoke the case that we want to test.
➃ After which we basically assert that adding a duplicate does not change the mailing list in any way.

Look at how much of that test was devoted to the setup, much of which was identical to the setup of the previous testAddContact case. Looking ahead, we can guess that we will need much of the same setup for test cases for removeContact as well.

1.5.4 Collecting common setup code into a test fixture

A test fixture in unit testing is a reusable collection of data that provides support for running multiple tests.

In JUnit, we create test fixtures by

Declaring the shared data values as members of the test class.
Initializing them before each test case using a @BeforeEach function, and
If necessary, cleaning them up after each test using an @AfterEach function.

So, if we create this fixture near the top of the test class:

class TestMailingList {
    
    Contact holmes;
    Contact adams;
    Contact baker;
    Contact charles;
    Contact dickens;
    Contact adams2;
    
    Contact[] inputs;

    MailingList ml;
    
    @BeforeEach
    void setup() {
        holmes = new Contact("Holmes", "21B baker St.");
        adams = new Contact("Adams", "21 Pennsylvania Ave.");
        baker = new Contact("Baker", "Drury Ln.");
        charles = new Contact("Charles", "100 1st St.");
        dickens = new Contact("Dickens", "200 2nd St.");
        adams2 = new Contact("Adams", "32 Pennsylvania Ave.");
        
        Contact[] order = {dickens, adams, charles, holmes, baker}; 
        inputs = order;
        
        ml = new MailingList();
    }

Then we can simplify our tests:

    @Test
    void testMailingList() {
        assertEquals (0, ml.size());
        assertFalse (ml.contains("Jones"));
        assertNull (ml.getContact("Smith"));
        MailingList ml2 = new MailingList();
        assertEquals (ml2, ml);
        assertEquals (ml2.hashCode(), ml.hashCode());
        assertNotNull(ml.toString());
    }

    @Test
    void testAddContact() {
        ml.addContact(holmes);
        assertEquals (1, ml.size());
        assertTrue(ml.contains("Holmes"));
        assertFalse(ml.contains("Jones"));
        assertEquals (holmes, ml.getContact("Holmes"));
        assertNull (ml.getContact("Jones"));
        assertNotEquals(ml, new MailingList());
        MailingList ml2 = new MailingList();
        ml2.addContact(holmes);
        assertEquals (ml2, ml);
        assertEquals (ml2.hashCode(), ml.hashCode());
        assertTrue(ml.toString().contains("Holmes"));
    }

    @Test
    void testAddContactMulti() {
        for (int testSize = 1; testSize <= inputs.length; ++testSize) {
            MailingList ml0 = (MailingList)ml.clone();              
            ml.addContact(inputs[testSize-1]);
            assertEquals(testSize, ml.size());
            for (int j = 0; j <= testSize-1; ++j) {                 
                assertTrue (ml.contains(inputs[j].getName()), 
                        "failed after adding " + inputs[testSize-1].getName()); 
                assertEquals (inputs[j], ml.getContact(inputs[j].getName()),
                        "failed after adding " + inputs[testSize-1].getName());
                assertTrue(ml.toString().contains(inputs[j].getName()),
                        "failed after adding " + inputs[testSize-1].getName());
            }
            for (int j = testSize+1; j < inputs.length; ++j) {        
                assertFalse (ml.contains(inputs[j].getName()), 
                        "failed after adding " + inputs[testSize-1].getName());
                assertNull (ml.getContact(inputs[j].getName()),
                        "failed after adding " + inputs[testSize-1].getName());
                assertFalse(ml.toString().contains(inputs[j].getName()),
                        "failed after adding " + inputs[testSize-1].getName());
            }
            assertNotEquals(ml, ml0);
        }
    }   
 
    @Test
    void testAddDuplicateContact() {
        for (int i = 0; i < inputs.length; ++i) {
            ml.addContact(inputs[i]);
        }
        MailingList ml0 = (MailingList)ml.clone();
        
        // Add a duplicate
        ml.addContact(baker);
        assertEquals(ml0.size(), ml.size());
        assertEquals(ml0, ml);
        assertEquals(ml0.hashCode(), ml.hashCode());
        assertTrue (ml.contains(baker.getName()));
        assertEquals (baker, ml.getContact(baker.getName()));
        assertTrue(ml.toString().contains(baker.getName()));
    }

1.5.5 Are we keeping the contacts in the proper order?

The documentation of addContact says that we are supposed to keep the contacts in ascending order.

That’s not a problem for addTestContact, because we only have one contact (so it can hardly be out of order!). But it is something that we should be checking in the other two test cases.

But, how can we check that? Take another look at the interface of MailingList. There’s nothing in there that enables us to access all of the contacts. We can only get a Contact is we already know its name. Surely that’s not a good design!

It’s very common to discover flaws in a class’ interface when trying to write the unit tests. That’s because each unit test represents a kind of demonstration of how to use the class’ interface.

If you can’t write a desired unit test, you probably can’t do what you want with the class in the application either.

1.5.6 Providing access to the contacts

As a matter of Java style, when a class holds a collection of smaller items, we provide access to those by adding an iterator to provide access to the contained items and making the container class Iterable.

So, let’s modify the MailingList class accordingly:

public class MailingList implements Cloneable, Iterable<Contact> {

    private LinkedList<Contact> theContacts;

    /**
	 * Create an empty mailing list
	 *
	 */
	public MailingList() {
	    theContacts = new LinkedList<Contact>();
	}

    ⋮

    /**
	 * Provide access to the contacts.
	 */
    @Override
    public Iterator<Contact> iterator() {
        return theContacts.iterator();
    } 
	
}

Now, we can write a test to express the idea that the contacts are kept in order:

    @Test
    void testAddDuplicateContact() {
        for (int i = 0; i < inputs.length; ++i) {
            ml.addContact(inputs[i]);
        }
        MailingList ml0 = (MailingList)ml.clone();
        
        // Add a duplicate
        ml.addContact(baker);
        assertEquals(ml0.size(), ml.size());
        assertEquals(ml0, ml);
        assertEquals(ml0.hashCode(), ml.hashCode());
        assertTrue (ml.contains(baker.getName()));
        assertEquals (baker, ml.getContact(baker.getName()));
        assertTrue(ml.toString().contains(baker.getName()));
        
        Contact[] expected = {adams, baker, charles, dickens, holmes};
        int i = 0;
        for (Contact contact: ml) {
            assertEquals (expected[i], contact);
            ++i;
        }
    }

We’ll start with testAddDuplicateContact because it’s a bit simpler.

The expected array indicates the order in which we expect to see the various contacts.
The loop goes through the contacts in the mailing list one at a time, checking each one against the next element of expected.

Because this kind of comparison is so common, JUnit has an assertion specifically for that purpose:

    @Test
    void testAddDuplicateContact() {
        for (int i = 0; i < inputs.length; ++i) {
            ml.addContact(inputs[i]);
        }
        MailingList ml0 = (MailingList)ml.clone();
        
        // Add a duplicate
        ml.addContact(baker);
        assertEquals(ml0.size(), ml.size());
        assertEquals(ml0, ml);
        assertEquals(ml0.hashCode(), ml.hashCode());
        assertTrue (ml.contains(baker.getName()));
        assertEquals (baker, ml.getContact(baker.getName()));
        assertTrue(ml.toString().contains(baker.getName()));
        
        Contact[] expected = {adams, baker, charles, dickens, holmes};
        assertIterableEquals(Arrays.asList(expected), ml);
    }

The Arrays.asList call converts an ordinary array into something Iterable, which can then be compared directly against the Iterable variable ml.

1.5.7 testAddContactMulti - ordering test

With that, we can then add a similar ordering test to the more complicated testAddContactMulti:

    @Test
    void testAddContactMulti() {
        Contact[][] expected = {{dickens},
                {adams, dickens},
                {adams, charles, dickens},
                {adams, charles, dickens, holmes},
                {adams, baker, charles, dickens, holmes}
        };
        
        for (int testSize = 1; testSize <= inputs.length; ++testSize) {
            MailingList ml0 = (MailingList)ml.clone();              
            ml.addContact(inputs[testSize-1]);
            assertEquals(testSize, ml.size());
            for (int j = 0; j <= testSize-1; ++j) {                 
                assertTrue (ml.contains(inputs[j].getName()), 
                        "failed after adding " + inputs[testSize-1].getName()); 
                assertEquals (inputs[j], ml.getContact(inputs[j].getName()),
                        "failed after adding " + inputs[testSize-1].getName());
                assertTrue(ml.toString().contains(inputs[j].getName()),
                        "failed after adding " + inputs[testSize-1].getName());
            }
            for (int j = testSize+1; j < inputs.length; ++j) {        
                assertFalse (ml.contains(inputs[j].getName()), 
                        "failed after adding " + inputs[testSize-1].getName());
                assertNull (ml.getContact(inputs[j].getName()),
                        "failed after adding " + inputs[testSize-1].getName());
                assertFalse(ml.toString().contains(inputs[j].getName()),
                        "failed after adding " + inputs[testSize-1].getName());
            }
            assertNotEquals(ml, ml0);
            assertIterableEquals(Arrays.asList(expected[i]), ml);
        }
    }

This time we have an array of expected arrays, and after adding i elements from the input, we check the mailing list against expected[i].

1.6 Parameterized Tests

That last test was a bit clunky because it was actually running a whole series of tests on mailingLists that had 1, 2, …, 5 contacts added to them. We can simplify this by using a facility called parameterized tests, which allow us to run a test repeatedly passing a different parameter to the test function each time:

    @ParameterizedTest                                      ➀
    @ValueSource(ints = {1, 2, 3, 4, 5})                    ➁
    void testAddContactMulti(int testSize) {                ➂
        Contact[][] expected = {{dickens},
                {adams, dickens},
                {adams, charles, dickens},
                {adams, charles, dickens, holmes},
                {adams, baker, charles, dickens, holmes}
        };

        MailingList ml0 = (MailingList)ml.clone();
        for (int i = 0; i < testSize; ++i) {                ➃
            ml.addContact(inputs[i]);
        }
        assertEquals(testSize, ml.size());
        for (int j = 0; j <= testSize-1; ++j) {
            assertTrue (ml.contains(inputs[j].getName()));
            assertEquals (inputs[j], ml.getContact(inputs[j].getName()));
            assertTrue(ml.toString().contains(inputs[j].getName()));
        }
        for (int j = testSize; j < inputs.length; ++j) {
            assertFalse (ml.contains(inputs[j].getName()));
            assertNull (ml.getContact(inputs[j].getName()));
            assertFalse(ml.toString().contains(inputs[j].getName()));
        }
        assertNotEquals(ml, ml0);
        assertIterableEquals(Arrays.asList(expected[testSize-1]), ml);
    }

➀ Instead of @Test, we introduce this with @ParameterizedTest.

➁ A parameterized test must have one or more sources. The @ValueSource is probably the easiest one to use. It allows us to supply a stream of “basic” values (ints, strings, etc.).

If you need something more elaborate, @MethodSource allows you to supply a function that generates a series of values of any type you like.

There are other possible sources as well. See the JUnit5 documentation for details.
➂ The sequence of values specified in the source are passed to a function parameter in the test function. (Compare with @Test functions, which never take parameters.)
➃ After that, our code is similar, but simpler because we no longer have the outer loop to explicitly iterate over different test sizes.

Parameterized tests can be useful in introducing boundary and special values testing into our test cases.

1.7 Finishing Up

1.7.1 testClone

Our test for the clone() function starts much like you would expect it to:

    @Test
    void testClone() {
        MailingList ml0 = new MailingList();         ➀
        for (int i = 0; i < inputs.length; ++i) {
            ml0.addContact(inputs[i]);
        }
        MailingList ml = (MailingList)ml0.clone();   ➁
        
        assertThat (ml.size(), is(ml0.size()));      ➂
        assertThat (ml, equalTo(ml0));
        assertThat (ml.hashCode(), equalTo(ml0.hashCode()));
        assertIterableEquals(ml, ml0);
        assertThat (ml.toString(), equalTo(ml0.toString()));
}

➀ Here we set up the parameter for the eventual clone call.
➁ Here we call the function we are trying to test.
➂ Finally, a bunch of assertions indicating that the two mailing lists should be equal after the clone.

Checking for Deep Copy

But the documentation of the MailingList.clone function indicates that it is supposed to carry out a “deep copy”. That means that an implementation like this:

  ⋮
/**
 * Deep copy of the contacts.
 */
public Object clone() {
    MailingList result = new MailingList();
    result.contacts = contacts;
    return result;
}

would not be acceptable, because any subsequent modifications of the clone would also alter the original, and vice-versa. So we should test to be sure that does not happen:

@Test
void testClone() {
    MailingList ml0 = new MailingList();
    for (int i = 0; i < inputs.length; ++i) {
        ml0.addContact(inputs[i]);
    }
    MailingList ml = (MailingList)ml0.clone();

    assertThat (ml.size(), is(ml0.size()));
    assertThat (ml, equalTo(ml0));
    assertThat (ml.hashCode(), equalTo(ml0.hashCode()));
    assertIterableEquals(ml, ml0);
    assertThat (ml.toString(), equalTo(ml0.toString()));

    // clone() should be a deep copy, so changing one list should
    // not affect the other.
    int size = ml.size();
    ml.removeContact(baker);

    assertThat (ml0.size(), is(size));
    assertThat (ml0, not(equalTo(ml)));
    assertTrue (ml0.contains(baker.getName()));
    assertThat (ml0.getContact(baker.getName()), equalTo(baker));
    assertThat (ml0.toString(), not(equalTo(ml.toString())));

    ml = (MailingList)ml0.clone();
    ml0.removeContact(baker);

    assertThat (ml.size(), is(size));
    assertThat (ml, not(equalTo(ml0)));
    assertTrue (ml.contains(baker.getName()));
    assertThat (ml.getContact(baker.getName()), equalTo(baker));
    assertThat (ml.toString(), not(equalTo(ml0.toString())));
    }

Here we modify the clone ml, and then check to be sure the original ml0 was unaffected.
Here we modify the original ml0, and then check to be sure that that clone ml was unaffected.

1.7.2 removeContact & merge

We still need tests for removeContact (both versions) and merge. None of these require any ideas that we have not already examined, so I won’t go through them in detail. The full source code for this example is here:

Contact.java

package mailinglist;
/**
 * A contact is a name and address.
 * <p>
 * For the purpose of this example, I have simplified matters 
 * a bit by making both of these components simple strings. 
 * In practice, we would expect Address, at least, to be a
 * more structured type.
 * 
 * @author zeil
 *
 */
public class Contact 
  implements Cloneable, Comparable<Contact> {

 private String theName;
 private String theAddress;

 /**
  * Create a contact with empty name and address.
  *
  */
 public Contact ()
 {
  theName = "";
  theAddress = "";
 }

 /**
  * Create a contact
  * @param nm  name 
  * @param addr address
  */
 public Contact (String nm, String addr)
 {
  theName = nm;
  theAddress = addr;
 }


 /**
  * Get the name of the contact
  * @return the name
  */
 public String getName()
 {
  return theName;
 }
 
 /**
  * Change the name of the contact
  * @param nm new name
  */
 public void setName (String nm) 
 {
  theName= nm;
 }

 /**
  * Get the address of the contact
  * @return the address
  */
 public String getAddress()
 {
  return theAddress;
 }
 
 /**
  * Change the address of the contact 
  * @param addr new address
  */
 public void setAddress (String addr) 
 {
  theAddress = addr;
 }

 /**
  * True if the names and addresses are equal 
  */
 public boolean equals (Object right)
 {
  Contact r = (Contact)right;
  return theName.equals(r.theName)
     && theAddress.equals(r.theAddress);
 }

 public int hashCode ()
 {
  return theName.hashCode() + 3 * theAddress.hashCode();
 }

 public String toString()
 {
  return theName + ": " + theAddress;
 }
 
 public Object clone()
 {
  return new Contact(theName, theAddress);
 }

 /**
  * Compare this contact to another.
  * Return value > 0 if this contact precedes the other,
  * == 0 if the two are equal, and < 0 if this contact
  * follows the other.  
  */
 public int compareTo (Contact c)
 {
  int nmcomp = theName.compareTo(c.theName);
  if (nmcomp != 0)
   return nmcomp;
  else
   return theAddress.compareTo(c.theAddress);
 }
}

MailingList.java

package mailinglist;

import java.util.Iterator;
import java.util.LinkedList;
import java.util.ListIterator;

/**
 * A collection of names and addresses
 */
public class MailingList implements Cloneable, Iterable<Contact> {

    private LinkedList<Contact> theContacts;

    /**
	 * Create an empty mailing list
	 *
	 */
	public MailingList() {
	    theContacts = new LinkedList<Contact>();
	}

	/**
	 *  Add a new contact to the list. Contacts should be kept in ascending
	 *  order with no duplicates.
	 *  
	 *  @param contact new contact to add
	 */
	public void addContact(Contact contact) {
	    ListIterator<Contact> it = theContacts.listIterator();
	    while (it.hasNext()) {
	        Contact c = it.next();
	        int compared = c.compareTo(contact); 
	        if (compared > 0) {
	            it.previous();
	            it.add(contact);
	            return;
	        } else if (compared == 0) {
	            return;
	        }
	    }
	    theContacts.add(contact);
	}

	/**
	 *  Remove one matching contact 
	 *  @param contact remove a contact equal to contact
	 */
	public void removeContact(Contact contact) {
        ListIterator<Contact> it = theContacts.listIterator();
        while (it.hasNext()) {
            Contact c = it.next();
            int compared = c.compareTo(contact); 
            if (compared > 0) {
                return;
            } else if (compared == 0) {
                it.remove();
                return;
            }
        }
	}

	/**
	 * Remove a contact with the indicated name
	 * @param name name of contact to remove
	 */
	public void removeContact(String name) {
        ListIterator<Contact> it = theContacts.listIterator();
        while (it.hasNext()) {
            Contact c = it.next();
            int compared = c.getName().compareTo(name); 
            if (compared > 0) {
                return;
            } else if (compared == 0) {
                it.remove();
                return;
            }
        }
	}

	/**
	 * Search for contacts
	 * @param name name to search for
	 * @return true if a contact with an equal name exists
	 */
	public boolean contains(String name) {
        ListIterator<Contact> it = theContacts.listIterator();
        while (it.hasNext()) {
            Contact c = it.next();
            int compared = c.getName().compareTo(name); 
            if (compared > 0) {
                return false;
            } else if (compared == 0) {
                return true;
            }
        }
        return false;
	}

	/**
	 * Search for contacts
	 * @param name name to search for
	 * @return contact with that name if found, null if not found
	 */
	public Contact getContact(String name) {
        ListIterator<Contact> it = theContacts.listIterator();
        while (it.hasNext()) {
            Contact c = it.next();
            int compared = c.getName().compareTo(name); 
            if (compared > 0) {
                return null;
            } else if (compared == 0) {
                return c;
            }
        }
        return null;
	}

	/**
	 * combine two mailing lists
	 *
	 */
	public void merge(MailingList anotherList) {
		// For a quick merge, we will loop around, checking the 
		// first item in each list, and always copying the smaller
		// of the two items into result
		LinkedList<Contact> result = new LinkedList<Contact>();
		ListIterator<Contact> thisPos = theContacts.listIterator();
        ListIterator<Contact> otherPos = anotherList.theContacts.listIterator();
        while (thisPos.hasNext() && otherPos.hasNext()) {
            Contact thisContact = thisPos.next();
            Contact otherContact = otherPos.next();
            int comp = thisContact.compareTo(otherContact);
            if (comp == 0) {
                result.add(thisContact);
            } else if (comp < 0) {
                result.add(thisContact);
                otherPos.previous();
            } else {
                result.add(otherContact);
                thisPos.previous();
            }           
        }
        // Now, one of the two lists has been entirely copied. 
        // The other might still have stuff to copy. So we just copy
        // any remaining items from the two lists. Note that one of these
        // two loops will execute zero times.
        while (thisPos.hasNext()) {
            result.add(thisPos.next());
        }
        while (otherPos.hasNext()) {
            result.add(otherPos.next());
        }
        // Now result contains the merged list. Transfer that into this list.
		theContacts = result;
	}

	/**
	 * How many contacts in list?
	 */
	public int size() {
		return theContacts.size();
	}

	/**
	 * Return true if mailing lists contain equal contacts
	 */
	public boolean equals(Object anotherList) {
	    if (!(anotherList instanceof MailingList)) {
	        return false;
	    }
		MailingList right = (MailingList) anotherList;
		if (size() != right.size()) { // (easy test first!)
			return false;
		}
        ListIterator<Contact> thisPos = theContacts.listIterator();
        ListIterator<Contact> otherPos = right.theContacts.listIterator();
        while (thisPos.hasNext() && otherPos.hasNext()) {
            Contact thisContact = thisPos.next();
            Contact otherContact = otherPos.next();
            if (!thisContact.equals(otherContact)) {
                return false;
            }
        }
        return true;
	}

	public int hashCode() {
	    return theContacts.hashCode();
	}

	public String toString() {
		StringBuffer buf = new StringBuffer("{");
		boolean first = true;
		for (Contact c: theContacts) {
		    if (!first) {
		        buf.append(", ");
		    }
		    first = false;
		    buf.append(c.toString());
		}
		buf.append("}");
		return buf.toString();
	}

	/**
	 * Deep copy of contacts
	 */
	public Object clone() {
		MailingList result = new MailingList();
		for (Contact c: theContacts) {
		    result.theContacts.add((Contact)c.clone());
		}
		return result;
	}


	/**
	 * Provide access to the contacts.
	 */
    @Override
    public Iterator<Contact> iterator() {
        return theContacts.iterator();
    } 
	
}

TestMailingList.java

package mailinglist;

import static org.junit.jupiter.api.Assertions.*;

import java.time.Duration;
import java.util.Arrays;

import org.hamcrest.core.IsNull;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ValueSource;

import static org.hamcrest.MatcherAssert.assertThat;                                                                    
import static org.hamcrest.Matchers.*;                                                                                  
import static org.junit.jupiter.api.Assertions.*;

class TestMailingList {
    
    Contact holmes;
    Contact adams;
    Contact baker;
    Contact charles;
    Contact dickens;
    Contact adams2;
    
    Contact[] inputs;

    MailingList ml;
    
    @BeforeEach
    void setup() {
        holmes = new Contact("Holmes", "21B baker St.");
        adams = new Contact("Adams", "21 Pennsylvania Ave.");
        baker = new Contact("Baker", "Drury Ln.");
        charles = new Contact("Charles", "100 1st St.");
        dickens = new Contact("Dickens", "200 2nd St.");
        adams2 = new Contact("Adams", "32 Pennsylvania Ave.");
        
        Contact[] order = {dickens, adams, charles, holmes, baker}; 
        inputs = order;
        
        ml = new MailingList();
    }

    @Test
    void testMailingList() {
        assertEquals (0, ml.size());
        assertFalse (ml.contains("Jones"));
        assertNull (ml.getContact("Smith"));
        MailingList ml2 = new MailingList();
        assertEquals (ml2, ml);
        assertEquals (ml2.hashCode(), ml.hashCode());
        assertNotNull(ml.toString());
    }

    @Test
    void testAddContact() {
        ml.addContact(holmes);
        assertEquals (1, ml.size());
        assertTrue(ml.contains("Holmes"));
        assertFalse(ml.contains("Jones"));
        assertEquals (holmes, ml.getContact("Holmes"));
        assertNull (ml.getContact("Jones"));
        assertNotEquals(ml, new MailingList());
        MailingList ml2 = new MailingList();
        ml2.addContact(holmes);
        assertEquals (ml2, ml);
        assertEquals (ml2.hashCode(), ml.hashCode());
        assertTrue(ml.toString().contains("Holmes"));
    }

    @ParameterizedTest
    @ValueSource(ints = {1, 2, 3, 4, 5})
    void testAddContactMulti(int testSize) {
        Contact[][] expected = {{dickens},
                {adams, dickens},
                {adams, charles, dickens},
                {adams, charles, dickens, holmes},
                {adams, baker, charles, dickens, holmes}
        };

        MailingList ml0 = (MailingList)ml.clone();
        for (int i = 0; i < testSize; ++i) {
            ml.addContact(inputs[i]);
        }
        assertEquals(testSize, ml.size());
        for (int j = 0; j <= testSize-1; ++j) {
            assertTrue (ml.contains(inputs[j].getName()));
            assertEquals (inputs[j], ml.getContact(inputs[j].getName()));
            assertTrue(ml.toString().contains(inputs[j].getName()));
        }
        for (int j = testSize; j < inputs.length; ++j) {
            assertFalse (ml.contains(inputs[j].getName()));
            assertNull (ml.getContact(inputs[j].getName()));
            assertFalse(ml.toString().contains(inputs[j].getName()));
        }
        assertNotEquals(ml, ml0);
        assertIterableEquals(Arrays.asList(expected[testSize-1]), ml);
    }   
 
    
    
    @Test
    void testAddDuplicateContact() {
        for (int i = 0; i < inputs.length; ++i) {
            ml.addContact(inputs[i]);
        }
        MailingList ml0 = (MailingList)ml.clone();
        
        // Add a duplicate
        ml.addContact(baker);
        assertThat(ml.size(), equalTo(ml0.size()));
        assertThat(ml, is(ml0));  // is() == equalTo()
        assertThat(ml.hashCode(), equalTo(ml0.hashCode()));
        assertTrue (ml.contains(baker.getName()));
        assertThat (ml.getContact(baker.getName()), equalTo(baker));
        assertTrue(ml.toString().contains(baker.getName()));
        
        Contact[] expected = {adams, baker, charles, dickens, holmes};
        assertThat(ml, contains(expected));       
    }   
    
    
    @Test
    void testRemoveContactContact() {
        for (int i = 0; i < inputs.length; ++i) {
            ml.addContact(inputs[i]);
        }
        MailingList ml0 = (MailingList)ml.clone();
        
        ml.removeContact(charles);
        Contact[] expected = {adams, baker, dickens, holmes};
        
        assertThat (ml.size(), is(ml0.size()-1));
        assertThat (ml, not(equalTo(ml0)));
        assertFalse (ml.contains(charles.getName()));
        assertNull (ml.getContact(charles.getName()));
        assertThat (ml, contains(expected));   
    }

    @Test
    void testRemoveContactString() {
        for (int i = 0; i < inputs.length; ++i) {
            ml.addContact(inputs[i]);
        }
        MailingList ml0 = (MailingList)ml.clone();
        
        ml.removeContact(dickens.getName());
        Contact[] expected = {adams, baker, charles, holmes};
        
        assertThat (ml.size(), is(ml0.size()-1));
        assertThat (ml, not(equalTo(ml0)));
        assertFalse (ml.contains(dickens.getName()));
        assertNull (ml.getContact(dickens.getName()));
        assertThat (ml, contains(expected));   
    }

    @Test
    void testMerge() {
        for (int i = 0; i < inputs.length; ++i) {
            ml.addContact(inputs[i]);
        }
        int divider = inputs.length / 2;
        MailingList ml1  = new MailingList();
        for (int i = 0; i <= divider; ++i) {
            ml1.addContact(inputs[i]);
        }
        MailingList ml2  = new MailingList();
        for (int i = divider; i < inputs.length; ++i) {
            ml2.addContact(inputs[i]);
        }
        
        MailingList ml0 = (MailingList)ml2.clone();
        
        ml1.merge(ml2);
        
        assertThat (ml1.size(), is(ml.size()));
        assertThat (ml1, equalTo(ml));
        assertThat (ml1.hashCode(), equalTo(ml.hashCode()));
        assertIterableEquals(ml1, ml);
        assertThat (ml1.toString(), equalTo(ml.toString()));
        
        assertThat (ml2.size(), is(ml0.size()));
        assertThat (ml2, equalTo(ml0));
        assertIterableEquals(ml2, ml0);
        
        for (int i = 0; i < inputs.length; ++i) {
            assertTrue (ml1.contains(inputs[i].getName()));
            assertThat (ml1.getContact(inputs[i].getName()), is(inputs[i]));
        }
        
        
        
    }

    @Test
    void testClone() {
        MailingList ml0 = new MailingList();
        for (int i = 0; i < inputs.length; ++i) {
            ml0.addContact(inputs[i]);
        }
        MailingList ml = (MailingList)ml0.clone();
        
        assertThat (ml.size(), is(ml0.size()));
        assertThat (ml, equalTo(ml0));
        assertThat (ml.hashCode(), equalTo(ml0.hashCode()));
        assertIterableEquals(ml, ml0);
        assertThat (ml.toString(), equalTo(ml0.toString()));
        
        // clone() should be a deep copy, so changing one list should
        // not affect the other.
        int size = ml.size();
        ml.removeContact(baker);
        
        assertThat (ml0.size(), is(size));
        assertThat (ml0, not(equalTo(ml)));
        assertTrue (ml0.contains(baker.getName()));
        assertThat (ml0.getContact(baker.getName()), equalTo(baker));
        assertThat (ml0.toString(), not(equalTo(ml.toString())));
        
        ml = (MailingList)ml0.clone();
        ml0.removeContact(baker);
        
        assertThat (ml.size(), is(size));
        assertThat (ml, not(equalTo(ml0)));
        assertTrue (ml.contains(baker.getName()));
        assertThat (ml.getContact(baker.getName()), equalTo(baker));
        assertThat (ml.toString(), not(equalTo(ml0.toString())));
        
        
    }

}

1.8 Is this Overkill?

We’ve illustrated here the mutator/accessor coverage introduced earlier.

Many, perhaps most, ADTs provide a small number of operations that manipulate the data in a non-trivial fashion, and a large number of get/set attribute functions that, conceptually at least, simply store and retrieve a private data member.

For example, suppose we wanted to test the following ADT:

Address.java

package mailinglist;
/**
 * A contact is a name and address.
 * <p>
 * For the purpose of this example, I have simplified matters 
 * a bit by making both of these components simple strings. 
 * In practice, we would expect Address, at least, to be a
 * more structured type.
 * 
 * @author zeil
 *
 */
public class Address implements Cloneable {

    private String name;
    private String streetAddress;
    private String city;
    private String state;
    private String zipCode;

    /**
     * Create an address with all empty fields.
     *
     */
    public Address ()
    {
        name = "";
        streetAddress = "";
        city = "";
        state = "";
        zipCode = "";
    }

    /**
     * Create an address.
     */
    public Address (String nm, String streetAddr, String city, 
            String state, String zip)
    {
        name = nm;
        streetAddress = streetAddr;
        this.city = city;
        this.state = state;
        zipCode = zip;
    }



    /**
     * @return the theName
     */
    public String getName() {
        return name;
    }

    /**
     * @param theName the theName to set
     */
    public void setName(String theName) {
        this.name = theName;
    }

    /**
     * @return the streetAddress
     */
    public String getStreetAddress() {
        return streetAddress;
    }

    /**
     * @param streetAddress the streetAddress to set
     */
    public void setStreetAddress(String streetAddress) {
        this.streetAddress = streetAddress;
    }

    /**
     * @return the city
     */
    public String getCity() {
        return city;
    }

    /**
     * @param city the city to set
     */
    public void setCity(String city) {
        this.city = city;
    }

    /**
     * @return the state
     */
    public String getState() {
        return state;
    }

    /**
     * @param state the state to set
     */
    public void setState(String state) {
        this.state = state;
    }

    /**
     * @return the zipCode
     */
    public String getZipCode() {
        return zipCode;
    }

    /**
     * @param zipCode the zipCode to set
     */
    public void setZipCode(String zipCode) {
        this.zipCode = zipCode;
    }

    /**
     * True if the names and addresses are equal 
     */
    public boolean equals (Object right)
    {
        Address r = (Address)right;
        return name.equals(r.name)
                && streetAddress.equals(r.streetAddress)
                && city.equals(r.city)
                && state.equals(r.state)
                && zipCode.equals(r.zipCode);
    }

    public int hashCode ()
    {
        return name.hashCode() + 3 * streetAddress.hashCode()
        + 5 * city.hashCode()
        + 7 * state.hashCode()
        + 11 * zipCode.hashCode();
    }

    public String toString()
    {
        return name + ": " + streetAddress + ": " 
                + city + ", " + state + " " + zipCode;
    }

    public Object clone()
    {
        return new Address(name, streetAddress, city,
                state, zipCode);
    }

}