Important! Since version 2.0.0, WebMock does not match credentials provided in Authorization header and credentials provided in the userinfo of a url. I.e. stub_request(:get, "user:pass@www.example.com") does not match a request with credentials provided in the Authorization header.

Connecting on Net::HTTP.start

HTTP protocol has 3 steps: connect, request and response (or 4 with close). Most Ruby HTTP client libraries
treat connect as a part of request step, with the exception of Net::HTTP which
allows opening connection to the server separately to the request, by using Net::HTTP.start.

WebMock API was also designed with connect being part of request step, and it only allows stubbing
requests, not connections. When Net::HTTP.start is called, WebMock doesn't know yet whether
a request is stubbed or not. WebMock by default delays a connection until the request is invoked,
so when there is no request, Net::HTTP.start doesn't do anything.
This means that WebMock breaks the Net::HTTP behaviour by default!

To workaround this issue, WebMock offers :net_http_connect_on_start option,
which can be passed to WebMock.allow_net_connect! and WebMock.disable_net_connect! methods, i.e.

WebMock.allow_net_connect!(net_http_connect_on_start:true)

This forces WebMock Net::HTTP adapter to always connect on Net::HTTP.start.

Matching with URI Templates

If you use any of the WebMock methods for matching query params, then Addressable will be used to match the base URI and WebMock will match the query params. If you do not, then WebMock will let Addressable match the full URI.

Matching headers

WebMock will match request headers against stubbed request headers in the following situations:

Background

Thank you Fakeweb! This library was inspired by FakeWeb.
I imported some solutions from that project to WebMock. I also copied some code i.e Net:HTTP adapter.
Fakeweb architecture unfortunately didn't allow me to extend it easily with the features I needed.
I also preferred some things to work differently i.e request stub precedence.