Skip to content

xtr_http_client_contracts.testing

What an implementation of the client contract tests itself with.

Install it with the testing extra. Nothing here is imported by the contract itself, so an application that only depends on the interfaces never pays for it.

HttpClientTestCase

What every client that satisfies the contract does, run against the fixture server.

Subclass it and return the client under test::

class TestMyClient(HttpClientTestCase):
    def create_client(self) -> HttpClientInterface:
        return MyClient()

A client that cannot honour part of the contract yet names the tests it skips and why::

class TestMyClient(HttpClientTestCase):
    skipped_tests: ClassVar[Mapping[str, str]] = {
        "test_ipv6_resolve": "no IPv6 in this environment",
    }

The suite starts the fixture server once for the whole session, on a free port, and points every test at it through :attr:base_uri and :attr:port; the few tests that need a second server start and stop one themselves. A subclass adding tests of its own reads the same two attributes.

skipped_tests class-attribute

skipped_tests: Mapping[str, str] = {}

Test names to skip, mapped to why. A parametrized test is named without its parameter.

port class-attribute instance-attribute

port: int = 0

The port the session's fixture server listens on, set before every test.

base_uri class-attribute instance-attribute

base_uri: str = ''

The origin of the session's fixture server, set before every test.

fixture_server staticmethod

fixture_server() -> Iterator[TestHttpServer]

The server every test points at, listening for the whole session.

create_client

create_client() -> HttpClientInterface

Return the client the suite is to run against.

Returns:

test_get_request async

test_get_request() -> None

A plain GET: the status and headers are in, and the body decodes to what was sent.

test_body_stream async

test_body_stream() -> None

The body is also the message's stream, which reads the same bytes.

Nothing in the reference suite reads a response that way — it has no streamed body on the message — so this is the contract's own addition.

test_head_request async

test_head_request() -> None

A HEAD answers headers describing a body it does not send.

test_unsupported_option async

test_unsupported_option() -> None

An option the client has never heard of is refused, never quietly obeyed.

test_http_version async

test_http_version() -> None

Asking for HTTP/1.0 sends HTTP/1.0, which the echo answers with.

test_chunked_encoding async

test_chunked_encoding() -> None

A chunked body is reassembled; framing that stops mid-chunk fails the transfer.

test_client_error async

test_client_error() -> None

A 404 is an answer: told about when asked for, readable when not.

test_ignore_errors async

test_ignore_errors() -> None

Reading the status of a 404 is not being told about it.

test_dns_error async

test_dns_error() -> None

A host that will not resolve fails the request, and fails it again on a retry.

test_inline_auth async

test_inline_auth() -> None

Credentials in the URL are sent as basic credentials, decoded as given.

test_bad_request_body async

test_bad_request_body() -> None

A body producing something that is not bytes fails the request.

test_304 async

test_304() -> None

A 304 carries no body, whatever length it declares.

test_redirects async

test_redirects(headers: Mapping[str, str]) -> None

A chain is followed as GET, and credentials come back when it returns home.

test_invalid_redirect async

test_invalid_redirect() -> None

A Location nothing can be made of is left as the 3xx it came on.

test_relative_redirects async

test_relative_redirects() -> None

A relative Location is resolved; following none leaves it to be read.

test_redirect_307 async

test_redirect_307() -> None

A 307 keeps the method and the body, once it is followed.

test_max_redirects async

test_max_redirects() -> None

One hop too few ends on the 3xx, saying where it would have gone.

test_post_json async

test_post_json() -> None

A JSON body is sent as JSON, and says so in its content type.

test_post_array async

test_post_array() -> None

A mapping body is sent as a form, which the echo answers field by field.

test_post_resource async

test_post_resource() -> None

A body read from somewhere else is sent as it is produced.

test_post_callback async

test_post_callback() -> None

A body produced in pieces, empty ones included, arrives as one form.

test_cancel async

test_cancel() -> None

A cancelled transfer has nothing left to read.

test_info_on_canceled_response async

test_info_on_canceled_response() -> None

Cancelling is something the transfer info records.

test_resolve async

test_resolve() -> None

A host pinned to an address is reached at it, for the request that pinned it only.

test_idn_resolve async

test_idn_resolve() -> None

A very long label and a non-ASCII name both resolve to what they are pinned to.

test_ipv6_resolve async

test_ipv6_resolve() -> None

A host pinned to an IPv6 address is reached over IPv6.

test_not_a_timeout async

test_not_a_timeout() -> None

The timeout is how long a transfer may go quiet for, not how long it may take.

test_timeout_on_access async

test_timeout_on_access() -> None

A head that does not arrive in time fails the request.

test_timeout_is_not_a_fatal_error async

test_timeout_is_not_a_fatal_error() -> None

A transfer that timed out mid-body carries on being read.

test_timeout_with_active_concurrent_stream async

test_timeout_with_active_concurrent_stream() -> None

A transfer that keeps arriving does not hold a timeout back.

test_timeout_on_initialize async

test_timeout_on_initialize() -> None

Four heads that never arrive time out alongside each other, not one after another.

test_timeout_on_destruct async

test_timeout_on_destruct() -> None

The same four, each reported where its request was made.

test_destruct async

test_destruct() -> None

Leaving the block frees a transfer rather than waiting for the rest of it.

test_proxy async

test_proxy() -> None

The proxy option is asked for the absolute URL, with its own credentials.

test_no_proxy async

test_no_proxy() -> None

http_proxy is obeyed with no option at all, and no_proxy exempts a host.

test_auto_encoding_request async

test_auto_encoding_request() -> None

A client asks for a compressed body by itself, and hands it over decoded.

test_base_uri async

test_base_uri() -> None

A relative URL is resolved against the base, traversal included.

test_query async

test_query() -> None

Query parameters are merged into the ones the URL already carried.

test_informational_response async

test_informational_response() -> None

A 1xx ahead of the real status is read past, not answered with.

test_userland_encoding_request async

test_userland_encoding_request() -> None

Asking for an encoding outright hands the body over as it arrived.

test_gzip_broken async

test_gzip_broken() -> None

A body compressed only in name fails the transfer.

test_max_duration async

test_max_duration() -> None

A transfer outlasting its whole-request limit ends there, however much arrives.

test_max_connect_duration async

test_max_connect_duration() -> None

Connecting is given its own limit, well short of the idle one.

test_with_options async

test_with_options() -> None

Options become the defaults of a new client, and leave this one as it was.

test_send_request_prefers_the_request_headers async

test_send_request_prefers_the_request_headers() -> None

A header the request carries is sent; one it lacks is filled from the options.

test_send_request_resolves_a_relative_request_uri async

test_send_request_resolves_a_relative_request_uri() -> None

A request whose URI is relative is resolved against base_uri.

test_send_request_merges_the_query_option async

test_send_request_merges_the_query_option() -> None

query is merged into the query the request's URI already carried.

test_send_request_applies_auth_bearer_only_without_one async

test_send_request_applies_auth_bearer_only_without_one() -> None

auth_bearer fills an Authorization the request has none of, and replaces none.

test_send_request_refuses_a_body_on_both async

test_send_request_refuses_a_body_on_both() -> None

A request carrying a body plus a body option is a request refused, not merged.

test_request_is_send_request_of_the_same_request async

test_request_is_send_request_of_the_same_request() -> None

request(method, url) answers as send_request of that method and URL does.

test_post_multipart async

test_post_multipart(tmp_path: Path) -> None

A form holding a file is sent as multipart, the file named and typed after itself.

test_post_multipart_with_an_unnamed_file async

test_post_multipart_with_an_unnamed_file() -> None

A file with no name of its own goes as unknown, of no type anyone can guess.

test_post_multipart_keeps_the_callers_boundary async

test_post_multipart_keeps_the_callers_boundary() -> None

A multipart content type the caller set, boundary and all, is the one the body uses.

test_post_form_without_a_file_stays_url_encoded async

test_post_form_without_a_file_stays_url_encoded() -> None

A form holding no file is sent url-encoded, not as multipart.

TestHttpServer

TestHttpServer(host: str = _HOST, port: int = _ANY_FREE_PORT)

The server the conformance suite points a client at.

It runs on an event loop of its own, in a background thread, because the client under test owns the loop its own code runs on: a client that stops pumping its loop — which is exactly what a timeout test provokes — must not stop the server that is meant to keep answering it.

start() returns once the port is listening, and both start() and stop() may be called again at any point, so one instance can live for a whole test session::

@pytest.fixture(scope="session")
def http_server() -> Iterator[TestHttpServer]:
    with TestHttpServer() as server:
        yield server

Unless a port is named, the server listens on whichever free port the operating system hands out, which :attr:port and :attr:base_uri report once :meth:start has returned. A restarted server may be given a different one.

What each route answers is described in _fixture_routes; what the echoing ones report about the request is described in _fixture_request.

Bind nothing yet: the socket is opened by :meth:start.

host property

host: str

The address the server listens on.

port property

port: int

The port the server listens on.

Raises:

  • RuntimeError –

    When the server was asked for any free port and has not been started, so no port has been chosen yet.

base_uri property

base_uri: str

The origin a client should send its requests to.

start

start() -> None

Listen, and return once the port accepts connections.

Starting an already-running server does nothing, so a fixture may start it defensively. Whatever stopped the thread from listening — a port already taken, most often — is raised here rather than left to make every later request fail obscurely.

stop

stop() -> None

Close the port and everything still connected to it.

Stopping a server that is not running does nothing, and a stopped server can be started again; a route still writing when this is called is cut off rather than waited for.