Testing Object-Oriented Code
In this pack:
sizing,
notation,
rule strictness.
Overview
A test holds a design in place while the code inside changes. It does
that only when it speaks to an object through its callers' messages and
checks what a caller could see. A test has three moves, in this order:
build what is needed, send one message, check what a caller could see. A
test that reaches inside is tied to one arrangement of the code, so a
tidy-up turns it red although the clinic sees no change. This skill
covers the moves, the names, and the stand-ins a test may use.
When to use
- You are writing a test for a value, an entity, an aggregate or a use
case.
- A small change inside one class turns many tests red.
- A test reads a private field, sends a private message or checks the
order of steps inside a method.
- A test checks that a query was asked, or how many times.
- You are choosing between a dummy, a stub, a spy, a mock and a fake.
- A test is named after a method, a number, or nothing in particular.
- A collaborator is a database, a clock, a notice sender or a library
the clinic does not own.
When not to use
- The code cannot be built in a test without a database, a server or the
real time, and the question is how to change its design so it can:
that is
designing for testability.
- The code has no tests at all and must change now: pinning what it does
before the change is in
working with legacy code.
- A screen, a scheduled job or a message listener needs its framework to
run: layering the system rule 4
keeps such an edge humble.
- The code is an answer used once and thrown away, which the index's
sizing table skips entirely.
Core rules
Rule. Speak to an object only through the messages its callers
send, and check only what one of those callers could see: the answer
it returns, what a later public message answers, or a message it sends
out through a port. Reading a private field, sending a private
message or counting the steps inside a method ties the test to one
arrangement of the code, so a tidy-up breaks it while the clinic's
behaviour stays the same.
Default. Write each test before the code that makes it pass. Run
it and watch it fail for the reason its name states; write the least
code that turns it green; then improve the design while every test
stays green. A test that has never failed has shown nothing.
The exception is code written only to learn something, such as a
trial of how an outside service answers: throw that code away, and
write the version that stays test first.
Rule. Name each test for the behaviour it checks, in the clinic's
words: the situation and the outcome. "A booking into a taken slot
is refused" tells a reader what broke; a number or a bare method name
tells nothing. When a test fails, its name says which rule broke, and
when that rule changes, the names say which tests to open.
Default. Keep the real domain classes in a test, its values,
entities and aggregates, and stand in only for a collaborator the
object reaches through a port, such as a repository, a clock or a
notice sender. A real domain object behaves in the test as it does
in the clinic; a stand-in for one repeats what the test writer
guessed about it. The exception is a role no class plays yet, whose
messages the test is finding out: a stand-in for that role lets the
test say what the object needs from it, and the role becomes a port
the domain owns, as
inverting dependencies
rule 1 asks.
Rule. Choose the kind of stand-in from what the test asks of the
collaborator: a stub returns an answer the test chose to a query; a
fake is a small working version, such as a repository that holds its
aggregates in memory; a spy records the commands it receives for the
test to read afterwards; a mock is told in advance which commands to
expect and fails the test when they do not arrive; a dummy fills a
parameter the test never uses. Never check that a query was sent: a
query changes nothing, as
encapsulating state and behaviour
rule 4 asks, so asking it cannot be behaviour.
Judgement. Check a command by the state it leaves or by the
message it sends. Check the state when an object the test can ask
keeps the outcome, such as a waiting list that no longer holds a
patient; check the message when the outcome leaves through a port and
no class in the clinic keeps it, such as a notice sent to that
patient. What tips the balance is where the outcome lives: checking
messages for an outcome kept as state ties the test to the steps that
reach it.
Rule. Never stand in for a type the clinic's code does not own,
such as a library's client or an outside system's own class: put a
port the clinic owns in front of it, as
inverting dependencies
rule 1 asks, and stand in for the port. A stand-in for a type the
clinic does not own repeats a guess about how that type behaves, and
the tests pass while the real one fails. The adapter that answers the
port is checked against the real outside system in a few slower
tests, and a fake for the same port passes those same tests, so the
two cannot drift apart.
Pattern
Both fences test one step of the aggregates reference: a cancelled
appointment frees a slot, and FreedTimeOffer offers it to the patient
who has waited longest. FreedTimeOffer itself is that reference's
class, unchanged; this skill tests it and adds nothing to it.
Before, the test replaces the waiting list with a subclass, so the real
WaitingList never runs.
Before:
class ScriptedWaitingList extends WaitingList
- next: PatientId
- asked: Boolean
- removed: PatientId?
+ new(next: PatientId)
asked := false
removed := null
+ nextPatient(): PatientId?
asked := true
return next
+ remove(patient: PatientId): void
removed := patient
return
+ wasAsked(): Boolean
return asked
+ removedPatient(): PatientId?
return removed
The test builds ScriptedWaitingList with one patient, hands
FreedTimeOffer the notices stand-in the After fence declares, runs
run, and checks wasAsked() and removedPatient(). It checks that a
query was asked (rule 5) and stands in for a domain class (rule 4), so
it fails if run stops asking nextPatient although nothing a caller
sees changes, and it passes while the real WaitingList.remove is
broken, because the real class never runs. The stand-in reads none of
the fields it inherits, because it overrides every message
FreedTimeOffer sends to the list.
After, the test keeps the real waiting list and records the notice at
the port.
After:
interface Notices
+ send(patient: PatientId, slot: Slot): void
class RecordingNotices implements Notices
- sent: List<PatientId>
+ new()
sent := new List<PatientId>()
+ send(patient: PatientId, slot: Slot): void
sent.add(patient)
return
+ sentTo(): ReadOnlyList<PatientId>
return sent.readOnlyView()
Notices keeps the shape its senders give it in the aggregates
reference, send(patient, slot), and this fence declares only send
because FreedTimeOffer sends only send. WaitingList is the real
class, with the fields, constructor, join and waiting of the
composition skill and the nextPatient and remove of the aggregates
reference. The test builds a real WaitingList, sends it join for one
patient, passes a cancelled appointment, whose freedSlot() the
aggregates reference takes to answer the slot it released, runs run,
and checks two things: sentTo() contains the patient, the message that
leaves through the port (rule 6), and waiting() no longer contains the
patient, the state the list keeps (rule 6). RecordingNotices is a spy
(rule 5) for a port the clinic owns (rule 7). new List<PatientId>() is
taken to mean an empty list that the notices stand-in owns. true and
false are the two values a Boolean holds. Both fences store nothing,
and the caller that saves the list after run is left out.
Red flags
Places to look, not verdicts. A red flag becomes a finding only with
evidence: a measurement, a reproducible bug, or a failing test.
- A test that reads a private field or sends a private message.
- A test that checks a query was asked, or how many times.
- A stand-in that extends a concrete domain class.
- A stand-in for a library's or an outside system's own type.
- Test names such as
test1 or the name of the method alone.
- A test that fails when a method is renamed inside the class.
Common mistakes
- Writing the test after the code and never seeing it fail.
- Replacing values and entities with stand-ins because they have
collaborators.
- Checking every message an object sends, instead of its outcome.
- Keeping a fake that no test compares with the real adapter.
- Putting several behaviours in one test, so its failure names none.
Related skills
Further reading
- Stand-ins
- Test names and shape
1---2name: oo-testing-object-oriented-code3description: Use when writing tests for objects, when tests break although behaviour did not change, or when choosing a mock, stub or fake.4license: MIT5metadata:6 source: https://skillmd.com/skills/yutna/oo-testing-object-oriented-code7 version: 0.21.08 pack: object-oriented-design-skills9---1011# Testing Object-Oriented Code1213**In this pack:**14[sizing](../oo-design/SKILL.md#how-much-design-a-task-warrants),15[notation](../oo-design/references/notation.md),16[rule strictness](../oo-design/SKILL.md#how-strictly-a-rule-is-meant).1718## Overview1920A test holds a design in place while the code inside changes. It does21that only when it speaks to an object through its callers' messages and22checks what a caller could see. A test has three moves, in this order:23build what is needed, send one message, check what a caller could see. A24test that reaches inside is tied to one arrangement of the code, so a25tidy-up turns it red although the clinic sees no change. This skill26covers the moves, the names, and the stand-ins a test may use.2728## When to use2930- You are writing a test for a value, an entity, an aggregate or a use31 case.32- A small change inside one class turns many tests red.33- A test reads a private field, sends a private message or checks the34 order of steps inside a method.35- A test checks that a query was asked, or how many times.36- You are choosing between a dummy, a stub, a spy, a mock and a fake.37- A test is named after a method, a number, or nothing in particular.38- A collaborator is a database, a clock, a notice sender or a library39 the clinic does not own.4041## When not to use4243- The code cannot be built in a test without a database, a server or the44 real time, and the question is how to change its design so it can:45 that is46 [designing for testability](../oo-designing-for-testability/SKILL.md).47- The code has no tests at all and must change now: pinning what it does48 before the change is in49 [working with legacy code](../oo-working-with-legacy-code/SKILL.md).50- A screen, a scheduled job or a message listener needs its framework to51 run: [layering the system](../oo-layering-the-system/SKILL.md) rule 452 keeps such an edge humble.53- The code is an answer used once and thrown away, which the index's54 sizing table skips entirely.5556## Core rules57581. Rule. **Speak to an object only through the messages its callers59 send, and check only what one of those callers could see: the answer60 it returns, what a later public message answers, or a message it sends61 out through a port.** Reading a private field, sending a private62 message or counting the steps inside a method ties the test to one63 arrangement of the code, so a tidy-up breaks it while the clinic's64 behaviour stays the same.65662. Default. **Write each test before the code that makes it pass.** Run67 it and watch it fail for the reason its name states; write the least68 code that turns it green; then improve the design while every test69 stays green. A test that has never failed has shown nothing.70 The exception is code written only to learn something, such as a71 trial of how an outside service answers: throw that code away, and72 write the version that stays test first.73743. Rule. **Name each test for the behaviour it checks, in the clinic's75 words: the situation and the outcome.** "A booking into a taken slot76 is refused" tells a reader what broke; a number or a bare method name77 tells nothing. When a test fails, its name says which rule broke, and78 when that rule changes, the names say which tests to open.79804. Default. **Keep the real domain classes in a test, its values,81 entities and aggregates, and stand in only for a collaborator the82 object reaches through a port, such as a repository, a clock or a83 notice sender.** A real domain object behaves in the test as it does84 in the clinic; a stand-in for one repeats what the test writer85 guessed about it. The exception is a role no class plays yet, whose86 messages the test is finding out: a stand-in for that role lets the87 test say what the object needs from it, and the role becomes a port88 the domain owns, as89 [inverting dependencies](../oo-inverting-dependencies/SKILL.md)90 rule 1 asks.91925. Rule. **Choose the kind of stand-in from what the test asks of the93 collaborator: a stub returns an answer the test chose to a query; a94 fake is a small working version, such as a repository that holds its95 aggregates in memory; a spy records the commands it receives for the96 test to read afterwards; a mock is told in advance which commands to97 expect and fails the test when they do not arrive; a dummy fills a98 parameter the test never uses.** Never check that a query was sent: a99 query changes nothing, as100 [encapsulating state and behaviour](../oo-encapsulating-state-and-behaviour/SKILL.md)101 rule 4 asks, so asking it cannot be behaviour.1021036. Judgement. **Check a command by the state it leaves or by the104 message it sends.** Check the state when an object the test can ask105 keeps the outcome, such as a waiting list that no longer holds a106 patient; check the message when the outcome leaves through a port and107 no class in the clinic keeps it, such as a notice sent to that108 patient. What tips the balance is where the outcome lives: checking109 messages for an outcome kept as state ties the test to the steps that110 reach it.1111127. Rule. **Never stand in for a type the clinic's code does not own,113 such as a library's client or an outside system's own class: put a114 port the clinic owns in front of it, as115 [inverting dependencies](../oo-inverting-dependencies/SKILL.md)116 rule 1 asks, and stand in for the port.** A stand-in for a type the117 clinic does not own repeats a guess about how that type behaves, and118 the tests pass while the real one fails. The adapter that answers the119 port is checked against the real outside system in a few slower120 tests, and a fake for the same port passes those same tests, so the121 two cannot drift apart.122123## Pattern124125Both fences test one step of the aggregates reference: a cancelled126appointment frees a slot, and `FreedTimeOffer` offers it to the patient127who has waited longest. `FreedTimeOffer` itself is that reference's128class, unchanged; this skill tests it and adds nothing to it.129130Before, the test replaces the waiting list with a subclass, so the real131`WaitingList` never runs.132133Before:134135```text136class ScriptedWaitingList extends WaitingList137 - next: PatientId138 - asked: Boolean139 - removed: PatientId?140 + new(next: PatientId)141 asked := false142 removed := null143 + nextPatient(): PatientId?144 asked := true145 return next146 + remove(patient: PatientId): void147 removed := patient148 return149 + wasAsked(): Boolean150 return asked151 + removedPatient(): PatientId?152 return removed153```154155The test builds `ScriptedWaitingList` with one patient, hands156`FreedTimeOffer` the notices stand-in the After fence declares, runs157`run`, and checks `wasAsked()` and `removedPatient()`. It checks that a158query was asked (rule 5) and stands in for a domain class (rule 4), so159it fails if `run` stops asking `nextPatient` although nothing a caller160sees changes, and it passes while the real `WaitingList.remove` is161broken, because the real class never runs. The stand-in reads none of162the fields it inherits, because it overrides every message163`FreedTimeOffer` sends to the list.164165After, the test keeps the real waiting list and records the notice at166the port.167168After:169170```text171interface Notices172 + send(patient: PatientId, slot: Slot): void173174class RecordingNotices implements Notices175 - sent: List<PatientId>176 + new()177 sent := new List<PatientId>()178 + send(patient: PatientId, slot: Slot): void179 sent.add(patient)180 return181 + sentTo(): ReadOnlyList<PatientId>182 return sent.readOnlyView()183```184185`Notices` keeps the shape its senders give it in the aggregates186reference, `send(patient, slot)`, and this fence declares only `send`187because `FreedTimeOffer` sends only `send`. `WaitingList` is the real188class, with the fields, constructor, `join` and `waiting` of the189composition skill and the `nextPatient` and `remove` of the aggregates190reference. The test builds a real `WaitingList`, sends it `join` for one191patient, passes a cancelled appointment, whose `freedSlot()` the192aggregates reference takes to answer the slot it released, runs `run`,193and checks two things: `sentTo()` contains the patient, the message that194leaves through the port (rule 6), and `waiting()` no longer contains the195patient, the state the list keeps (rule 6). `RecordingNotices` is a spy196(rule 5) for a port the clinic owns (rule 7). `new List<PatientId>()` is197taken to mean an empty list that the notices stand-in owns. `true` and198`false` are the two values a `Boolean` holds. Both fences store nothing,199and the caller that saves the list after `run` is left out.200201## Red flags202203Places to look, not verdicts. A red flag becomes a finding only with204evidence: a measurement, a reproducible bug, or a failing test.205206- A test that reads a private field or sends a private message.207- A test that checks a query was asked, or how many times.208- A stand-in that extends a concrete domain class.209- A stand-in for a library's or an outside system's own type.210- Test names such as `test1` or the name of the method alone.211- A test that fails when a method is renamed inside the class.212213## Common mistakes214215- Writing the test after the code and never seeing it fail.216- Replacing values and entities with stand-ins because they have217 collaborators.218- Checking every message an object sends, instead of its outcome.219- Keeping a fake that no test compares with the real adapter.220- Putting several behaviours in one test, so its failure names none.221222## Related skills223224- [oo-design](../oo-design/SKILL.md) sizes a task and defines the rule225 labels.226- [oo-encapsulating-state-and-behaviour](../oo-encapsulating-state-and-behaviour/SKILL.md)227 keeps a query from changing state, which rule 5 relies on.228- [oo-inverting-dependencies](../oo-inverting-dependencies/SKILL.md)229 puts a port beside the domain and an adapter at the edge, which rules230 4 and 7 rely on.231- [oo-designing-interfaces](../oo-designing-interfaces/SKILL.md) shapes232 the port a stand-in answers around the messages its caller sends.233- [oo-layering-the-system](../oo-layering-the-system/SKILL.md) keeps a234 hard edge humble, which is why a screen or a job is not tested in235 depth here.236- [oo-designing-aggregates](../oo-designing-aggregates/SKILL.md) gives237 the freed-time step this skill's Pattern tests, and the waiting list238 it changes.239- [oo-designing-for-testability](../oo-designing-for-testability/SKILL.md)240 changes a design that a test cannot build or control.241- [oo-working-with-legacy-code](../oo-working-with-legacy-code/SKILL.md)242 pins what untested code does before it changes.243244## Further reading245246- [Stand-ins](references/stand-ins.md)247- [Test names and shape](references/test-names-and-shape.md)