feat!: add new overload to match RequestUri, accepting Matches

[skwasjer]

This PR adds a new type Matches (see below) and adds a new overload RequestMatchingExtensions.RequestUri(RequestMatching, Matches).

Relates to #112

The behavior of the sibling overload accepting a string RequestMatchingExtensions.RequestUri(RequestMatching, string) has now changed. It now no longer infers a wildcard match if the input string contains an asterisk '*'. It now only expects relative or absolute URI's and will match them exactly as before.
Unfortunately, changing the behavior will cause friction amongst users that have used wildcards in their tests, but I see no other way to transition to this new API.

To perform wildcard matches, it must now be explicitly provided via the overload accepting a Matches type, eg. using Matches.Wildcard("some*thing"). By using this explicit approach, we give users full control over how a request URI can be matched, and remove the ambiguity that was present with the string/wildcard inference. With the new API users can even use custom expression, regexes, etc.

Matches struct

The new Matches struct encapsulates string matching, so there is one unified API that can be used internally my MockHttp to match request URI's but also in the future headers, and URI components separately (eg. query string, path, authority, etc.).

IMPORTANT: no URL (data) encoding/decoding is performed when using the Matches type, thus the user of MockHttp must make sure the value is encoded properly.

The Matches type provides several helpers:

• Match using wildcard(s) *:

  Matches.Wildcard("*/controller/*/action?query=*")

• Match using regex:

  Matches.Regex(".+/controller/\w+/action?query=.+")
  // or
  Matches.Regex(new Regex(".+/controller/.+/action?query=.+"))

• Match using custom expression:

  Matches.Expression(s => s.Contains("/controller/") && s.Contains("/action?query="))

The following are less useful for request URI matching, but in the future the Matches type will also support matching query string and header key value pairs, which is where these will shine.

• Match null or empty:

  Matches.Empty

• Match anything:

  Matches.Any

• Match exactly:

  Matches.Exactly("/controller/nested/action?query=1")

Operators

The Matches type has several operator implementations, which also allows mixing different pattern styles:

• And

  Matches.Wildcard("*controller*") & Matches.Regex(".+/action?query=.+")

• Or:

  Matches.Wildcard("*controller*") | Matches.Regex(".+/action?query=.+")

• Xor:

  Matches.Wildcard("*controller*") ^ Matches.Regex(".+/action?query=.+")

• Not:

  !Matches.Wildcard("*controller*")

Implicit conversion

string implicitly converts to Matches using Matches.Exactly(..)

ToString

When calling ToString(), returns the provided pattern value.

[skwasjer]

Renaming Pattern to Matches would make more sense in the context of the Fluent API.
Similary, the Expression method should probably be named When.

You'd then get statements such as:

mockHttp
    .When(matching => matching
        .Method("GET")
        .RequestUri(Matches.When(uri => uri.StartsWith("http://")) & Matches.Wildcard("*/controller/action"))
    .Respond(with => with
        .StatusCode(200)
    );

It reads more natural this way.

Ideally, Pattern/Matches would also have a generic base interface or abstract base type, so we can use Uri in stead of string while at the same time have an API that could accept HeaderCollection for when this is implemented for HTTP headers.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud