Short answer: it’s not “expected,” but it is common for GitHub Actions runners to be slow enough that the Prefect test server doesn’t come up within the default 30s. The

prefect_test_harness

starts a local Prefect Server (uvicorn) in a subprocess and waits for it to become healthy; on CI that startup can occasionally exceed 30s and trigger a timeout. What to try first - Increase the startup timeout:

python
  # conftest.py
  import pytest
  from prefect.testing.utilities import prefect_test_harness

  @pytest.fixture(scope="session", autouse=True)
  def prefect_harness():
      # give CI more time to boot the test server
      with prefect_test_harness(server_startup_timeout=120):
          yield

The callable signature confirms this parameter exists and defaults to 30 seconds: - prefect.testing.utilities.prefect_test_harness(server_startup_timeout: int | None = 30) Other common CI-specific causes and mitigations - Parallel test runs: If you use pytest-xdist (

-n

), multiple workers may try to start harnesses concurrently. Either: - Use a single session-scoped harness (as above), and/or - Reduce parallelism or ensure only one harness is created. - Proxies in CI: Outbound proxies can accidentally intercept localhost calls. Set:

bash
  NO_PROXY=127.0.0.1,localhost

- Slow/variable CI performance: Cold caches, limited CPU, and I/O throttling can delay server import/startup. Pin dependencies and cache your Python env if possible. - Logging to diagnose: Enable verbose logging to see if the test server is starting and when it fails:

bash
  PREFECT_LOGGING_LEVEL=DEBUG
  pytest -o log_cli=true -o log_cli_level=DEBUG

- Make startup happen once: Use a session-scoped fixture so the server starts once per job, not per test module/function. Recent related changes - There was a recent fix to improve subprocess cleanup in the test harness (teardown). Not directly about startup timeouts, but good to be on a recent 3.x: - Fix subprocess cleanup in prefect_test_harness If it still times out - Please share the exact exception text/stack trace (does it say the server didn’t start within X seconds?), if you’re using pytest-xdist, and any proxy settings in the job. With that, I can suggest a more targeted fix. References - Prefect 3 settings (for logging, etc.): Prefect 3 settings

Yes — with

@pytest.fixture(scope="session", autouse=True)

the harness will start once per test session (i.e., once per Python process) and be shared by all tests. Two gotchas to keep in mind: - If you run tests with pytest-xdist (e.g.,

-n auto

), each worker is a separate process and will create its own session-scoped harness/server. - The default

server_startup_timeout

is 30s, so bumping it to 90s (as you did) is a common fix for CI where startup can be slower. Glad it’s working now! If you hit anything else (especially with parallel runs), let me know.