Java Guild course · Lesson 0003

Lesson 0003 · the graduate requirement

Unit Tests That Earn Their Place

Anyone can reach 100% coverage on Book. The marks are in which cases you chose — and this lesson ends by proving yours were the right ones.

The Graduate requirement is one line: “Write test cases for Book and Library classes.” Every candidate will do this. So it is not where you gain marks — it is where you lose them, by writing the obvious six tests that assert the getters return what the constructor was given.

Step 1 · Create BookTest

Create this file, at exactly this path:

src/test/java/com/solirius/intermediate/library/BookTest.java

The directory already exists from Lesson 0002. Paste the whole file:

package com.solirius.intermediate.library;

import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Nested;
import org.junit.jupiter.api.Test;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertTrue;

@DisplayName("A book")
class BookTest {

    private static final String TITLE = "Dune";
    private static final String AUTHOR = "Frank Herbert";

    private Book aBook() {
        return new Book(TITLE, AUTHOR);
    }

    @Test
    @DisplayName("is available when newly created")
    void isAvailableWhenNewlyCreated() {
        assertFalse(aBook().isBorrowed());
    }

    @Nested
    @DisplayName("when borrowed")
    class WhenBorrowed {

        @Test
        @DisplayName("reports success the first time")
        void reportsSuccessTheFirstTime() {
            assertTrue(aBook().borrowBook());
        }

        @Test
        @DisplayName("refuses a second borrow")
        void refusesASecondBorrow() {
            Book book = aBook();
            book.borrowBook();
            assertFalse(book.borrowBook(),
                    "a book already on loan must not be borrowable again");
        }
    }

    @Nested
    @DisplayName("when returned")
    class WhenReturned {

        @Test
        @DisplayName("refuses if it was never borrowed")
        void refusesIfItWasNeverBorrowed() {
            assertFalse(aBook().returnBook(),
                    "returning a book nobody borrowed must not report success");
        }

        @Test
        @DisplayName("becomes available again")
        void becomesAvailableAgain() {
            Book book = aBook();
            book.borrowBook();
            book.returnBook();
            assertFalse(book.isBorrowed());
        }
    }

    @Test
    @DisplayName("describes itself as available")
    void describesItselfAsAvailable() {
        assertEquals("Dune by Frank Herbert (Available)", aBook().toString());
    }

    @Test
    @DisplayName("describes itself as borrowed")
    void describesItselfAsBorrowed() {
        Book book = aBook();
        book.borrowBook();
        assertEquals("Dune by Frank Herbert (Borrowed)", book.toString());
    }
}

Step 2 · Run it

cd ~/Desktop/java-guild-candidate-test-intermediate-main
mvn test

Expect 8 tests — your 7 plus the golden master from Lesson 0002:

[INFO] Tests run: 8, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS

Tests run: 5 ... in when returned   // actually has 2
Tests run: 2 ... in when borrowed
Tests run: 0 ... in A book           // actually has 3
Tests run: 13, Failures: 0, Errors: 0, Skipped: 0  // the total is right

ls src/test/java/com/solirius/intermediate/library/

Step 3 · Create LibraryTest

src/test/java/com/solirius/intermediate/library/LibraryTest.java

package com.solirius.intermediate.library;

import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;

import java.util.List;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertTrue;

@DisplayName("A library")
class LibraryTest {

    private final Library library = new Library();

    @Test
    @DisplayName("has nothing available when it is empty")
    void hasNothingAvailableWhenEmpty() {
        assertTrue(library.viewAvailableBooks().isEmpty());
    }

    @Test
    @DisplayName("offers an added book as available")
    void offersAnAddedBookAsAvailable() {
        library.addBook(new Book("Dune", "Frank Herbert"));

        List<Book> available = library.viewAvailableBooks();

        assertEquals(1, available.size());
        assertEquals("Dune", available.get(0).getTitle());
    }

    @Test
    @DisplayName("hides a borrowed book, and only that book, from the available list")
    void hidesOnlyTheBorrowedBook() throws Exception {
        library.addBook(new Book("Dune", "Frank Herbert"));
        library.addBook(new Book("Emma", "Jane Austen"));

        library.borrowBook("Dune");

        List<Book> available = library.viewAvailableBooks();
        assertEquals(1, available.size(), "exactly one of the two should remain");
        assertEquals("Emma", available.get(0).getTitle());
    }

    @Test
    @DisplayName("matches a title regardless of case, so users need not type it exactly")
    void matchesATitleRegardlessOfCase() {
        library.addBook(new Book("Dune", "Frank Herbert"));

        assertNotNull(library.searchBook("dune"));
        assertNotNull(library.searchBook("DUNE"));
    }

    @Test
    @DisplayName("returns null when searching for a book it does not have")
    void returnsNullWhenSearchingForAnAbsentBook() {
        assertNull(library.searchBook("Gone With The Wind"));
    }
}

Step 4 · Run the lot

mvn test

[INFO] Tests run: 13, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS

Thirteen: 1 golden master + 7 BookTest + 5 LibraryTest.

Step 5 · Prove your tests are worth having

A green suite tells you nothing on its own. This step is the one that separates these tests from the obvious ones — and it takes four minutes.

Break the production code on purpose, and check that exactly the right test catches it. This is mutation testing, done by hand.

Sabotage 1 · make borrowBook always succeed

In Book.java, replace the body of borrowBook() with:

public boolean borrowBook() {
    isBorrowed = true;
    return true;          // the guard is gone
}

mvn test

[ERROR] BookTest.refusesASecondBorrow
   a book already on loan must not be borrowable again ==> expected: <false> but was: <true>
[ERROR] GoldenMasterTest.behavesAsApproved » Failed Approval
[ERROR] Tests run: 13, Failures: 1, Errors: 1, Skipped: 0

Now put it back and confirm green before continuing.

Sabotage 2 · make viewAvailableBooks ignore the flag

In Library.java, replace the body of viewAvailableBooks() with:

public List<Book> viewAvailableBooks() {
    return new ArrayList<>(books);     // no filtering at all
}

mvn test

[ERROR] LibraryTest.hidesOnlyTheBorrowedBook
   exactly one of the two should remain ==> expected: <1> but was: <2>
[ERROR] GoldenMasterTest.behavesAsApproved » Failed Approval
[ERROR] Tests run: 13, Failures: 1, Errors: 1, Skipped: 0

Again exactly one unit test, and it is the one designed for the job. Restore the code:

git checkout src/main/java/com/solirius/intermediate/library/Book.java \
             src/main/java/com/solirius/intermediate/library/Library.java
mvn test

[INFO] Tests run: 13, Failures: 0, Errors: 0, Skipped: 0
[INFO] BUILD SUCCESS

Step 6 · Commit

cd ~/Desktop/java-guild-candidate-test-intermediate-main
mvn test          # must be green before committing

git add src/test/java/com/solirius/intermediate/library/BookTest.java
git add src/test/java/com/solirius/intermediate/library/LibraryTest.java

git commit -F - <<'EOF'
test: add unit tests for Book and Library

Covers the Graduate requirement; the project had no src/test directory
and "mvn test" reported "No tests to run".

Cases are chosen so that a plausible wrong implementation would fail.
Verified by hand: removing the guard in Book.borrowBook fails exactly
refusesASecondBorrow, and making viewAvailableBooks skip its filter
fails exactly hidesOnlyTheBorrowedBook. The obvious test - borrowing a
fresh book and asserting true - passes against both broken versions,
which is why it is not the one carrying the weight.

These pass against the existing code, so they characterise rather than
drive it. Behaviour that does not yet exist is driven test-first in the
commits that follow.
EOF

git log --oneline

Naming: the part that gets read

An assessor reads your test names as a specification, often without opening the bodies.

Drill

Read this

Carry on

• Reference card: TDD cycle & JUnit 5 card
• Next: Lesson 0004 — Exceptions That Mean Something — the first real red bar

Try inventing your own sabotage: change something in Book or Library and predict which test will catch it before you run mvn test. If nothing catches it, you have found a test worth adding — bring it to me.