treq.auth omnibus

[twm]

• Rework the treq.test.test_auth to use a new treq._recorder.recorder() utility rather than mock.
• Closes #312: Mark _RequestHeaderSettingAgent as an IAgent implementer.
• Closes #313: Document treq.auth — add docstrings and add to the API page.
• Closes #314: Don't mutate Headers passed to _RequestHeaderSettingAgent
• Closes #268: UTF-8 encode basic auth username and password. Also allow bytes as an escape hatch.

[twm]

Happy to see mock.Mock gone :)

More of this to come!

For my tests, I stopped using spies that record and for which you assert the behaviour later, and instead I am using and ReplayAgentBacked similar to the angularjs $httpBackend

You pass a list of expected URLs and request data, but you also able to return a response. In this way, you can test chained agent interactions, without touching the network.

For example, I am using for SAML login testing in which more than 1 requests are made...and the response of the first request is used in the second request.

treq.testing, specifically RequestTraversalAgent, is exactly this! I'm a big fan of this style. It's actually the part of treq I use most, though it has some pretty rough edges. I didn't use it in this case for two reasons:

• treq.testing itself is a big hunk of code, far more complex than the treq.auth implementation itself, so it seemed risky.
• I plan to revise the treq.testing API once treq drops Python 2.7 support, so I didn't want to add an internal dependency on its current API.

[adiroiban]

I think that the spy is OK for unit tests and treq.testing can be used "network-free" integration tests.

[twm]

Thank you very much for the review and feedback, @adiroiban!