A Whirlwind Introduction to JUnit

Import the JUnit classes so you can use them in your code.

import student.TestCase;
...

Your class should be named using the JUnit convention with the name of the class you are testing followed by the word Test.

If you class is named Student, then your test will be named StudentTest.

import student.TestCase;

public class StudentTest
    extends TestCase
{
    // code goes here...
}

Test cases are defined using methods with names that start with test...().

Typically, your method will be named following the method you are testing in your source code. The example to the right tests the setName() method, so it is called testSetName(). For more complicated methods, you may have many tests (e.g., testFoo1(), testFoo2(), testFoo3(), etc.).

You have to test your assumptions/expectations of your code using an assertXXX() method call. These are provided by the TestCase base class.

import student.TestCase;

public class StudentTest
    extends TestCase
{
    private Student aStudent;

    public void setUp()
    {
        // fixture to be used for testing
        aStudent = new Student("Joe", "888-2993");
      }

    public void testSetName()
    {
        aStudent.setName("Manuel");
        assertEquals(aStudent.getName(), "Manuel");
    }
}

Import the JUnit classes so you can use them in your code.

import student.TestCase;

public class StudentTest
    extends TestCase
{
    // code goes here...
}

Fixtures are objects that are used in your test cases.

Define your fixtures as private fields in your test class (instance variables).

Initialize your fixture in the setUp() method.

The setUp() method is called automatically before each test method is executed, to ensure each test operates on a clean set of freshly initialized objects.

import student.TestCase;

public class StudentTest
    extends TestCase
{
    private Student aStudent;  // fixture to be used for testing

    public void setUp()
    {
        // initialize it here
        aStudent = new Student("Joe", "888-2993");
    }
}

The two test cases on the right run succesfully, since they each start with a freshly generated copy of the aStudent object.

...
    public void testSetName()
    {
        assertEquals(aStudent.getName(), "Joe");

        aStudent.setName("Manuel");
        assertEquals(aStudent.getName(), "Manuel");
    }

    public void testSomethingElse()
    {
        // aStudent .. is new here
        assertEquals(aStudent.getName(), "Joe");
        assertEquals(aStudent.getID(), "888-2993");
    }
}

Consider this simple piece of code.

public class HelloWorld
{
    public static void main(String[] args)
    {
        System.out.println("Hello world!");
    }
}

Themain() method is just a static method, so you can call it directly like any other. Don't forget its argments!

import student.TestCase;

public class HelloWorldTest
    extends TestCase
{
    public void testMain()
    {
        // call main()!
        HelloWorld.main(null);
    }
}

The student.TestCase base class provides for capturing all output sent to System.out during a test case. The history contents are reset before every test method automatically.

Note that if you are using assertEquals(), the expected output must match exactly, character for character, including all newlines.

Also note that systemOut()'s history is automatically normalized to represent newlines as "\n", regardless of platform, so just use \n in any expected values.

    public void testMain()
    {
        HelloWorld.main(null);

        // Can combine these into one line if needed
        String output = systemOut().getHistory();
        assertEquals("Hello world!\n", output);
    }

The student.TestCase base class provides an assert method called assertFuzzyEquals() that performs more lenient string comparisons. It ignores all differences in capitalization, punctuation, or extra spacing, as well as all whitespace at the beginning and ending of strings.

The exact details of what features are ignored in fuzzy comparisons are programmable if necessary. See the API for the StringNormalizer class and for TestCase for more details.

    public void testMain()
    {
        HelloWorld.main(null);
        assertFuzzyEquals("hello world", systemOut().getHistory());
    }

You can even change all your assertEquals() calls to use "fuzzy" comparisons, if you want.

    public void testMain()
    {
        HelloWorld.main(null);

        // Preferably, put this in the constructor or setUp(), since
        // it will affect all assertEquals() that come after it,
        // unless you turn it off again:
        setUseFuzzyStringComparisons(true);        

        // Now performs a fuzzy comparison:
        assertEquals("hello world", systemOut().getHistory());
    }

The student.TestCase base class provides some helpers for more advanced string tests, including one for regular expression testing (giving better failure messages than just using the methods in the String class).

    public void testMain()
    {
        HelloWorld.main(null);
        assertTrue(equalsRegex(systemOut().getHistory(), "[Hh]ello\s.*"));
    }

Consider this simple piece of code.

public class HelloWorld
{
    public static void main(String[] args)
    {
        System.out.println("Hello, " + args[0] + "!");
    }
}

You can provide any arguments you want when you call main() in a test case.

    public void testMain()
    {
        HelloWorld.main(new String[] { "Joe" });
        assertEquals("Hello, Joe!\n", systemOut().getHistory());
    }

Consider this simple piece of code.

public class HelloWorld
{
    public static void main(String[] args)
    {
        System.out.println("Hello, " + args[0] + "!");
        System.exit(0);
    }
}

You can provide any arguments you want when you call main() in a test case.

    public void testMain()
    {
        try
        {
            HelloWorld.main(new String[] { "Joe" });
        }
        catch (student.testingsupport.ExitCalledException e)
        {
            // Confirm exit's return value was zero:
            assertEquals(0, e.getStatus());
        }
        // Check the System.out contents, too:
        assertEquals("Hello, Joe!\n", systemOut().getHistory());
    }

Consider this simple piece of code.

import java.util.Scanner;

public class HelloWorld
{
    public static void main(String[] args)
    {
        Scanner in = new Scanner(System.in);

        System.out.print("Enter your name: ");
        String name = in.next();
        System.out.println("Hello, " + name + "!");
    }
}

You can provide your own contents for System.in within your test case if you are using student.TestCase.

    public void testMain()
    {
        setSystemIn("Joe\n");  // Don't forget the newline!
        HelloWorld.main(null);
        assertEquals("Enter your name: Hello, Joe!\n",
            systemOut().getHistory());
    }

You can easily provide multiple lines as well, and setSystemIn() will build the input for you, adding a line terminator at the end of each line.

There's also a multiline() helper method you can use in any other situations where you need to write multi-line strings.

    public void testMain()
    {
        // If you provide multiple strings, a line terminator
        // is automatically added after each one:
        setSystemIn(
            "This is the first line of text.",
            "And this will appear on line two.",
            "",
            "There is a blank line before this one.",
            "You can provide as many as you like."
            );

        ...

        assertEquals(multiline(
            "expected output line 1",
            "expected output line 2",
            "expected output line3"
            ),
            systemOut().getHistory());
    }

Or you can read the input from a text file using fromFile(). Provide a file name, or a File object, as the argument--be sure not to use absolute path names, though, since those are user-specific.

    public void testMain()
    {
        setSystemIn(fromFile("test-input/test3.txt"));
        HelloWorld.main(null);
        assertEquals(fromFile("expected-output/test3.txt"),
            systemOut().getHistory());
    }

Notice that the assert method call in the example shown above includes the full text, including the prompt message. In fact, the prompt message is followed by a space, because that space is part of the prompt itself, but it isn't followed by a newline (the newline is part of what is typed on stdin, not part of what is "printed" by the program). This can be a bit confusing if you have many back-and-forth prompts and responses in a test case action.

Sometimes, it is better to use contains() or endsWith(), rather than testing the entire output using assertEquals().

    public void testMain()
    {
        setSystemIn("Joe\n");
        HelloWorld.main(null);
        asserttrue(systemOut().getHistory().contains("Hello, Joe!"));
    }