Exercise: The Package Tracker
Take the depot's ticket: packages that need a signature are now held at the depot, and released again. Add the new status to a working package whose every method checks its status, without re-checking the statuses that already work, with every arrow of the state diagram tested throughout.
Journeyman · C# · Java · Python · JavaScript · TypeScript · Updated
The depot manager has a ticket for you. Packages that need a signature, when nobody's home, now come back to the depot and wait there until they go out again. That's a new status for the tracker. The tracker's code works today, and its tests check every arrow on the package's state diagram; your job is to add the new status without breaking any of them, and without having to re-check the statuses that already work.
Before you start
You need one language set up, as in Setup: VS Code and Your Language, and to know how to run the tests, as in Running the Exercise Tests. The exercise is written in all five of the course's languages; pick the one you use.
Get the exercise code
Open this lesson's GitHub repository, github.com/ask-codey/exercise-dp-package-tracker, also linked from the Exercise box beside the lesson. Clone it into your course folder. In a terminal, in that folder:
git clone https://github.com/ask-codey/exercise-dp-package-tracker.git
Git makes a folder, exercise-dp-package-tracker, with the exercise code inside.
The repository has a folder for each language: csharp, java, python, javascript and typescript. Each folder holds:
- the tracker's code, as it is today: a
Packagewith a method for each thing that can happen to it (the repository'sREADME.mdnames the files for each language); - the tests, which you don't need to change;
- a demo program: package 42's day, with a stop back at the depot.
In VS Code, choose File > Open Folder and open your language's folder, not the whole repository.
The ticket
From: the depot manager, Lakeside Parcel
New status: held at the depot. The depot team's scanner already calls
hold()when a shipped package comes back in, andrelease()when it goes out again, but they don't do anything yet.
- Only a shipped package can be held. A held package's status is
held at the depot.- A held package can only be released, which puts it back
out for delivery. It can't be loaded, dropped off or canceled while it's held.Everything that works today has to keep working, exactly as the state diagram says. And last time we added a status, cancel broke for packages nobody touched. Adding this one shouldn't mean re-checking every other status.
The state diagram
These are the arrows the tests check, with the ticket's two new ones last. Anything that isn't an arrow here is refused, with a message such as Package 42: can't cancel, it's shipped:
| From | Event | To |
|---|---|---|
| (start) | ordered | |
| ordered | ship | shipped |
| ordered | cancel | canceled |
| shipped | load | out for delivery |
| out for delivery | drop off | delivered |
| delivered | return | returned |
| shipped | hold (new) | held at the depot |
| held at the depot | release (new) | out for delivery |
The repository's README.md has the same diagram drawn with Mermaid, which GitHub shows as a picture. Sketch the new box and its two arrows on paper before you write any code.
What to do
- Run the tests first. Six pass: every arrow the tracker has today, and every request it refuses. Four fail: they're the ticket.
- Read the code and find the smell. How many places would a new status have to be added? What happens in a method that doesn't know a status?
- Change the code in small steps, and run the tests after every step. The six that pass must stay green the whole time.
- Stop when all ten are green and the demo prints what When you're done shows.
The README's Stuck? section names the pattern, if you want it. Try a few minutes without it first.
Check your work
Each language has its own command, run in the terminal in your language's folder (Terminal > New Terminal in VS Code). The repository's README.md has the full list, including the one-time setup for Python (a virtual environment and pytest) and TypeScript (npm install).
| Language | Run the tests | Run the demo |
|---|---|---|
| C# | dotnet test |
dotnet run --project PackageTracker |
| Java | ./mvnw test (.\mvnw test in PowerShell) |
java src/main/java/Demo.java |
| Python | python -m pytest |
python demo.py |
| JavaScript | npm test |
node demo.js |
| TypeScript | npm test |
node demo.ts |
A failing test's message starts with Not yet: for the ticket's work, or Keep this working: if a change broke something that worked, and names the arrow it expected, for example Not yet: shipped --hold--> held at the depot.
Hints
- Change the shape before you add the status. First make the five statuses you have work a new way, with all six tests still green. Then add the new one.
- Every box on the diagram could be its own piece of code that knows its own arrows, and nothing else.
- A missing arrow is the usual case. Most requests aren't allowed from most statuses. Can "not from here" be written once, instead of in every status?
- The package itself shouldn't need to know any status by name once you're done.
When you're done
All 10 tests are green, and the demo prints the same five lines in every language:
Package 42: shipped
Package 42: held at the depot
Package 42: can't load, it's held at the depot
Package 42: out for delivery
Package 42: delivered
held at the depot is one new piece of code, and the statuses you didn't open still pass every test. The next status on the depot manager's list, "at customs", will be the same small job.
Submit your exercise
The exercise is how you finish this lesson. When your work is done, put it on GitHub in a repo of your own, then submit that repo's address here.
On GitHub, click +, then New repository. Name it (for example
exercise-dp-package-tracker), choose Public, and click Create repository. Leave out the README: your folder already has one.In a terminal in your exercise folder (Git Bash on Windows), send your work to your new repo. Point your copy at your own repo, then commit and push:
git remote set-url origin https://github.com/your-name/exercise-dp-package-tracker.git git add . git commit -m "My solution" git push -u origin mainPaste your repo's address, such as
https://github.com/your-name/exercise-dp-package-tracker, into Submit your exercise on this page. The site checks that the repo is public and holds your commits, and then the lesson is complete.
Changed something after you submitted? Push it, and submit again: your latest submission is the one that counts.
So what
The state diagram was the spec, the tests checked every arrow on it, and the new status went in without anyone re-checking the old ones. That's the payoff of giving each status its own home: a change to one can't quietly break another.