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

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Executable documentation

Similar to Executable documentation (20)

Recently uploaded

Recently uploaded (20)

Executable documentation