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
¶
Test names to skip, mapped to why. A parametrized test is named without its parameter.
port
class-attribute
instance-attribute
¶
The port the session's fixture server listens on, set before every test.
base_uri
class-attribute
instance-attribute
¶
The origin of the session's fixture server, set before every test.
fixture_server
staticmethod
¶
The server every test points at, listening for the whole session.
create_client ¶
Return the client the suite is to run against.
Returns:
-
HttpClientInterface–A client, freshly made: a test may cancel transfers or exhaust a connection pool,
-
HttpClientInterface–so no two tests share one.
test_get_request
async
¶
A plain GET: the status and headers are in, and the body decodes to what was sent.
test_body_stream
async
¶
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
¶
A HEAD answers headers describing a body it does not send.
test_unsupported_option
async
¶
An option the client has never heard of is refused, never quietly obeyed.
test_http_version
async
¶
Asking for HTTP/1.0 sends HTTP/1.0, which the echo answers with.
test_chunked_encoding
async
¶
A chunked body is reassembled; framing that stops mid-chunk fails the transfer.
test_client_error
async
¶
A 404 is an answer: told about when asked for, readable when not.
test_ignore_errors
async
¶
Reading the status of a 404 is not being told about it.
test_dns_error
async
¶
A host that will not resolve fails the request, and fails it again on a retry.
test_inline_auth
async
¶
Credentials in the URL are sent as basic credentials, decoded as given.
test_bad_request_body
async
¶
A body producing something that is not bytes fails the request.
test_redirects
async
¶
A chain is followed as GET, and credentials come back when it returns home.
test_invalid_redirect
async
¶
A Location nothing can be made of is left as the 3xx it came on.
test_relative_redirects
async
¶
A relative Location is resolved; following none leaves it to be read.
test_redirect_307
async
¶
A 307 keeps the method and the body, once it is followed.
test_max_redirects
async
¶
One hop too few ends on the 3xx, saying where it would have gone.
test_post_json
async
¶
A JSON body is sent as JSON, and says so in its content type.
test_post_array
async
¶
A mapping body is sent as a form, which the echo answers field by field.
test_post_resource
async
¶
A body read from somewhere else is sent as it is produced.
test_post_callback
async
¶
A body produced in pieces, empty ones included, arrives as one form.
test_info_on_canceled_response
async
¶
Cancelling is something the transfer info records.
test_resolve
async
¶
A host pinned to an address is reached at it, for the request that pinned it only.
test_idn_resolve
async
¶
A very long label and a non-ASCII name both resolve to what they are pinned to.
test_ipv6_resolve
async
¶
A host pinned to an IPv6 address is reached over IPv6.
test_not_a_timeout
async
¶
The timeout is how long a transfer may go quiet for, not how long it may take.
test_timeout_on_access
async
¶
A head that does not arrive in time fails the request.
test_timeout_is_not_a_fatal_error
async
¶
A transfer that timed out mid-body carries on being read.
test_timeout_with_active_concurrent_stream
async
¶
A transfer that keeps arriving does not hold a timeout back.
test_timeout_on_initialize
async
¶
Four heads that never arrive time out alongside each other, not one after another.
test_timeout_on_destruct
async
¶
The same four, each reported where its request was made.
test_destruct
async
¶
Leaving the block frees a transfer rather than waiting for the rest of it.
test_proxy
async
¶
The proxy option is asked for the absolute URL, with its own credentials.
test_no_proxy
async
¶
http_proxy is obeyed with no option at all, and no_proxy exempts a host.
test_auto_encoding_request
async
¶
A client asks for a compressed body by itself, and hands it over decoded.
test_base_uri
async
¶
A relative URL is resolved against the base, traversal included.
test_query
async
¶
Query parameters are merged into the ones the URL already carried.
test_informational_response
async
¶
A 1xx ahead of the real status is read past, not answered with.
test_userland_encoding_request
async
¶
Asking for an encoding outright hands the body over as it arrived.
test_gzip_broken
async
¶
A body compressed only in name fails the transfer.
test_max_duration
async
¶
A transfer outlasting its whole-request limit ends there, however much arrives.
test_max_connect_duration
async
¶
Connecting is given its own limit, well short of the idle one.
test_with_options
async
¶
Options become the defaults of a new client, and leave this one as it was.
test_send_request_prefers_the_request_headers
async
¶
A header the request carries is sent; one it lacks is filled from the options.
test_send_request_resolves_a_relative_request_uri
async
¶
A request whose URI is relative is resolved against base_uri.
test_send_request_merges_the_query_option
async
¶
query is merged into the query the request's URI already carried.
test_send_request_applies_auth_bearer_only_without_one
async
¶
auth_bearer fills an Authorization the request has none of, and replaces none.
test_send_request_refuses_a_body_on_both
async
¶
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
¶
request(method, url) answers as send_request of that method and URL does.
test_post_multipart
async
¶
A form holding a file is sent as multipart, the file named and typed after itself.
test_post_multipart_with_an_unnamed_file
async
¶
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
¶
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
¶
A form holding no file is sent url-encoded, not as multipart.
TestHttpServer ¶
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.
port
property
¶
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.
start ¶
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 ¶
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.