Ridge

Ridge is a source generator that creates strongly typed HTTP clients for integration tests. HTTP clients generated by Ridge require the WebApplicationFactory. The use of the WebApplicationFactory allows Ridge to access internal components of ASP.NET and analyze them. This significantly improves route generation and allows implicit support of areas, routing without attributes, and so on.

Ridge supports .NET 6 and newer.

Quick links

• NuGet package
• Documentation

Example

// --------------------------------------------ExampleController.cs-------------------------------------------------[GenerateClient]// Notice the attributepublicclassExamplesController:Controller{[HttpGet("ReturnGivenNumber")]publicActionResult<int>ReturnGivenNumber([FromQuery]intinput){returninput;}}// ------------------------------------------Test.cs----------------------------------------------------------------[Test]publicasyncTaskCallControllerUsingRidge(){usingvarwebApplicationFactory=newWebApplicationFactory<Program>().WithRidge();// add ridge dependencies to WebApplicationFactoryvarclient=webApplicationFactory.CreateClient();// create instance of client generated by source generatorvarexamplesControllerClient=newExamplesControllerClient(client,webApplicationFactory.Services);varresponse=awaitexamplesControllerClient.ReturnGivenNumber(10);Assert.True(response.IsSuccessStatusCode);Assert.AreEqual(10,response.Result);}

Setup

• Mark controller with the [GenerateClient] attribute. This attribute tells the source generator to generate class *YourControllerName*Client in the assembly which contains the controller.
• Call WithRidge() extension method on WebApplicationFactory.
• Create instance of *YourControllerName*Client.
• Create requests using *YourControllerName*Client instance.

Hint: Use package RidgeDotNet.AspNetCore in your AspNetCore project instead of RidgeDotNet. RidgeDotNet.AspNetCore has minimal dependencies, preventing unnecessary test code in your project.

Best practices

• Use ActionResult<T> when possible to enable strongly typed response generation.
• Use [FromRoute], [FromQuery], [FromBody], and similar attributes when possible to ensure correct parameter mapping.
• Add a logger to check generated requests and responses when necessary. More information here.
• Use RethrowExceptionInsteadOfReturningHttpResponse for improved test experience.

Wiki

Full documentation can be found in the wiki.

Features that are not currently supported

Note that you can always fall back to WebApplicationFactory when you need to test something that is not supported by Ridge.

• Minimal API
• Custom request types. JSON is the only request type currently supported.
• Single action parameter transformations (add parameter to single action or transform parameter in single action)
• [FromForm] attributes
• Actions returning custom implementation of IActionResult.

Mappings that are not supported by default

Ridge supports a wide range of parameter mappings, but some special cases are currently not supported by default. Known unsupported mappings are the following:

• [FromQuery] with an array of complex arguments
• Complex types with [FromXXX] attributes on properties

Example of [FromQuery] with an array of complex arguments:

publicvirtualActionResultNotSupported([FromQuery]IEnumerable<ComplexArgument>complexArguments){//..}

Example of complex types with [FromXXX] attributes on properties:

publicvirtualActionResultNotSupported(Mixedmixed){//..}publicclassMixed{[FromBody]publicstringBodyName{get;set;}[FromHeader]publicstringHeaderName{get;set;}}

If you need to use this feature then consider writing custom HttpRequestFactoryMiddleware or creating an issue.

Contributions

Icon made by Freepik from www.flaticon.com.