Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 29 ยท Quality and pitfalls

Designing Good Tests

Write JUnit tests that read like specifications: clear names, one behavior per test, builders, test doubles, no over-specification and readable failures.

Anyone can make a test pass. The harder skill is writing a test that is still useful two years later, when someone else changes the code and the test is the only thing that tells them what broke. Good tests are short, named after behavior, independent of each other, and fail with a message that points at the problem. Bad tests are long, fragile, and fail in ways that make you open a debugger.

This lesson is fully runnable. Every example uses the real JUnit 6 API on our Java runner, with the same small helper at the bottom of each file that plays the role of Maven, Gradle or your IDE (see Your First JUnit Test). The ideas apply equally to TestNG; only the annotations change.

What makes a test good

Five habits of good tests

Say what The name states the behavior.
One reason to fail One behavior per test.
Independent No test needs another to run first.
Fast Milliseconds, so you run them often.

A fifth habit ties them together. Tests must be readable by a stranger.

1 / 2

Name tests after behavior

A test name is documentation that the compiler never lets rot. Compare these two failures in a build log:

  • testTotal2 FAILED
  • vipCustomerGetsTenPercentOff FAILED

The second one tells you the rule that broke before you open any file. A good pattern is a short sentence in the present tense: rejectsNegativeQuantity, appliesTaxAfterDiscount, emptyCartCostsNothing. JUnit also lets you write @DisplayName("VIP customers get 10% off") when you want spaces and punctuation, which you will meet in Lifecycle, Nested Tests and Display Names.

One behavior per test

A test should have one reason to fail. If a single test checks the subtotal, the discount, the tax and the formatting, the first broken assertion hides the others, and the name cannot describe what went wrong. Several assertions are fine when they describe one behavior (the fields of one returned object, say). Use assertAll for that, so you see every mismatch at once.

Arrange, act, assert, and keep arrange small

The shape from the first lesson still applies, but real tests often drown in setup. When arrange takes twenty lines, the fix is almost never a longer comment. It is a test data builder that produces a sensible default object, so each test mentions only what is different about its scenario.

Builders keep the interesting part visible

Look at how the tests below read. Each one names only the detail it cares about: vip(), withItem(...). Everything else comes from defaults inside the builder. If Order gets a new required field next month, you change one builder instead of forty tests.

Java Behavior-named tests with a builder

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Read the test names aloud: together they are a specification of the pricing rules. The builder is plain Java, no library required; libraries such as Lombok or Instancio only generate the same code.

Test doubles: control what the code talks to

Real code talks to databases, mail servers and clocks. In a unit test you replace those collaborators with test doubles so the test is fast, deterministic and focused. The four common kinds are in the slides above. The names are used loosely in everyday talk, but the differences matter when you choose:

  • A stub answers questions: () -> 20 as a tax rate.
  • A fake is a small working implementation: a HashMap standing in for a database.
  • A spy records what happened, so you can assert it afterwards: a notifier that stores messages in a list.
  • A mock (from a library like Mockito) is a configurable double that can both stub answers and verify calls; see Mocks and Spies with Mockito.

You do not need a library for simple doubles. A hand-written one is plain code you can read, and it makes a good first step before you reach for Mockito. The next example tests a checkout service with all three of the first kinds. The tests check what the user of the service would see (the saved order, the sent message) and avoid reaching inside.

Java A stub, a fake and a spy

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Three small choices make these tests durable:

  1. A fresh double for every test. JUnit creates a new test-class instance for each method, and @BeforeEach rebuilds the objects, so no state leaks between tests.
  2. The stub is a lambda. () -> 20 is easier to read than a class, and it states the scenario right where the service is built.
  3. The notifier assertions are loose on purpose. They check who and which order, not the exact sentence. If a copywriter rewords the email, no test breaks.

Avoid over-specification

A test is over-specified when it fails for reasons that do not matter to the user. Typical causes:

  • Asserting the exact text of a message when only the fact that it was sent matters.
  • Verifying the order of internal calls when the order is an implementation detail.
  • Mocking every collaborator and verifying every interaction, so any refactoring turns the suite red even though behavior is unchanged.
  • Reading private fields through reflection to "check state".

The remedy is to test what the code promises, through its public behavior. A useful self-check: if you restructure the production code without changing what it does, how many tests should break? The right answer is none. Tests that break during a pure refactoring are costing you more than they give.

The opposite error, under-specification, is just as common: assertNotNull(result) passes for almost any result. Pin the value that matters.

Readable failures

When a test fails, the message is your first (often only) clue. Make it carry information:

  • Prefer assertEquals(expected, actual) over assertTrue(a == b). The first prints both values; the second prints nothing useful.
  • Add a message when the values alone do not explain the intent. Pass it as a supplier (() -> "...") when building it is expensive; JUnit only calls it on failure.
  • Use assertAll("heading", ...) to see every wrong field at once.

The example below fails on purpose so that you can compare three messages for the same underlying bug. Run it and read the failure lines.

Java Three ways to report the same bug

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

JUnit does not promise an order, so the lines may appear in a different order from the source. poorMessage says only expected: <true> but was: <false>, which is no help. valuesInTheMessage shows expected: <02108> but was: <2108>, so you can spot the missing zero at once. everyFieldAtOnceWithContext names the scenario, reports only the one wrong field (the city assertion passed) and explains the lesson in your own words. Spending ten seconds on that message saves the next person ten minutes.

A short checklist for reviewing a test

  • Does the name state a behavior a user of the class would recognize?
  • Can you tell what is being tested from the test body alone, without scrolling to a helper?
  • Would it still pass after a harmless refactoring?
  • Would it fail if the behavior broke? (If you are not sure, break the code and see.)
  • Does it run in milliseconds and without the network, a real clock or the file system?
  • Does the failure message tell you what went wrong?

Tests that clear this bar make change cheap. The coverage and mutation testing lesson gives you tools to measure the second and fourth point.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which test name best describes behavior?

    A good name states a rule in plain language, so a red line in the build log tells you what broke without opening the file.
  2. 2. What is the main purpose of a test data builder?

    A builder provides sensible defaults. Tests override only what differs, and a change in the object's constructor is fixed in one place.
  3. 3. A class records every message it is asked to send so the test can inspect them afterwards. Which kind of double is it?

    A spy captures interactions for later assertions. A stub only returns canned answers and a fake is a working lightweight implementation.
  4. 4. Which situation signals an over-specified test?

    Over-specified tests break during harmless refactoring. Test the observable promises of the code instead of its internal steps.
  5. 5. Why is assertEquals("02108", zip) usually better than assertTrue(zip.equals("02108"))?

    assertEquals reports the two values. assertTrue can only report that a condition was false.

Summary

  • Name tests after behavior, test one behavior each, and keep every test independent of the others.
  • Use builders so tests show only the details that matter, and create fresh objects in @BeforeEach.
  • Choose the simplest double: stub for answers, fake for a working stand-in, spy for recorded calls, mock library when interactions are the point.
  • Test promises, not internals: a pure refactoring should not break tests.
  • Invest in failure messages: assertEquals over assertTrue, assertAll for related fields, a supplier message for intent.
  • Every example here ran on the real JUnit 6 API; only the runner glue stands in for your build tool.

Next: Flaky Tests and Common Mistakes, the ways good-looking tests quietly turn unreliable.