Match outgoing requests¶

Run the complete page example.

A test needs to know whether your app asked for the right thing. Checking only the returned value can miss a wrong URL, a missing header or an incorrect request body.

A route is the rule that decides which requests a stub entry answers. A RouteMatcher holds that rule. Start with a method and path, then add conditions for the details that matter to your test. Each entry pairs a route with a reply, as the first test shows.

Choose a method and path¶

You want to match a request by its HTTP method and path. You also want a safe answer for any request you did not plan for. The Testing.cs sample sets up one route for each method and a fallback route.

using StubHttp http = new StubHttp
{
    {
        Route.Fallback(),
        Reply.Status(HttpStatusCode.NotFound)
    },
    {
        Route.Get("/get"),
        Reply.Status(HttpStatusCode.OK)
    },
    {
        Route.Post("/post"),
        Reply.Status(HttpStatusCode.Created)
    },
    {
        Route.Any("/any"),
        Reply.Status(HttpStatusCode.Accepted)
    },
};
using HttpClient httpClient = new HttpClient(http, disposeHandler: false);
using HttpResponseMessage get = await httpClient.GetAsync(new Uri("https://api.example.com/get")); // get.StatusCode == OK
using HttpResponseMessage post = await httpClient.PostAsync(new Uri("https://api.example.com/post"), null); // post.StatusCode == Created
using HttpResponseMessage delete = await httpClient.DeleteAsync(new Uri("https://api.example.com/any")); // delete.StatusCode == Accepted, Route.Any matches every method
using HttpResponseMessage missing = await httpClient.GetAsync(new Uri("https://api.example.com/missing")); // missing.StatusCode == NotFound, from Route.Fallback()

• Route.Get, Post, Put, Delete, Patch and Head each match one HTTP method.
• Route.For takes an HttpMethod, such as HttpMethod.Options, for a method with no factory of its own.
• Route.Any matches the path with any method.
• Route.Fallback() matches every request. A fallback route is tried only after every other route fails to match.

The fallback comes first in the list, yet the /get request still reaches its own route. Only /missing, which no other route matches, gets the fallback's 404. Without a fallback, an unmatched request throws InvalidOperationException.

The sample sends through a plain HttpClient built on the stub. That checks the stub's rules alone, and it needs no JSON metadata. disposeHandler: false leaves the stub for its own using to dispose. For a full Refit test, use the generated client and JSON context.

Path and priority rules¶

Template is required. A leading / matches the request's absolute path. An absolute template compares scheme, host and path. "*" accepts any path. A complete {name} segment matches one nonempty segment. It does not expose a captured parameter. An embedded placeholder, such as person-{id}, is literal text. Literal segments compare case-sensitively. Segment counts and trailing slashes matter. A query written inside a template is ignored. Set a query property to check it.

The handler tries one-shot expectations, then reusable routes, then fallbacks. Within each group it uses declaration order. It does not rank routes by path detail. A one-shot route is consumed after matching. Add identical routes in order to supply a sequence of replies. Reusable=true allows repeated matches and removes the verification requirement. Fallback=true gives the final priority and also removes the verification requirement. A manually configured fallback must pass its other conditions. Route.Fallback() accepts everything. An unmatched request throws InvalidOperationException; it does not return an automatic 404.

Check queries, headers and bodies¶

You may need a route to match only when a request carries a certain header, form field or other detail. Build a RouteMatcher yourself and set the conditions you need. The request must pass every condition you set. This Testing.cs sample sets Headers, FormData and Where.

RouteMatcher route = new RouteMatcher
{
    Method = HttpMethod.Post,
    Template = "/people/{id}",
    Headers = [("X-Test", "yes")],
    FormData = [("name", "Ada Lovelace")],
    Where = static request => request.RequestUri!.Host == "api.example.com",
};
using StubHttp http = new StubHttp { { route, Reply.Text("matched") } };
using HttpClient httpClient = new HttpClient(http, disposeHandler: false);
using HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Post, "https://api.example.com/people/7")
{
    Content = new FormUrlEncodedContent(
    [
        new KeyValuePair<string, string>("name", "Ada Lovelace"),
    ]),
};
request.Headers.Add("X-Test", "yes");
using HttpResponseMessage response = await httpClient.SendAsync(request); // response body == "matched"

Headers looks for X-Test: yes. FormData looks for the name field in the form body. Where runs your lambda on the request, here to check the host. The lambda captures nothing, so it is marked static. The route's reply is "matched" only because all three checks pass, along with the method and path.

These are all the properties you can set on a RouteMatcher:

The stub checks the method, the path, the query properties and Headers first. Then it checks Body and FormData, then Where, then WhereAsync. It stops at the first check that fails.

Query and form decoding converts + to a space and decodes percent escapes. Bare keys have empty values. Empty entries between & characters are ignored. Keys and values compare case-sensitively. All three query properties can be used together. ExactQuery checks decoded content, despite its string argument. It does not check raw byte spelling or pair order. Predicates run after the built-in checks and receive no cancellation token. Body buffering makes content rereadable when buffering succeeds.

Body and FormData read the request body, so they need the stub's default RequestCapture.Full setting. With any other RequestCapture setting, a route that sets either one throws InvalidOperationException when the stub tries to match it.

Duplicate-query discrepancy¶

You might expect an exact-query route for a=1&a=1 to need two a=1 pairs. It does not. The stub compares the pair count and checks that each expected pair is present. It does not count how many times a pair occurs. This Testing.cs sample shows the current behavior for both exact-query properties.

using StubHttp http = new StubHttp
{
    {
        new RouteMatcher { Template = "/query", ExactQueryParams = [("a", "1"), ("a", "1")] },
        Reply.Text("matched ExactQueryParams")
    },
    {
        new RouteMatcher { Template = "/query", ExactQuery = "a=1&a=1" },
        Reply.Text("matched ExactQuery")
    },
};
using HttpClient httpClient = new HttpClient(http, disposeHandler: false);
using HttpResponseMessage pairs = await httpClient.GetAsync(new Uri("https://api.example.com/query?a=1&b=2")); // matched ExactQueryParams, even though "a" is not duplicated

// Each route answers once, so this second request can only match the ExactQuery route, and it accepts it too.
using HttpResponseMessage encoded = await httpClient.GetAsync(new Uri("https://api.example.com/query?a=1&b=2")); // matched ExactQuery: "a=1&a=1" also accepts a query with a single a=1

The request a=1&b=2 has two pairs, and a=1 is one of them. That satisfies the ExactQueryParams route, which answers the first request. The second request can only reach the ExactQuery route, and it passes there too.

Avoid duplicate pairs in exact-query routes. When the number of repeats matters, parse and count the pairs in Where.

Send requests to a one-shot route one at a time. Two requests that arrive together can both match it before the stub marks it used. Two requests on one one-shot route shows the result.

List the configured routes¶

StubHttp implements IEnumerable<RouteMatcher>, so LINQ works on it. For example, http.Select(static route => route.Template) lists each route's template. Both enumeration interfaces return a snapshot of the configured routes.

API reference¶