spawn_uvicorn

safir.testing.uvicorn.spawn_uvicorn(*, working_directory, app=None, factory=None, capture=False, timeout=5.0, env=None, logger=None)

Spawn an ASGI app as a separate Uvicorn process.

The current working directory will always be added to the Python path, so app and factory can point to modules found relative to the current working directory, or relative to the working_directory parameter.

Parameters:

  • working_directory (str | Path) – Directory in which Uvicorn should run. Normally this should come from the tmp_path fixture.

  • app (str | None, default: None) – Module and variable name of the app. Either this or factory must be given.

  • factory (str | None, default: None) – Module name and callable that will create the app object. Either this or app must be given.

  • capture (bool, default: False) – Whether to capture standard output and standard error of Uvicorn. If set to true, both will be automatically decoded as UTF-8 text and will be available in the process attribute of the returned object.

  • timeout (float, default: 5.0) – How long to wait in seconds.

  • env (dict[str, str] | None, default: None) – Extra environment variable settings.

  • logger (BoundLogger | None, default: None) – Logger to use for logging, if given. If not, a new structlog logger will be created.

Returns:

Properties of the running Uvicorn service.

Return type:

UvicornProcess

Raises:

  • RuntimeError – Raised if no logger was provided and no logger could be obtained from structlog.

  • ServerNotListeningError – Raised if the server did not start within the timeout. Generally this means it had some fatal error during startup.

  • ValueError – Raised if either both or neither of app and factory were given.