From 35feda9cc6c792624a5e531c36f831c8665fd41c Mon Sep 17 00:00:00 2001 From: Cserna Zsolt Date: Sat, 7 Feb 2026 21:52:22 +0100 Subject: [PATCH 1/2] add docs for readiness check --- doc/howto.rst | 35 ++++++++++++++++++++++++++ tests/examples/test_howto_readiness.py | 30 ++++++++++++++++++++++ 2 files changed, 65 insertions(+) create mode 100644 tests/examples/test_howto_readiness.py diff --git a/doc/howto.rst b/doc/howto.rst index 93e47c2a..952955dc 100644 --- a/doc/howto.rst +++ b/doc/howto.rst @@ -299,6 +299,41 @@ the ``httpserver`` fixture). return ("127.0.0.1", 8000) +Waiting for server to be ready +------------------------------ + +By default, the ``httpserver`` fixture ensures that the server is bound to the +configured address and listening for incoming connections. While this is +sufficient for most use cases, you can optionally wait for the server to be +fully ready to serve HTTP requests before proceeding with your tests. This is +particularly useful when your client has strict timeout requirements or when the +HTTP server has a slow startup time. + +To enable this check, *pytest-httpserver* issues an HTTP probe request to the +server before your test starts to ensure the server is ready to serve requests. +You can configure the timeout for this probe request as needed. + + +.. warning:: + + This check is not supported in SSL mode, as the probe request is not + configured to accept the self-signed certificate used by the server. To + enable this feature with SSL, override the ``wait_for_server_ready()`` + method with your implementation. + + +To enable this feature, set the ``startup_timeout`` keyword argument when +initializing ``HTTPServer``. This parameter specifies the maximum time to wait +for the server to become ready to serve HTTP requests. + + +.. literalinclude :: ../tests/examples/test_howto_readiness.py + :language: python + + +In the case the server times out, the test will fail. + + Multi-threading support ----------------------- diff --git a/tests/examples/test_howto_readiness.py b/tests/examples/test_howto_readiness.py new file mode 100644 index 00000000..1ae2a6d1 --- /dev/null +++ b/tests/examples/test_howto_readiness.py @@ -0,0 +1,30 @@ +from collections.abc import Generator + +import pytest +import requests + +from pytest_httpserver import HTTPServer + +# By overriding make_httpserver fixture, you can override the object which is +# used by the httpserver fixture. You can put this to your conftest.py so in +# that case it will be used for all tests in the project, or you can put it to a +# test file if you want to use it only for that file. + + +@pytest.fixture(scope="session") +def make_httpserver() -> Generator[HTTPServer, None, None]: + server = HTTPServer(startup_timeout=10) # wait for 10 seconds for the server to be ready + server.start() + yield server + server.clear() + if server.is_running(): + server.stop() + + +def test_example(httpserver: HTTPServer): + # the server is ready at this point, you can add request handlers and start sending requests + httpserver.expect_request("/foobar").respond_with_json({"foo": "bar"}) + + response = requests.get(httpserver.url_for("/foobar")) + assert response.status_code == 200 + assert response.json() == {"foo": "bar"} From ac84e5614c85ef80da440efe81715588f0c1f2d0 Mon Sep 17 00:00:00 2001 From: Cserna Zsolt Date: Sat, 7 Feb 2026 23:01:44 +0100 Subject: [PATCH 2/2] releasenotes: add release note for readiness check --- releasenotes/notes/readiness-1cda7fef501cebd8.yaml | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 releasenotes/notes/readiness-1cda7fef501cebd8.yaml diff --git a/releasenotes/notes/readiness-1cda7fef501cebd8.yaml b/releasenotes/notes/readiness-1cda7fef501cebd8.yaml new file mode 100644 index 00000000..c9048b05 --- /dev/null +++ b/releasenotes/notes/readiness-1cda7fef501cebd8.yaml @@ -0,0 +1,6 @@ +--- +features: + - | + More robust server startup by checking server readiness (disabled by + default). + `#462 `_