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

By

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 Package with a method for each thing that can happen to it (the repository's README.md names 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, and release() 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

  1. Run the tests first. Six pass: every arrow the tracker has today, and every request it refuses. Four fail: they're the ticket.
  2. 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?
  3. Change the code in small steps, and run the tests after every step. The six that pass must stay green the whole time.
  4. 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.

  1. 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.

  2. 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 main
    
  3. Paste 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.

Key terms

Related