Executable documentation

Any fool can write code that a
computer can understand. Good
programmers write code that humans
can understand.
- Martin Fowler

What’s wrong with this test?
@Test
public void testRead() throws Exception {
Mockito.when(eofwatcher.eofDetected(Mockito.<InputStream>any())).thenReturn(Boolean.TRUE);
Mockito.when(instream.read()).thenReturn(0, -1);
Assert.assertEquals(0, eofstream.read());
Assert.assertFalse(eofstream.isSelfClosed());
Assert.assertNotNull(eofstream.getWrappedStream());
Mockito.verify(eofwatcher, Mockito.never()).eofDetected(instream);
Assert.assertEquals(-1, eofstream.read());
Assert.assertNull(eofstream.getWrappedStream());
Mockito.verify(instream, Mockito.times(1)).close();
Mockito.verify(eofwatcher).eofDetected(instream);
}
(from the open-source project HttpClient)

Value of Unit Tests
Prevent Regression
Drive Development Facilitate Refactoring
Document Functionality

Strive for Clean Code
if ((getDate().year – dob.year > 62 || (getDate().year – dob.year == 62
&& getDate().month > dob.month)) && early)
payment = getEarlyPay();
else if ((getDate().year – dob.year > 65 || (getDate().year – dob.year == 65
&& getDate().month >= dob.month)) && !early)
payment = getRegPay();
else
payment = 0;
Duplication

if (getAgeInYears() >= 62 && early)
else if (getAgeInYears() >= 65 && !early)
else
payment = 0;
int getAgeInYears() {
int age = getDate().year – dob.year;
if (getDate().month >= dob.month) age++;
return age;
}
Magic
numbers

final static int EARLY_RETIREMENT_AGE = 62;
final static int REGULAR_RETIREMENT_AGE = 65;
if (getAgeInYears() >= EARLY_RETIREMENT_AGE && early)
else if (getAgeInYears() >= REGULAR_RETIREMENT_AGE && !early)
else
payment = 0; Complex conditional

if (isCollectingEarlyRetirement())
else if (isCollectingRegularRetirement())
else
payment = 0;
boolean isCollectingEarlyRetirement() {
return early && getAgeInYears() >= EARLY_RETIREMENT_AGE);
}
Ambiguous
names

if (isCollectingEarlyRetirement())
payment = getEarlyRetirementPayment();
else if (isCollectingRegularRetirement())
payment = getRegularRetirementPayment();
else
payment = 0;
boolean isCollectingEarlyRetirement() {
return electedEarlyRetirement && getAgeInYears() >= EARLY_RETIREMENT_AGE);
}

Unit Tests are Code
 Choose good method names
 Keep methods short and coherent
 Avoid magic numbers
 Avoid long argument lists
 Avoid duplication

Test One Thing Per Test
@Test
public void afterCellAdded_boardIsAtLeast10x10() {
Board board = new Board();
board.addCell(0, 0);
assertThat(board.getHeight(), is(greaterThan(10));
assertThat(board.getWidth(), is(greaterThan(10));
}
Name describes exactly what is being tested
Set up (could be part of test class setup)
Operation to test
Validation

Hamcrest Library
assertThat(number, both(greaterThan(10)).and(LessThan(30)));
assertThat(array, is(emptyArray());
assertThat(collection, hasItems(1, 4, 7));
assertThat(map, hasKey("color")
assertThat(javaBean, hasProperty("age"));

What’s wrong with this test?
@Test
}

@Test
}
Ambiguous
Sequence of cases
Magic numbers
Confusing Names

EofSensorInputStream
getWatcher()
getWrappedStream()
EofSensorWatcher
InputStream
eofwatcher
instream
Class being tested has two
component classes
wrappedStream
watcher
eofstream

Step 1: fix names
@Test
}

Step 1: fix names
@Test
Mockito.when(watcher.eofDetected(Mockito.<InputStream>any())).thenReturn(Boolean.TRUE);
Mockito.when(wrappedStream.read()).thenReturn(0, -1);
Mockito.verify(watcher, Mockito.never()).eofDetected(wrappedStream);
Mockito.verify(wrappedStream, Mockito.times(1)).close();
Mockito.verify(watcher).eofDetected(wrappedStream);
}

Step 2: magic numbers
@Test
Mockito.when(wrappedStream.read()).thenReturn(0, -1);
}

Step 2: magic numbers
@Test
Mockito.when(wrappedStream.read()).thenReturn(DATA_VALUE, EOF);
Assert.assertEquals(DATA_VALUE, eofstream.read());
Assert.assertEquals(EOF, eofstream.read());
}

Step 3: What’s being
tested?@Test
}

Step 4: Separate the Tests
@Test
}

@Test
public void whenNotAtEOF_readReturnsNextByte() throws Exception {
}

@Test
public void whenNotAtEOF_readReturnsNextByteFromWrappedStream() throws Exception {
wrappedStream.returnOnRead(DATA_VALUE);
}

@Test
assertThat(eofstream.read(), is(DATA_VALUE));
}

@Test
public void whenNotAtEOF_readDoesNotCloseStream () throws Exception {
}
@Test
}

@Test
eofstream.read();
}
@Test
}

@Test
public void afterSuccessfulRead_haveOriginalWrappedStream() throws Exception {
eofstream.read();
assertThat(eofstream.getWrappedStream(), sameInstance((InputStream) wrappedStream));
}
@Test
public void whenNoData_readReturnsEOF() throws Exception {
assertThat(eofstream.read(), is(EOF));
}
@Test
public void afterEofRead_streamIsNotSelfClosed() throws Exception {
eofstream.read();
assertFalse(eofstream.isSelfClosed());
}

@Test
public void afterEofRead_wrappedStreamIsNull() throws Exception {
eofstream.read();
assertThat(eofstream.getWrappedStream(), nullValue());
}
@Test
public void afterEofRead_wrappedStreamIsClosed() throws Exception {
eofstream.read();
assertTrue(wrappedStream.isClosed());
}
@Test
public void afterEofRead_nextReadReturnsEOF() throws Exception {
eofstream.read();
assertThat(eofstream.read(), is(EOF));
}

Tests Document Behavior
whenNotAtEOF_readReturnsNextByteFromWrappedStream
whenNotAtEOF_readDoesNotCloseStream
afterSuccessfulRead_haveOriginalWrappedStream
whenNoData_readReturnsEOF
afterEofRead_streamIsNotSelfClosed
afterEofRead_wrappedStreamIsNull
afterEofRead_wrappedStreamIsClosed
afterEofRead_nextReadReturnsEOF

Unit Tests are Executable Documentation
 Keep the tests clean
 Test one thing per test
 Use descriptive names

Executable documentation

More Related Content

What's hot (20)

Similar to Executable documentation (20)

Recently uploaded (20)

Executable documentation