tests: linkcheck: refactor to remove variable sharing between tests and test webservers

[jayaddison]

Feature or Bugfix

• Refactoring

Purpose

• Tests for linkcheck builder: begin using requests.Session functionality during linkchecking #11324 will benefit from the use of threaded webservers during unit tests.
  • The test_auth_header_uses_first_match test appears flaky when threaded test webservers are used (see Flaky unit test: test_auth_header_uses_first_match #11348).
    • My working theory is that sharing of the records variable -- used to capture request header values within the server, and then assert on their values in the unit test -- across threads is somehow unsafe/unreliable (and could be the cause of the test flakiness).

Detail

• Refactor to remove the sharing of the records variable between unit tests and their corresponding webserver request handler threads.
• Allow each test to provide a callable that declares the success criteria, and have the webserver thread evaluate that and communicate a resulting success/failure code using HTTP status codes.

Relates

• May resolve Flaky unit test: test_auth_header_uses_first_match #11348.
• Could be tested in combination with linkcheck tests: test webservers: enable HTTP/1.1 protocol #11392.

[jayaddison]

I'm sorta unsatisfied and not entirely convinced by this explanation, but it does seem that the algorithm used by headers.as_string method is non-trivial complexity-wise; from the relevant documentation it's essentially an email.message.Message-like object, and the latter has had a few bugs and has been rewritten at least once.

Would that complexity be enough to put some of the unit tests near the client timeout threshold? ... I don't know, 0.05s seems like it should be a lot of compute-time budget. 🤷

I've removed a call to the method in 81ce0f0 and on a sample size of one, it allowed the two instances of test_linkcheck_request_headers on Py3.8 (two because we run the tests against two versions of docutils) to pass when they both failed on a previous version of the code (although I did add a merge-latest between the two).

[jayaddison]

Further suggestions and feedback welcome; otherwise I think that this should be ready for review (no further changes planned at the moment).

[francoisfreitag]

Looking good!

[jayaddison]

Thank you @francoisfreitag!

[AA-Turner]

More timeouts:

FAILED tests/test_build_linkcheck.py::test_defaults - assert 6 == 5
 +  where 6 = len(["links.rst:4: [broken] http://localhost:7777/#!bar: HTTPConnectionPool(host='localhost', port=7777): Read timed out. (read timeout=0.05)", "links.rst:7: [broken] http://localhost:7777#does-not-exist: Anchor 'does-not-exist' not found", 'links.rst:9: [broken] path/to/notfound: ', "links.rst:6: [broken] http://localhost:7777/#top: Anchor 'top' not found", 'links.rst:11: [broken] http://localhost:7777/image.png: 404 Client Error: Not Found for url: http://localhost:7777/image.png', 'links.rst:13: [broken] http://localhost:7777/image2.png: 404 Client Error: Not Found for url: http://localhost:7777/image2.png'])
 +    where ["links.rst:4: [broken] http://localhost:7777/#!bar: HTTPConnectionPool(host='localhost', port=7777): Read timed out. (read timeout=0.05)", "links.rst:7: [broken] http://localhost:7777#does-not-exist: Anchor 'does-not-exist' not found", 'links.rst:9: [broken] path/to/notfound: ', "links.rst:6: [broken] http://localhost:7777/#top: Anchor 'top' not found", 'links.rst:11: [broken] http://localhost:7777/image.png: 404 Client Error: Not Found for url: http://localhost:7777/image.png', 'links.rst:13: [broken] http://localhost:7777/image2.png: 404 Client Error: Not Found for url: http://localhost:7777/image2.png'] = <built-in method splitlines of str object at 0x55aa021f40d0>()
 +      where <built-in method splitlines of str object at 0x55aa021f40d0> = "links.rst:4: [broken] http://localhost:7777/#!bar: HTTPConnectionPool(host='localhost', port=7777): Read timed out. (read timeout=0.05)\nlinks.rst:7: [broken] http://localhost:7777#does-not-exist: Anchor 'does-not-exist' not found\nlinks.rst:9: [broken] path/to/notfound: \nlinks.rst:6: [broken] http://localhost:7777/#top: Anchor 'top' not found\nlinks.rst:11: [broken] http://localhost:7777/image.png: 404 Client Error: Not Found for url: http://localhost:7777/image.png\nlinks.rst:13: [broken] http://localhost:7777/image2.png: 404 Client Error: Not Found for url: http://localhost:7777/image2.png\n".splitlines

[jayaddison]

Thanks again @AA-Turner. Related to this and #11432: do you have any idea why it might be that the LaTeX-related continuous integration tests seem to be more susceptible to timeout failures?