Lesson 3 of 6
Tests, the README and the Walkthrough Call
Add tests that prove the tool's rules, write the README a marker wants to read, and prepare for the questions a walkthrough call brings.
6 minForward Deployed Engineering
After this lesson you will be able to prove a take-home works with a few tests, write a README that a marker can act on in two minutes, and answer the questions a walkthrough call usually brings.
You continue in the fde-interview folder from lesson 2, which holds reconcile.py, shipments.csv and invoices.csv. If you did the exercise in lesson 2, your report ends with four extra count lines. That changes nothing here.
Test the rules, not the files
A marker will probably run your tool once on the sample files. Tests tell them something a single run cannot: that you know which rules the tool follows, and that each rule holds by itself. Write one test for each assumption you wrote down in lesson 2.
Create test_reconcile.py next to reconcile.py:
import unittest
from reconcile import reconcile
def shipment(shipment_id, amount):
return {"shipment_id": shipment_id, "agreed_amount": amount}
def invoice(invoice_id, shipment_id, amount):
return {"invoice_id": invoice_id, "shipment_id": shipment_id, "amount": amount}
class ReconcileTests(unittest.TestCase):
def test_a_matching_pair_gives_no_findings(self):
found = reconcile([shipment("S-1", "100.00")], [invoice("INV-1", "S-1", "100.00")])
self.assertEqual(found, [])
def test_ids_match_whatever_their_case_and_spacing(self):
found = reconcile([shipment("S-1", "100.00")], [invoice("INV-1", " s-1 ", "100.00")])
self.assertEqual(found, [])
def test_a_comma_in_an_amount_is_not_a_difference(self):
found = reconcile([shipment("S-1", "1250.00")], [invoice("INV-1", "S-1", "1,250.00")])
self.assertEqual(found, [])
def test_a_shipment_with_no_invoice_is_reported(self):
found = reconcile([shipment("S-1", "100.00")], [])
self.assertEqual(found, [("not_invoiced", "S-1", "agreed 100.00")])
def test_a_wrong_amount_is_reported_with_both_figures(self):
found = reconcile([shipment("S-1", "640.00")], [invoice("INV-1", "S-1", "460.00")])
self.assertEqual(found, [("wrong_amount", "S-1", "agreed 640.00, INV-1 says 460.00")])
def test_a_second_invoice_for_one_shipment_is_reported(self):
invoices = [invoice("INV-1", "S-1", "100.00"), invoice("INV-2", "S-1", "100.00")]
found = reconcile([shipment("S-1", "100.00")], invoices)
self.assertEqual(found, [("invoiced_twice", "S-1", "INV-1, INV-2")])
def test_an_invoice_for_an_unknown_shipment_is_reported(self):
found = reconcile([], [invoice("INV-1", "S-9", "100.00")])
self.assertEqual(found, [("unknown_shipment", "S-9", "INV-1")])
if __name__ == "__main__":
unittest.main()Run the tests from the fde-interview folder:
python -m unittestThe output ends like this (the time will differ):
Ran 7 tests in 0.001s
OKLook at what these tests do. Each name is a sentence that states a rule, so a marker who reads only the names learns what the tool promises. Each test builds the one or two rows its rule needs and does not read the sample files, so editing a sample file cannot break a test. And all of them call reconcile directly, which is possible only because lesson 2 kept the comparing apart from the reading and printing.
Seven tests took a few minutes to write. You do not need more for a take-home. You need the ones that match your assumptions.
Write the README
The README is the first thing the marker opens, and it may be the only thing a hiring manager reads. Write it for a person with two minutes. Use these six sections, in this order:
- What it does, in two sentences, in the customer's words.
- How to run it: the exact command, and the output to expect.
- What the sample data shows, stated as findings a finance team could act on.
- Assumptions: the list from your notes.
- What is left out, and what you would do next.
- How long you spent.
Here is the README for this tool. Read it as a model, then write your own in the exercise.
# Shipment and invoice check
Compares Calder Freight's nightly shipments export with its invoices
export and lists every shipment whose invoicing looks wrong.
## Run it
Needs Python 3.9 or later. Nothing to install.
python reconcile.py shipments.csv invoices.csv
python -m unittest
The first command prints one line per finding. The second runs 7 tests.
## What the sample data shows
5 findings in 6 shipments:
- S-1004 and S-1006 were never invoiced: 1800.00 not billed.
- S-1002 was invoiced 460.00 against an agreed 640.00 (180.00 short).
- S-1005 was invoiced twice (INV-504 and INV-505).
- INV-506 is for S-1009, which is not in the shipments file.
## Assumptions
- The shipments file is the record of what was agreed. Where amounts
differ the report shows both and does not pick one.
- Ids are compared ignoring case and surrounding spaces.
- A comma in an amount is a thousands separator.
- Two invoices for one shipment are reported even if both are correct.
- An invoice for a shipment not in the file is reported. It may belong
to another night's export.
## Left out, and what I would do next
- A row with a missing column or an amount that is not a number stops
the tool with an error. Next: report the row and carry on.
- Both files are read into memory. Fine for a night's export. For much
larger files I would load them into a database and join there.
- First question for finance: is S-1009 in another night's file?
## Time spent
About three hours: 20 minutes reading, 2 hours building and testing,
40 minutes on this file.Notice the third section. It does not describe the code. It tells finance that 1800.00 was not billed and that one customer may have been charged twice. An FDE's work is judged by what the customer can do with it, and the README is where you show you know that.
Notice too that the "Left out" section admits what breaks the tool. Give reconcile.py an amount such as abc and it stops with an error. The interviewer will find that in a minute. Having written it down yourself, with what you would do about it, turns a weakness into evidence of judgement.
Prepare for the walkthrough call
Many take-homes are followed by a call. These questions come up often, so prepare an answer to each in notes.md.
"Walk me through what you built." Start with the problem and the findings, not the code. Two minutes: what the brief asked, what you noticed in the data, what you assumed, how the tool is put together, what it found.
"What if the files had ten million rows?" Say where the limit is and what you would change. The tool keeps every row in memory, which will not fit on a small server at that size. You would load both files into a database, which can join them without holding everything in memory, and you would measure before deciding. Do not redesign for a size nobody has asked for.
"Which file is right when the amounts differ?" You do not know, and saying so is the correct answer. It is the customer's decision. You would ask finance who owns the agreed price, and until then the report shows both figures.
"What would you do next with the customer?" Show finance the five findings and ask which they already knew about. Ask how each export is produced, and whether an invoice can be raised in a different night's file from its shipment.
"What would you change?" Have one honest answer ready, such as the handling of bad rows. Saying "nothing" is the only wrong answer.
Before you send it
Take-homes fail in a few common ways, and each takes minutes to prevent.
- It does not run on the marker's machine. Copy your folder to a new place, follow your own README from the top, and fix whatever you had to do that the README did not say.
- It is over-built. A web page, a database and a container for a three-hour brief suggest you would do the same with a customer's time.
- The README describes the code and not the problem.
- The time limit was ignored. If you went over, say by how much and what you spent it on.
- The data was never read, so the tool reports the comma and the lower-case id as problems.
Key takeaways
- Write one small test for each assumption, and name each test as a sentence that states the rule.
- A README starts with the problem and how to run the tool, and gives the findings in the customer's terms.
- Say what you left out and what breaks the tool; the interviewer will find it anyway.
- In the walkthrough, talk about the problem and the findings before the code.
- Check that your submission runs from a clean copy before you send it.
Try it
Write README.md for your tool in your own words, using the six sections from this lesson and your notes from lesson 2. Then copy the folder somewhere new, follow only your README to run the tool and the tests, and fix the README wherever you had to guess. Last, set a timer for two minutes and explain the work out loud to a friend or a voice recorder. A good result is a README that somebody who never saw the brief can follow, and a spoken walkthrough that reaches the five findings before it names a single function.
Official documentation
Written with AI and checked automatically. Nobody has run these steps by hand, and tools change, so a command may behave differently in the version you install. Spotted a mistake? Tell us.