Test the Running HTTP Boundary, Not the Function

One-line summary

An API is not a callable Python function; it is a protocol promised over the network through methods, paths, headers, JSON, status codes, and response bodies. Tests must start the server on a real port and pass through this boundary.

Why pure-function tests are not enough

Even if create_order() returns the right dictionary, the router may not be wired to the POST path, may not read the auth header, or may turn every exception into a 500. Body length, JSON decoding, content type, and case-insensitive header handling are also invisible in a function call. That is why the independent grader reserves an arbitrary loopback port, starts app.py --host 127.0.0.1 --port ..., and sends real HTTP requests.

Distinguish the cases: a successful creation is 201, a replay of the same command is 200, missing authentication is 401, a known identity without permission is 403, and an invalid amount is 400. The response must contain the generated integer ID along with the owner, organization, amount, and status. The X-Trace-Id on every response is the handle that ties a request to logs. An implementation that gets only the status code right and sends an empty body, or a fake server that always returns the same static JSON, is exposed by the follow-up requests.

Regression evidence to build in practice

The test waits for server readiness via /healthz and fails if it is not ready within the time limit. After creating an order, it retries with the same key and a different amount and checks that the original ID and amount are preserved. It also calls the real paths to check that the owner can read and cancel the created resource, and that another user in the same organization and an admin from another organization are rejected. After the process exits, it checks stdout and stderr to make sure no authentication values leaked.

Practical judgment criteria

Mocking is useful for isolating external faults, but it cannot be the only evidence of a protocol contract. Keep fast policy unit tests and real HTTP behavior tests together. The next lesson separates authentication from authorization so that this boundary can decide who may do what to which resource.