Unit 02.03: The one command that must work on a fresh clone

The test of a project setup is whether a fresh clone passes its tests with nothing configured.

Four commands, one requirement

Clone, install, test, run - with what each must not assume.

The code lists them.

STEPS = [
    ("git clone && cd",              "no setup assumed"),
    ("pip install -e '.[dev]'",      "pinned, including dev tools"),
    ("pytest -q",                    "MUST pass with no environment set"),
    ("uvicorn app.main:app --reload", "starts, with fake defaults"),
]
print(f"{'step':34} requirement")
for step, requirement in STEPS:
    print(f"{step:34} {requirement}")

print("""
The third line is the one to protect. If the test suite needs a database, a
key or a network, nobody runs it on every change -- and the tests that catch
most regressions are exactly the ones that need none of those.

Verify by cloning into a fresh directory with an empty environment.
""")

The third line is the one to protect. If the suite needs a database, a key or a network, nobody runs it on every change - and the tests that catch most regressions are exactly the ones needing none of those.

Verify it properly: clone into a fresh directory with an empty environment. Testing on your own machine proves nothing, because your machine has years of accumulated configuration.

The mistake this prevents

The mistake is a README that lists eleven setup steps including "start the database". A new developer's first hour is spent on infrastructure, and the first thing they learn is that the tests do not run.

Takeaway

A fresh clone must install and pass its tests with no environment set. Verify by actually cloning into an empty directory.

Mark complete