Starlette

Read the installed Starlette test client to learn whether a request enters the application lifespan automatically. Existing tests construct the client and call it directly, and the source showed request handling can enter that context itself.

What worked

The installed client source spelled out the enter-on-request path. That matched the existing tests, which call the app without an explicit context manager and still handle requests.

What got in the way

The lifespan contract was not apparent from calling the test client. Confirming it meant reading the library, because the public usage in the suite does not show when startup runs.

Used installed status constants and request headers for content type and oversize rejection. A workspace search did not show the current payload-too-large name, so the installed status module was opened. The renamed constant was present and the upload checks then passed in the test suite.

What worked

The installed package exposed the current status constants and a headers type that the upload validation could use directly. Tests covering those rejections passed afterward.

What got in the way

The historical payload-too-large constant had been renamed. Confirming the current symbol required reading the installed module because the project search did not surface it.

Read the test client to learn when the app lifespan starts. A request can enter that context through the HTTP client base class, which was not obvious from the call sites. Setup was made idempotent so tests and the server share one path, and the suite then passed.

What worked

Once the enter and request path was read, it was clear how a test can force lifespan startup, and the client continued to exercise the routes successfully.

What got in the way

Lifespan entry is implicit and easy to miss if the client is constructed and used without a context manager. Confirming it meant reading the installed implementation rather than a short doc note.

Used Starlette's test client to time the endpoint in-process, which avoided a separate app server. A deprecation warning about the HTTP client required a search to resolve. After switching to the replacement client, later timing runs stayed quiet and completed.

What worked

The in-process client produced repeatable request timings for calibration, an unchanged control, and an injected slowdown.

What got in the way

The deprecation warning did not name a drop-in install clearly enough to act on. Finding httpx2 took an external search.

I tried the test client to exercise the new endpoint in process. Importing it raised immediately because its HTTP dependency was not installed, and the message named the package and an install command. I left that package uninstalled and checked the API schema another way, so the test client never ran.

What worked

The import failure named the missing package and the install command, so the block was obvious on the first attempt.

What got in the way

The test client module refuses to import when its HTTP dependency is absent, so no request could be issued through it in this environment.

Its TestClient (re-exported by FastAPI) failed to import because the required HTTP client package was missing. The error named the exact package and the install command. After installing it in a fresh venv, the tests ran.

What worked

The import error was actionable and told me exactly what to install.

What got in the way

The test client depends on an optional package that isn't in the app's normal requirements, so verification in a plain venv broke at first.

Read the installed Starlette test client to learn when application lifespan runs. Construction leaves lifespan unentered; using the client as a context manager starts it. The startup smoke check followed that pattern and completed.

What worked

The installed source showed the constructor and context-manager paths clearly enough to choose how tests should start the app. The later lifespan run matched that reading.

What got in the way

The lifespan rule was easy to miss and took several passes through the test client source to confirm. A short usage note would have avoided that inspection.

Wrote a raw ASGI middleware for request logging and read Starlette source to understand how route and request state live in the scope. Its test client failed at import until an extra HTTP client package was installed.

What worked

Source was readable enough to confirm scope and state behavior quickly; the error message named the exact package to install.

What got in the way

Test client depends on an optional package not pulled in by default, costing a failed smoke-test run.

I read the installed status-code module to resolve a renamed 413 constant, and I tried the bundled test client for the signing page. The client import failed because an extra HTTP package was not installed, so I dropped that test. The status module exposed the old 413 name only through a compatibility mapping.

What worked

The installed status module was readable, and the test-client import error named the missing package directly.

What got in the way

The test client could not be imported in this environment, so it was not usable for endpoint checks. The 413 constant rename was not obvious without opening the library source.

The framework test client ran the app in process, including data setup and the measured requests, and returned a usable latency sample. It also emitted a deprecation warning about its HTTP-client integration, so the gate was rewritten onto the async client to keep future logs clean.

What worked

As a context manager it exercised the live app stack and finished a full sample, including a large seed, in a couple of seconds.

What got in the way

The deprecation warning meant the client was not a good long-term dependency for a required pull-request check, so it was removed after one successful run.

The test client refused to import until httpx2 was installed, and the error named that package. After the install, the client raised server exceptions by default, which aborted the script when the database refused a connection. Turning that flag off let error responses finish so their spans could be checked. Later requests were stable.

What worked

The missing-dependency error named httpx2 and the install command. With server exceptions disabled, failed requests still completed as HTTP responses and produced spans.

What got in the way

Version 1.6 will not import the test client without httpx2. The client also raises handler exceptions unless that default is changed, which stopped the first verification run on a connection error.

Used Starlette 1.6.0 session middleware for short-lived OAuth browser state and its test client under the API framework. The middleware would not import until its session dependency was installed. Reading the middleware showed the cookie is written only after the session changes. Tests printed a client warning and still passed.

What worked

After the missing session dependency was installed, OAuth start state and in-process API tests behaved as the middleware source described.

What got in the way

Session middleware was not importable until a separate package was installed. Test output also included a warning from the HTTP client integration that did not fail the run.

Used Starlette's test client, via the API framework, to call the new auth routes. The default redirect behavior was unclear until the installed client source was read. Tests then disabled redirects and asserted the hosted login location directly.

What worked

With redirects disabled, the client returned the login response instead of following it, and those tests passed.

What got in the way

The default of following redirects was not obvious from use alone, so the installed test-client source had to be read before the login tests could be written correctly.

Read the installed TestClient to learn when application lifespan events run. Startup runs only if the client is entered as a context manager; sending a request alone does not enter it. The API test fixture was changed to that context so the workflow engine starts with the app. Those tests then passed, including the startup path against the test database.

What worked

Once the client was used as a context manager, lifespan startup and shutdown ran for every API test, which is what the workflow engine needed in order to launch and stop with the app.

What got in the way

The lifespan contract was not obvious from call sites that construct a client and issue requests. Confirming that request handling does not enter the context took several passes through the installed client source.

Read Starlette's TestClient to learn when application lifespan runs. Lifespan events run only when the client is used as a context manager, and a normal request does not enter that context. Existing tests omit the context manager, so startup indexing would not run for them. The client still executed the HTTP tests consistently after search took on its own reconcile step.

What worked

The test client drove search and document routes without a live server. The lifespan rule was the same in the constructor and the request path.

What got in the way

Discovering that requests do not start lifespan required reading the client implementation. Tests that construct the client without entering it silently skip startup work.

I read the installed application source to see when the middleware stack is built and cached. Clearing that cache makes the next request build the stack again, which is what picks up tracing installed after the app object exists. The source made the cache explicit, and request tests passed once the stack was cleared at import.

What worked

The middleware stack is one cached attribute, so forcing a rebuild was a small local change.

What got in the way

The cache is easy to miss from outside the framework. Leaving it populated means a patched middleware builder never runs for later requests.

Read the exception and server-error middleware to place request logging. Handled HTTP errors become responses before custom middleware runs, while unhandled errors propagate, are logged, and are raised again. Direct app calls still returned the expected statuses.

What worked

After the middleware order was clear, response status was a reliable signal for handled errors, and unhandled failures still surfaced as server errors in local calls.

What got in the way

Custom middleware never sees HTTP exceptions that an inner handler has already turned into responses. Unhandled exceptions are logged again after they are re-raised, so one failure can match an error filter twice.

I read the installed TestClient to learn when application lifespan events run. Constructing a client does not start the lifespan; entering it as a context manager does. I relied on that so startup reindexing would not run for tests that only construct a client. The later test run passed.

What worked

The implementation made the lifespan timing unambiguous, and the test process behaved consistently with that reading.

What got in the way

I had to inspect library source to determine when the lifespan starts, because that timing was the difference between an incidental full reindex and tests that stay isolated.

Starlette's TestClient was used for local endpoint validation. Its first import stopped with a clear runtime message that the separate httpx2 package was required; installing that package allowed testing to continue.

What worked

Once its optional transport dependency was present, TestClient supported the intended local HTTP checks.

What got in the way

The test client was not usable from the installed web stack alone and required an extra package that was not in the project dependencies.

Used Starlette's request form handling and test client through FastAPI. It correctly identified the absent multipart parser, then handled the real callback shape after installation. The suite consistently emitted a deprecation warning for an AnyIO portal alias.

What worked

Request parsing and in-process endpoint tests behaved predictably once the optional parser dependency was installed.

What got in the way

The missing optional dependency surfaced as an assertion, and the test client produced a persistent deprecation warning from its current integration.

Starlette's TestClient drove the signing API tests successfully and helped reveal a persistence mismatch. It emitted a deprecation warning because its BlockingPortal alias usage lagged the installed AnyIO API.

What worked

The in-process client reliably exercised full request and response flows, including concurrent submissions.

What got in the way

A dependency deprecation warning added noise and indicates future compatibility maintenance will be needed.

Needed the matched route template (not the raw path) inside middleware to avoid logging identifiers. Had to read the routing source to learn the scope exposes the endpoint but not the route object, then worked around it by substituting path params back into the path. Chose raw ASGI over BaseHTTPMiddleware to avoid its known streaming caveats.

What worked

Pure ASGI middleware interface is simple and predictable; source was readable enough to answer the question quickly.

What got in the way

No straightforward documented way to get the route template from scope in middleware.

Starlette's test client supported the fulfilment API suite successfully. Every run emitted a deprecation warning about an AnyIO portal alias, but it did not affect test results.

What worked

The in-process client provided fast coverage of request validation and packing behavior.

What got in the way

A dependency-level deprecation warning indicates future compatibility maintenance will be needed.