...
Unit Test Guideline
...
From the very start, a part of our development process has been to use unit tests to validate our coding. While we have had to learn some lessons about how to properly make unit tests (some of which lessons are not fully reflected in old tests yet), our overall experience is that unit tests have been a great boon to the stability of our code. We thus encourage others to make use of the unit test framework provided with !NetarchiveSuite. See the "Practical matters" further down for instructions on how to run the unit tests that come with !NetarchiveSuite.==
Motivation and Guide
...
...
What is a unit test?
...
A unit test is an automatically run test of a delimited part (unit) of the code -- a method. Unit tests should be small, run quickly and automatically, not depend on external resources, and not prevent other unit tests from running.
...
The JUnit framework helps streamlining unit tests, and is supported by a number of development environments (IDEs). With it, writing a unit test can be as easy as creating a method that compares the results of running the tested method against expected values. For instance, the below would be a reasonable test method for the `java.lang.String.substring(int, int)` method:{{{
| Code Block |
|---|
public void testSubstring() { |
...
String testString = "teststring"; |
...
assertEquals("Legal substring should be allowed", |
...
"str", testString.substring(4, 7)); |
...
assertEquals("Substring from start should be possible", |
...
"test", testString.substring(0, 4)); |
...
assertEquals("Substring to end should be possible", |
...
"ring", testString.substring(6, testString.length())); |
...
assertEquals("Substring of the empty string should be possible", |
...
"", "".substring(0, 0)); |
...
try |
...
{ testString.substring(-1, 5); |
...
fail("Substring with negative start should be impossible"); |
...
} catch (IndexOutOfBoundsException e) |
...
{ assertTrue("Error message should contain illegal index value", |
...
e.getMessage().contains("-1")); |
...
} try { testString.substring(7, 5); |
...
fail("Substring with end before start should be impossible"); |
...
} catch (IndexOutOfBoundsException e) |
...
{ assertTrue("Error message should contain illegal index difference", |
...
e.getMessage().contains("-2")); |
...
} try { testString.substring(1, 100); |
...
fail("Substring with end too far out should be impossible"); |
...
} catch (IndexOutOfBoundsException |
...
e) { assertTrue("Error message should contain illegal index value", |
...
e.getMessage().contains("100")); |
...
} } |
The standard method name testTestedMethodName is used by JUnit to find tests to run, and by IntelliJ/Eclipse to allow navigation to and direct execution of individual tests. This test first checks standard (successful) usage, on examples of increasing complexity, then goes on to check the error scenarios, making sure that the right exception with the right message is thrown. The ~+`assertEquals`+~, ~+`assertTrue`+~ and ~+`fail`+~ methods are provided by the !TestCase class in JUnit, and take care of formatting an error message in a readable manner. As an example, here is the (first part of the) output of running the testing with the third assertEquals only substringing out to ~+`testString.length() - 1`+~:{{{
| Code Block |
|---|
junit.framework.ComparisonFailure: Substring to end should be possible |
...
Expected:ring |
...
Actual :rin |
...
at dk.netarkivet.tools.UploadTester.testSubstring(UploadTester.java:44) |
...
... |
...
...
Why would you want to do unit tests?
...
Two words: '''Saving time'''. Unit tests increases your development time slightly, but decreases your debugging time significantly. Perhaps more importantly, it reduces the number of bugs that make it into the final code, decreasing customer dissatisfaction, support costs, re-release effort etc.
...
A third reason to create and maintain unit tests is that it provides a safety net for making changes to the code. In the Netarkivet project, we belatedly realized that XML doesn't scale to millions of files very well, and decided to move to using a proper database instead. The database involves 17 interrelated tables. The changeover was done in just a few man-weeks, partly because the data access was abstracted using DAO classes, but also significantly because the usages and assumptions were encoded in unit tests. Whenever code is changed, unit tests can catch unexpected side effects.===
When do you write the unit tests?
...
In the Netarkivet project, we have used a code-unit-tests-first method of implementation. It may seem strange to test something that doesn't exist yet, but such code is actually the easiest to write unit tests for -- there is no implementation there to lead your thinking into specific paths and make you overlook the special cases that cause bugs down the line. Typical method implementation has three steps:1.
- Create the API as a stub method that is guaranteed not to work.
...
- Write a unit test that uses that API -- this test will fail.
...
- Implement the body of the API and see that the unit test passes.
Say that we want to create the method mentioned above that extracts domain names from URLs. The first step is to create the API and make sure it can compile:{{{
| Code Block |
|---|
public class |
...
DomainExtractor { /** This method extracts domain names from URLs. |
...
* * @param URL A string containing a URL, e.g. http://netarkivet.dk/index.html |
...
* @returns A string that contains the domain name found in the URL, e.g. netarkivet.dk |
...
*/ |
...
public String extract(String URL) |
...
{
return null;
}
} |
Next, we create a test class for this method (using JUnit) and implement tests for the functionality. When implementing tests, we should be in the most evil mindtest possible, seeking any way we can think of to make the method do something other than it claims it does.{{{
| Code Block |
|---|
public class DomainExtractorTester extends TestCase { |
...
public void testExtract() |
...
{ DomainNameExtractor dne = new DomainNameExtractor(); |
...
assertEquals("Must extract simple domain", "netarkivet.dk", |
...
dne.extract("http://netarkivet.dk/index.html")); |
...
assertEquals("Must extract long domains", "news.bbc.co.uk", |
...
dne.extract("http://news.bbc.co.uk/frontpage")); |
...
assertEquals("Must not depend on trailing slash", "test.com", |
...
dne.extract("http://test.com")); |
...
assertEquals("Must keep www part", "www.test.com", |
...
dne.extract("http://www.test.com")); |
...
}
} |
The ~+`assertEquals`+~ method inherited from test case takes three arguments: An explanatory message that tells us what we're testing for, the value that we expect to get from the test, and the actual value that the test gave us (in this case the return value of a method call).
At this point, we may realize that the method API does not specify what happens if we give it something that is not a URL, like "www.test.com". Does it throw an exception? Does it return null? Does it return some arbitrary part of the argument? Specifying error behaviour is as much a part of specifying the methods behaviour as saying what it does on the "good" cases. Also, what if the URL is not an HTTP URL, like "[[mailto:owner@test.com|mailto:owner@test.com]]"? Possibly we were really just thinking of HTTP URLs, but then we need to specify that, too. These realizations should go into the javadoc at once, and the test should be expanded to check them (not shown here).
...
Once the implementation is done, the unit test of course must pass.===
This seems complex, why would you want to code unit-test-first?
...
The above example might look like there's a lot of coding to unit tests, and I cannot pretend that there isn't some coding. However, two factors ameliorate it: Firstly, a lot of the framework of the tests can be provided by a good IDE, secondly, unit test code is not production code and does not need to meet as rigorous a standard -- this can even make it quite fun to make unit tests, firing off one mean example after another.
...
A third advantage of doing unit tests first is that it forces the programmer to break the design down to manageable pieces. If a method is too complex to test, it is probably too complex to debug. If a method is hard to test due to complex interrelations with other methods, those same interrelations would be a source of hard-to-find bugs. On the other hand, a method that is easily tested can also more easily be reused in other contexts, as its behaviour is well known.===
What are important things to keep in mind when making unit tests?
...
'''Make the test as simple as possible, but not simpler.''' Each test should test only one method, not the methods that the tested method calls. Look at what the method /itself/ does and test that. Also, check what the method promises in its !JavaDoc and disregard that which is promised by those methods called in turn by the tested method.
...
'''Don't try to prove a negative.''' It's tempting to test that a method call don't change things it's not supposed to, but you can't really do that. Any method can change all manner of things, if it really wants to, and you cannot check them all. Only if the !JavaDoc or other design contract explicitly states that some parts are unchanged should that be checked.===
How do you make a unit test for X?
...
We've run across many different kinds of code to make unit tests, and found solutions to at least some of them.
Interaction with external resources:: When writing code that interfaces with external resources, the easiest way to test that ''your'' code works (don't attempt to unit test an Oracle database installation:) is to provide a mock object that emulates the resource. If you code is cleanly written, this is likely to be easy. A mock object is an object that can be used instead of the real thing, but has much reduced functionality. For instance, it may give pre-calculated answers to the specific calls that the unit tests make, or it may give dummy answers and count how many times it has been called. A generic system for mock objects is available at [[http://www.mockobjects.com|mockobjects.com]].
Exceptions:: Don't catch exceptions unless either the test should throw one, or catching is required for cleanup. The latter should be very rare, as cleanup properly is the province of ~+`tearDown()`+~. Particularly, accidentally catching the exception thrown by ~+`assertX()`+~ or ~+`fail()`+~ will abort the tests with no explanation as to why. When a method specifies that it throws exceptions under certain circumstances, the correct way to test it is this:{{{
try {
| Code Block |
|---|
try { myInstance.doWork(somethingAwful("green")); |
...
fail("Should have thrown GotSomethingAwfulException when given something awful to work on."); |
...
} catch (GotSomethingAwfulException e) |
...
{ assertEquals("Exception should remember color of awful thing", "green", e.getColor()); |
...
} |
}}}
Trying to catch other exceptions leads to extra code with no gain, confusion about the interface, tests that fail in intractable ways, and incomprehensible tests. The above style should be used exactly for when the method ''should'' throw an exception according to its API.
`System.exit`:: While calling `System.exit()` is frowned upon in server applications, you will also sometimes want to test command-line tools or other systems where `System.exit()` may reasonably be called. We have created a standard class that uses a !SecurityManager to catch `System.exit()` calls, which would otherwise abort the entire test run. This can be extended to indicate whether a `System.exit()` call was expected or not.===
What are unit tests not good for?
...
There Is No Silver Bullet, of course. Unit tests can help you get better code, but it can only go so far. There are several types of problems that are difficult or even impossible to really test for in unit tests, and such untestable parts should be noted for testing in larger-scale tests.
Parallelization:: Interactions of multiple threads, or worse, multiple processes, are difficult at best to test. Many of our attempts have ended with tests that pass only occasionally, or that sometimes hang the test system. We have a few ideas that work, though:
* Make sure the threads have recognizable names, and if the threads are expected to terminate, wait in a loop till they have. Make sure to have a timeout on it, though.
Complex interactions:: Despite the best design efforts, some errors only occur when multiple components are put together. Even if each component does its part perfectly well, misunderstandings of designs and assumptions can cause unexpected behaviour. This is properly the field of integration tests. Some errors also come up because the unit test writer didn't think of every possible case, but in that case the unit test can later be extended to cover other cases.
External resources:: Interactions with name servers, databases, web services or other resources that either are slow or unpredictable should be avoided, as it complicates the setup and makes spurious errors more likely. Such resources can sometimes be replaced with mock-ups that give the answers that the tested methods expect.
Hardware-dependent problems:: Some bugs only occur on some platforms or when specific hardware is in use. For instance, Windows has mandatory locking that can make cause the `File.delete()` method to fail until the lock is released. This is not a problem under Unix, so our unit tests never attempted to test that problem. Much as Java would like to be truly platform-independent, there are always some differences.
Scaling:: Scalability issues are typically hard to test for within the time constraints of unit tests.
== Practical matters ==
All our unit tests are placed under the `tests` directory (along with some integrity tests), using a directory structure that mimics the classes they test (such that they can access package-private members). Each package contains an `XTesterSuite` class, where X is the module name and the last part of the package name. This class assembles the tests in that package as one bundle of tests, but also allows the tests to be run as a separate suite. Typically, each package also has a `TestInfo` class that contains various useful constants (names of test data files, for instance), and a `data` directory containing all test data for that package (but not its subpackages). The tests for a class `X` are placed in a class `XTester`, with each method `fooBar()` being tested by one or more methods whose name begins with `testFooBar` (incidentally, this format is understood by the !UnitTest IntelliJ plug-in).===
Running unit-tests
...
The unit tests can be run using the Ant target "unittest". Other test suites can be run as ''ant test -Dsuite=${SUITE-CLASS}'', where SUITE-CLASS is the class name with the dk.netarkivet prefix removed. ''Eg. ant unittest'' corresponds to ant test -Dsuite=!UnitTesterSuite.
If you want to run the unit tests in another manner, e.g. from within your development environment, run the class `dk.netarkivet.tests.UnitTesterSuite` with the following java parameters:{{{
| Code Block |
|---|
- |
...
Xmx700m -Ddk.netarkivet.settings.file=tests/dk/netarkivet/test-settings.xml |
...
-Dorg.apache.commons.logging.log=org.apache.commons.logging.impl.Jdk14Logger |
...
-Djava.util.logging.config.file=tests/dk/netarkivet/testlog.prop |
...
-Djava.security.manager |
...
-Djava.security.policy=tests/dk/netarkivet/test.policy |
...
-Dorg.archive.crawler.frontier.AbstractFrontier.queue-assignment-policy=org.archive.crawler.frontier.HostnameQueueAssignmentPolicy,org.archive.crawler.frontier.IPQueueAssignmentPolicy,org.archive.crawler.frontier.BucketQueueAssignmentPolicy,org.archive.crawler.frontier.SurtAuthorityQueueAssignmentPolicy,org.archive.crawler.frontier.TopmostAssignedSurtQueueAssignmentPolicy,dk.netarkivet.harvester.harvesting.DomainnameQueueAssignmentPolicy |
}}}
It is recommended to also use the option `-Ddk.netarkivet.testutils.runningAs=NONE` to avoid running unit tests that are not expected to pass.===
Running Integrity-tests
...
To run the integrity-test it's assumed you have a running FTP server and JMS broker.
...
The JMS broker should be setup with a broker where username 'controlRole' and password 'R_D' is assigned and run on port 7676.===
Excluded tests
...
We have a system for excluding unit tests from execution when they either depend on external issues or belong to code that is still under development. This prevents the unit test suite from being 'polluted' by tests that are not yet expected to work. A test can be excluded by using the `dk.netarkivet.testutils.runningAs` method:{{{
| Code Block |
|---|
if (!TestUtils.runningAs("LC")) { |
...
return; |
...
} |
...
This causes the test to end successfully unless the tests are run as the user `LC`. The tests can be run either as a specific user, as NONE or as ALL, by setting the property `dk.netarkivet.testutils.runningAs`, e.g. `-Ddk.netarkivet.testutils.runningAs=LC`. When run as ALL, every unit test regardless of exclusion is run -- this is used for the daily regression tests. When run as NONE, no excluded tests are run. Typically, a developer would run the unit test suite as him- or herself to see ones own failing tests but not be distracted by other developers failing tests.
In order to avoid excessive exclusion, it is a good idea to generate a list of which exclusions are in place by grepping for 'testutils.runningAs' in the source. At release time, only exclusions stemming from problems that cannot be solved yet and that are not blocking the release should be in place.===
Private methods
...
Private methods are just as deserving as public methods of being tested, but due to Java's lack of a "friend" concept, they cannot be directly accessed from other classes. Instead, we have a utility class `ReflectUtils` that provides methods for accessing private methods as well as private fields (for easier setup). An example of using reflection for tests could be:{{{
hc =
| Code Block |
|---|
hc = HarvestController.getInstance(); |
...
Field arcRepController = ReflectUtils.getPrivateField(hc.getClass(), |
...
"arcRepController"); |
...
final List<File> stored = new ArrayList<File>(); |
...
arcRepController.set(hc, new MockupJMSArcRepositoryClient(stored)); |
...
Method uploadFiles = ReflectUtils.getPrivateMethod(hc.getClass(), |
...
"uploadFiles", List.class); |
...
uploadFiles.invoke(hc, list(TestInfo.CDX_FILE, TestInfo.ARC_FILE2); |
...
assertEquals("Should have exactly two files uploaded", |
...
2, stored.size()); // Set as sideeffect by mockup |
...
... |
...
JUnit assertions
...
JUnit comes with a base package of useful assertions, but we have over time crystallized out more assertions. These all live in the ~+`dk.netarkivet.testutils`+~ package, which is placed together with the tests. Along with a number of miscellaneous support utilities and mock-ups (described below), there are the following new asserts in the testutils package:
ClassAsserts:: The assertions in here (`assertHasFactoryMethod`, `assertSingleton`, and `assertPrivateConstructor`) pertains mainly to singleton objects, of which there is a small handful in the system. The `assertEquals` method tests via reflection that the `equals` method obeys the requirements from `Object.equals`.
CollectionAsserts:: The `assertIteratorEquals` and `assertListEquals` methods provide more detailed messages about differences in iterators and lists than just doing `equals`. The `assertIteratorNamedEquals` is for specific use by `HarvestDefinitionDAOTester`.
FileAsserts:: These methods help inspecting test results that reside in files. The `assertFileNumberOfLines` method checks the number of lines in a file without holding the whole file in memory. The other methods are utility methods that provide more informative error messages for tests of whether files contain strings or match regular expressions.
MessageAsserts:: The one assert method here checks the generic JMS message class !NetarkivetMessage for whether a reply was successful and outputs the error message from it if not.
StringAsserts:: The three utility methods here are similar to those of `FileAsserts` in that the provide better error messages for string/regexp matching.
XmlAsserts:: These assertions help test XML structures. The `assertElementHasAttribute` and `assertElementHasNotAttribute` check for the presence of a given attribute and whether it does or does not have a given text. Similarly, the `assertNoNodeWithXPath` and `assertNodeWithXPath` methods test whether or not a node exists in a document corresponding to a particular XPath string, and the `assertNodeTextInXPath` checks if an existing node contains a specific test.===
Mock-ups
...
As using objects in their normal contexts became more and more difficult in an increasingly complex system, we turned to [[http://www.mockobjects.com/|mock objects]] to simplify unit tests. Additionally, we have standardized some of our most common set-up/tear-down procedures into objects of their own. An examples of how we are using this can be seen in the test class ~+`dk.netarkivet.common.utils.StreamUtilsTester.java`+~ and the tests found in the test package ~+`dk.netarkivet.harvester.webinterface`+~.