feat+: add spec-like test driver (#13)

Author: ArwynFr

.github/README.md

@@ -10,7 +10,15 @@ License](https://img.shields.io/github/license/ArwynFr/dotnet-integration-testin
 
 ## Installation
 
-    dotnet add package ArwynFr.IntegrationTesting
+```shell
+dotnet new classlib -n MyTestProject
+```
+
+```shell
+dotnet add package ArwynFr.IntegrationTesting
+dotnet add pacakge Microsoft.NET.Test.Sdk
+dotnet add package xunit.runner.visualstudio
+```
 
 ## Usage
 
@@ -23,53 +31,100 @@ output, so you get them in the test output in case of failure. It also
 overwrites the application configuration with values from user secrets
 and environement variables.
 
-    public class MyTest : IntegrationTestBase<Program>
+```cs
+public class MyTest : IntegrationTestBase<Program>
+{
+    public MyTest(ITestOutputHelper output) : base(output) { }
+
+    [Fact]
+    public async Task OnTest()
     {
-        public MyTest(ITestOutputHelper output) : base(output) { }
+        // Call system under test
+        var response = await Client.GetFromJsonAsync<OrderDto>($"/order");
+
+        response.Should().HaveValue();
+    }
+
+    // Override a service with fake implementation in the tested app
+    protected override void ConfigureAppServices(IServiceCollection services)
+        => services.AddSingleton<IMyService, FakeService>();
+}
+```
+
+### EntityFrameworkCore integration
+
+```cs
+public class TestBaseDb : IntegrationTestBase<Program, MyDbContext>
+{
+    public TestBaseDb(ITestOutputHelper output) : base(output) { }
 
-        [Fact]
-        public async Task OnTest()
-        {
-            // Call system under test
-            var response = await Client.GetFromJsonAsync<OrderDto>($"/order");
+    [Fact]
+    public async Task OnTest()
+    {
+        // Access the injected dbcontext
+        var value = await Database.Values
+            .Where(val => val.Id == 1)
+            .Select(val => val.Result)
+            .FirstOrDefaultAsync();
 
-            response.Should().HaveValue();
-        }
+        // Call system under test
+        var result = await Client.GetFromJsonAsync<int>("/api/value/1");
 
-        // Override a service with fake implementation in the tested app
-        protected override void ConfigureAppServices(IServiceCollection services)
-            => services.AddSingleton<IMyService, FakeService>();
+        result.Should().Be(value + 1);
     }
 
-### EntityFrameworkCore integration
+    // Create and drop a database for every test execution
+    protected override IDatabaseTestStrategy<Context> DatabaseTestStrategy
+        => IDatabaseTestStrategy<MyDbContext>.DatabasePerTest;
+
+    // Configure EFcore with a random database name
+    protected override void ConfigureDbContext(DbContextOptionsBuilder builder)
+        => builder.UseSqlite($"Data Source={Guid.NewGuid()}.sqlite");
+}
+```
+
+### Fluent specification-based testing
+
+```cs
+// Actual code redacted for brievty
+// Write a test driver that implements specifications:
+private class MySpecDriver(MyDbContext dbContext, HttpClient client) : TestDriverBase<SpecDriver>
+{
+    // Arranges
+    public async Task ThereIsEntityWithName(string name) { }
+    public async Task ThereIsNoEntityWithName(string name) { }
+
+    // Acts
+    public async Task ListAllEntities() { }
+    public async Task FindEntityWithName(string name) { }
+    public async Task CreateEntity(EntityDetails payload) { }
+
+    // Asserts
+    public async Task ResultShouldBe(string name) { }
+    public async Task DetailsCountShouldBe(int number) { }
+}
+
+public class MySpecTest(ITestOutputHelper output) : TestBaseDb
+{
+    // Write fluent specifiation test:
+    [Theory, InlineData("ArwynFr")]
+    public async Task OnTest(string name)
+    {
+        await Services.GetRequiredService<MySpecDriver>()
+            .Given(x => x.ThereIsEntityWithName(name))
+            .When(x => x.FindEntityWithName(name))
+            .Then(x => x.ResultShouldBe(name))
+            .ExecuteAsync();
+    }
 
-    public class TestBaseDb : IntegrationTestBase<Program, MyDbContext>
+    // Configure DI library
+    protected override void ConfigureAppServices(IServiceCollection services)
     {
-        public TestBaseDb(ITestOutputHelper output) : base(output) { }
-
-        [Fact]
-        public async Task OnTest()
-        {
-            // Access the injected dbcontext
-            var value = await Database.Values
-                .Where(val => val.Id == 1)
-                .Select(val => val.Result)
-                .FirstOrDefaultAsync();
-
-            // Call system under test
-            var result = await Client.GetFromJsonAsync<int>("/api/value/1");
-
-            result.Should().Be(value + 1);
-        }
-
-        // Create and drop a database for every test execution
-        protected override IDatabaseTestStrategy<Context> DatabaseTestStrategy
-            => IDatabaseTestStrategy<MyDbContext>.DatabasePerTest;
-
-        // Configure EFcore with a random database name
-        protected override void ConfigureDbContext(DbContextOptionsBuilder builder)
-            => builder.UseSqlite($"Data Source={Guid.NewGuid()}.sqlite");
+        base.ConfigureAppServices(services);
+        services.AddSingleton(_ => new MySpecDriver(Database, Client));
     }
+}
+```
 
 ## Contributing
 

.github/USAGE.md

@@ -25,10 +25,12 @@ application behaves as expected.
 Simply extend the `IntegrationTestBase<TEntryPoint>` class and provide
 the entrypoint class you want to test:
 
-    public class MyTest : IntegrationTestBase<Program>
-    {
-        public MyTest(ITestOutputHelper output) : base(output) { }
-    }
+```cs
+public class MyTest : IntegrationTestBase<Program>
+{
+    public MyTest(ITestOutputHelper output) : base(output) { }
+}
+```
 
 ## Arranging the tested application
 
@@ -59,23 +61,25 @@ Singleton lifetime. Accessing the DI container outside of the client
 call will return an unscoped provider as scopes are created and disposed
 by the framework for each request.
 
-    // Override a service with custom implementation in the tested app
-    protected override void ConfigureAppServices(IServiceCollection services)
-        => services.AddSingleton<IMyService, FakeService>();
+```cs
+// Override a service with custom implementation in the tested app
+protected override void ConfigureAppServices(IServiceCollection services)
+    => services.AddSingleton<IMyService, FakeService>();
 
-    [Fact]
-    public async Task OnTest()
-    {
-        var expected = 3;
+[Fact]
+public async Task OnTest()
+{
+    var expected = 3;
 
-        // Access the injected service from the test code
-        var service = Services.GetRequiredService<IMyService>();
-        service.SetValue(expected);
+    // Access the injected service from the test code
+    var service = Services.GetRequiredService<IMyService>();
+    service.SetValue(expected);
 
-        var response = await Client.GetFromJsonAsync<int>($"/value");
+    var response = await Client.GetFromJsonAsync<int>($"/value");
 
-        response.Should().Be(expected);
-    }
+    response.Should().Be(expected);
+}
+```
 
 ## Accessing the tested application
 
@@ -84,14 +88,14 @@ You can access the tested application using the `Client` property which
 returns a pseudo `HttpClient` created by `WebApplicationFactory`. You
 access your application like a client application would:
 
-<!-- -->
-
-    [Fact]
-    public async Task OnTest()
-    {
-        var response = await Client.GetFromJsonAsync<OrderDto>($"/order");
-        response.Should().HaveValue();
-    }
+```cs
+[Fact]
+public async Task OnTest()
+{
+    var response = await Client.GetFromJsonAsync<OrderDto>($"/order");
+    response.Should().HaveValue();
+}
+```
 
 Configuration  
 This property grants you acces to the `IConfiguration` values that are
@@ -131,8 +135,10 @@ context instance will be generated per test and injected in your target
 app as a singleton. You can access the same context instance in your
 test through the `Database` property.
 
-        protected override void ConfigureDbContext(DbContextOptionsBuilder builder)
-            => builder.UseSqlite($"Data Source=test.sqlite");
+```cs
+protected override void ConfigureDbContext(DbContextOptionsBuilder builder)
+    => builder.UseSqlite($"Data Source=test.sqlite");
+```
 
 The base class also exposes a `DatabaseTestStrategy` property that
 allows you to customize the test behavior regarding the database. You
@@ -164,12 +170,12 @@ database in parallel. Otherwise the tests will try to access the same
 database concurrently and will fail to drop it while other tests are
 running:
 
-<!-- -->
-
-        protected override IDatabaseTestStrategy<Context> DatabaseTestStrategy
-            => IDatabaseTestStrategy<Context>.DatabasePerTest;
+```cs
+protected override IDatabaseTestStrategy<Context> DatabaseTestStrategy
+    => IDatabaseTestStrategy<Context>.DatabasePerTest;
 
-        protected override void ConfigureDbContext(DbContextOptionsBuilder builder)
-            => builder.UseSqlite($"Data Source={Guid.NewGuid()}.sqlite");
+protected override void ConfigureDbContext(DbContextOptionsBuilder builder)
+    => builder.UseSqlite($"Data Source={Guid.NewGuid()}.sqlite");
+```
 
 This beahvior WILL drop your database after each test !

.github/workflows/integration.yaml

@@ -66,6 +66,7 @@ jobs:
         with:
           files: .
           dot: true
+          config_file: ./markdownlint.yaml
 
   not-outdated:
     runs-on: ubuntu-latest

markdownlint.yaml

@@ -0,0 +1,3 @@
+default: true
+MD046:
+    style: fenced

src/ArwynFr.IntegrationTesting.Tests.Target/DummyController.cs

@@ -0,0 +1,21 @@
+using Microsoft.AspNetCore.Http.HttpResults;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.EntityFrameworkCore;
+
+namespace ArwynFr.IntegrationTesting.Tests.Target;
+
+[ApiController]
+public class DummyController : ControllerBase
+{
+    private readonly DummyDbContext _dbContext;
+
+    public DummyController(DummyDbContext dbContext) => _dbContext = dbContext;
+
+    [HttpGet("/api/entities/{name}")]
+    public async Task<Results<Ok<string>, NotFound<string>>> ExecuteAsync(string name)
+    {
+        var value = await _dbContext.Entities.FirstOrDefaultAsync(entity => entity.Name == name);
+        if (value == null) { return TypedResults.NotFound("Not found"); }
+        return TypedResults.Ok(value.Name);
+    }
+}

src/ArwynFr.IntegrationTesting.Tests.Target/DummyDbContext.cs

@@ -8,6 +8,8 @@ public class DummyDbContext : DbContext
 {
     public DummyDbContext(DbContextOptions options) : base(options) => Expression.Empty();
 
+    public DbSet<DummyEntity> Entities => Set<DummyEntity>();
+
     protected override void OnModelCreating(ModelBuilder modelBuilder)
         => modelBuilder.ApplyConfigurationsFromAssembly(GetType().Assembly);
 }

src/ArwynFr.IntegrationTesting.Tests.Target/DummyEntity.cs

@@ -0,0 +1,8 @@
+namespace ArwynFr.IntegrationTesting.Tests.Target;
+
+public class DummyEntity
+{
+    public int Id { get; init; }
+
+    public required string Name { get; init; }
+}

src/ArwynFr.IntegrationTesting.Tests.Target/Program.cs

@@ -3,10 +3,12 @@
 var builder = WebApplication.CreateBuilder(args);
 builder.Services.AddScoped<IDummyService, DummyService>();
 builder.Services.AddSqlite<DummyDbContext>("invalid");
+builder.Services.AddControllers();
 var app = builder.Build();
 app.MapGet("/", () => "Hello World!");
 app.MapGet("/error", () => { throw new DummyException(); });
 app.MapGet("/service", (IDummyService service) => service.GetHashCode());
+app.MapControllers();
 app.Run();
 
 public partial class Program;

src/ArwynFr.IntegrationTesting.Tests/DriverTest.cs

@@ -0,0 +1,34 @@
+using ArwynFr.IntegrationTesting.Tests.Target;
+
+using Microsoft.EntityFrameworkCore;
+using Microsoft.Extensions.DependencyInjection;
+
+using Xunit;
+using Xunit.Abstractions;
+
+namespace ArwynFr.IntegrationTesting.Tests;
+
+public partial class DriverTest(ITestOutputHelper output) : IntegrationTestBase<Program, DummyDbContext>(output)
+{
+    [Theory, InlineData("random")]
+    public async Task ExecuteAsync(string name)
+    {
+        await Services.GetRequiredService<DummyDriver>()
+            .Given(x => x.ThereIsAnEntity(name))
+            .When(x => x.FindEntityByName(name))
+            .Then(x => x.ResultShouldBe(name))
+            .ExecuteAsync();
+    }
+
+    protected override void ConfigureAppServices(IServiceCollection services)
+    {
+        base.ConfigureAppServices(services);
+        services.AddSingleton(_ => new DummyDriver(Database, Client));
+    }
+
+    protected override void ConfigureDbContext(DbContextOptionsBuilder builder)
+    => builder.UseSqlite($"Data Source={Guid.NewGuid()}.sqlite");
+
+    protected override IDatabaseTestStrategy<DummyDbContext> DatabaseTestStrategy
+    => IDatabaseTestStrategy<DummyDbContext>.DatabasePerTest;
+}