improvement(#60): Document DbContextFactory, added TestContainers

Author: jhartmann123

.gitlab-ci.yml

@@ -18,6 +18,13 @@ stages:
 
 variables:
   BUILD_IMAGE: mcr.microsoft.com/dotnet/sdk:10.0
+  DOCKER_VERSION: "29"
+  DOCKER_BUILDKIT: 1
+  DOCKER_HOST: tcp://docker:2376
+  DOCKER_TLS_CERTDIR: "/certs/${CI_JOB_ID}"
+  DOCKER_TLS_VERIFY: 1
+  DOCKER_CERT_PATH: "/certs/${CI_JOB_ID}/client"
+  TESTCONTAINERS_RYUK_DISABLED: "true" # Disable Ryuk as we're running in dind-rootless and there is no docker.sock available.
 
 default:
   interruptible: true
@@ -45,12 +52,7 @@ build:
 
 dotnet:test:
   services:
-    - name: postgres:17
-      alias: postgres
-  variables:
-    POSTGRES_PASSWORD: admin
-    ConnectionStrings__Npgsql: Host=postgres;Database=test_npgsql;Username=postgres;Password=admin
-    ConnectionStrings__Hangfire: Host=postgres;Database=test_hangfire;Username=postgres;Password=admin
+    - docker:${DOCKER_VERSION}-dind-rootless
 
 release:lint-merge-request:
   stage: test

Extensions.slnx

@@ -16,6 +16,7 @@
     <Project Path="src/Hosting/test/Hosting.Tests.csproj" />
     <Project Path="src/Mediator/test/Mediator.Tests.csproj" />
     <Project Path="src/UnitTests.EntityFrameworkCore.Npgsql/test/UnitTests.EntityFrameworkCore.Npgsql.Tests.csproj" />
+    <Project Path="src/UnitTests.EntityFrameworkCore.SqlServer/test/UnitTests.EntityFrameworkCore.SqlServer.Tests.csproj" />
     <Project Path="src/UnitTests.EntityFrameworkCore/test/UnitTests.EntityFrameworkCore.Tests.csproj" />
   </Folder>
   <Project Path="src/AspNetCore/src/AspNetCore.csproj" />
@@ -25,6 +26,7 @@
   <Project Path="src/Hangfire/src/Hangfire.csproj" />
   <Project Path="src/Hosting/src/Hosting.csproj" />
   <Project Path="src/Mediator/src/Mediator.csproj" />
+  <Project Path="src/TestContainers/src/TestContainers.csproj" />
   <Project Path="src/UnitTests.EntityFrameworkCore.Npgsql/src/UnitTests.EntityFrameworkCore.Npgsql.csproj" />
   <Project Path="src/UnitTests.EntityFrameworkCore.SqlServer/src/UnitTests.EntityFrameworkCore.SqlServer.csproj" />
   <Project Path="src/UnitTests.EntityFrameworkCore/src/UnitTests.EntityFrameworkCore.csproj" />

README.md

@@ -39,14 +39,11 @@ Provides services and extensions for hosting. See the [documentation](docs/Hosti
 [![NuGet](https://img.shields.io/nuget/v/Fusonic.Extensions.Mediator.svg?label=Fusonic.Extensions.Mediator&style=plastic)](https://www.nuget.org/packages/Fusonic.Extensions.Mediator/)
 Provides simple mediator implementation. See the [documentation](docs/Mediator/README.md) for more details.
 
-[![NuGet](https://img.shields.io/nuget/v/Fusonic.Extensions.UnitTests.svg?label=Fusonic.Extensions.UnitTests&style=plastic)](https://www.nuget.org/packages/Fusonic.Extensions.UnitTests/)
-Xunit-based testing base classes with support for dependency injection. Libraries supporting specific DI containers (SimpleInjector, ServiceProvider) are in separate packages. See the [unit test documentation](docs/UnitTests/README.md) for more details.
-
-[![NuGet](https://img.shields.io/nuget/v/Fusonic.Extensions.UnitTests.ServiceProvider.svg?label=Fusonic.Extensions.UnitTests.ServiceProvider&style=plastic)](https://www.nuget.org/packages/Fusonic.Extensions.UnitTests.ServiceProvider/)
-Xunit-based testing base classes. Supports dependency injection with Microsofts Dependency Injection framework (ServiceProvider).. See the [unit test documentation](docs/UnitTests/README.md) for more details.
+[![NuGet](https://img.shields.io/nuget/v/Fusonic.Extensions.TestContainers.svg?label=Fusonic.Extensions.TestContainers&style=plastic)](https://www.nuget.org/packages/Fusonic.Extensions.TestContainers/)
+Provides simple mediator implementation. See the [documentation](docs/Mediator/README.md) for more details.
 
-[![NuGet](https://img.shields.io/nuget/v/Fusonic.Extensions.UnitTests.SimpleInjector.svg?label=Fusonic.Extensions.UnitTests.SimpleInjector&style=plastic)](https://www.nuget.org/packages/Fusonic.Extensions.UnitTests.SimpleInjector/)
-Xunit-based testing base classes. Supports dependency injection with SimpleInjector.. See the [unit test documentation](docs/UnitTests/README.md) for more details.
+[![NuGet](https://img.shields.io/nuget/v/Fusonic.Extensions.UnitTests.svg?label=Fusonic.Extensions.UnitTests&style=plastic)](https://www.nuget.org/packages/Fusonic.Extensions.UnitTests/)
+Experimental package that provides a simple TestContainer setup for XUnit v3 test assemblies. See the [test containers documentation](docs/TestContainers/README.md) for more details.
 
 [![NuGet](https://img.shields.io/nuget/v/Fusonic.Extensions.UnitTests.EntityFrameworkCore.svg?label=Fusonic.Extensions.UnitTests.EntityFrameworkCore&style=plastic)](https://www.nuget.org/packages/Fusonic.Extensions.UnitTests.EntityFrameworkCore/)
 Adds database support using EF Core to the unit tests. See the [unit test documentation](docs/UnitTests/README.md) for more details.

docs/TestContainers/README.md

@@ -0,0 +1,58 @@
+# Test containers
+
+EXPERIMENTAL. APIs might change any time as this library is currently only targeted for internal testing.
+
+`Fusonic.Extensions.TestContainers` provides XUnit v3 startup classes that start some commonly used test containers.
+
+When running the tests within a GitLab, GitHub or Azure DevOps-CI pipeline, the test containers get random names and get cleaned up after test execution.
+
+Outside of a (known) CI pipeline, the test containers get stable names and do not get cleaned up after test execution. This is intended to speed up repeated test execution in local dev environments.
+
+Example usage:
+```cs
+// In your test Project
+using MyProject.Tests;
+using Microsoft.Data.SqlClient;
+using Xunit.Sdk;
+using Xunit.v3;
+
+[assembly: TestPipelineStartup(typeof(TestStartup))]
+
+namespace MyProject.Tests;
+
+public class TestStartup : TestContainerStartup
+{
+    public static string ConnectionString { get; private set; } = null!;
+
+    public override async ValueTask StartAsync(IMessageSink diagnosticMessageSink)
+    {
+        var container = await StartMsSql();
+        ConnectionString = new SqlConnectionStringBuilder(container.GetConnectionString())
+        {
+            InitialCatalog = "testtemplate"
+        }.ConnectionString;
+    }
+}
+```
+
+## Running in GitLab
+
+In order to use TestContainers in GitLab, start `docker:dind-rootless` as a service. When running rootless dind, you also must set `TESTCONTAINERS_RYUK_DISABLED` to `true`, as there is no `docker.sock` available. Ryuk is responsible for cleaning up the test containers, even when test jobs get cancelled. Disabling it should be safe though, as the containers started within `docker:dind` get cleaned up anyway.
+
+Example:
+```yaml
+variables:
+  DOCKER_VERSION: "29"
+  DOCKER_BUILDKIT: 1
+  DOCKER_HOST: tcp://docker:2376
+  DOCKER_TLS_CERTDIR: "/certs/${CI_JOB_ID}"
+  DOCKER_TLS_VERIFY: 1
+  DOCKER_CERT_PATH: "/certs/${CI_JOB_ID}/client"
+  TESTCONTAINERS_RYUK_DISABLED: "true" # Disable Ryuk as we're running in dind-rootless and there is no docker.sock available.
+
+dotnet:test:
+  services:
+    - docker:${DOCKER_VERSION}-dind-rootless
+  script:
+    - echo "Running Tests..."
+```

docs/UnitTests/README.md

@@ -167,6 +167,12 @@ public class TestFixture : ServiceProviderTestFixture
 
 The interface of `ITestStore` is straight forward. You can easily replace your test store with something else for another strategy or for supporting other databases.
 
+When using `IDbContextFactory`, the factory must be registered with scoped lifetime, not with the default singleton lifetime.  
+
+```cs
+services.AddDbContext<AppDbContext>(b => b.UseNpgsqlDatabasePerTest(testStore), ServiceLifetime.Scoped);
+```
+
 ### PostgreSQL - Template
 
 When using the `NpgsqlDatabasePerTest` it is assumed that you use a prepared database template. This template should have all migrations applied and may contain some seeded data. Each test gets a copy of this template. With the `PostgreSqlUtil`, we provide an easy way to create such a template.
@@ -254,6 +260,11 @@ The connection string must have the `Intial catalog` set. It determines the name
 
 The `TemplateCreator` specifies the method to create a template. It has to create and seed the database and create a backup for the copies used for the tests. Fortunately, the `SqlServerTestUtil` provides a method to do exactly that.
 
+When using `IDbContextFactory`, the factory must be registered with scoped lifetime, not with the default singleton lifetime.  
+
+```cs
+services.AddDbContext<AppDbContext>(b => b.UseSqlServerDatabasePerTest(testStore), ServiceLifetime.Scoped);
+```
 
 ### Configuring any other database
 

src/Directory.Packages.props

@@ -11,6 +11,7 @@
     <PackageVersion Include="Hangfire.Core" Version="1.8.21" />
     <PackageVersion Include="Hangfire.PostgreSql" Version="1.20.12" />
     <PackageVersion Include="MailKit" Version="4.14.1" />
+    <PackageVersion Include="Microsoft.Data.SqlClient" Version="6.1.3" />
     <PackageVersion Include="Microsoft.EntityFrameworkCore.Design" Version="10.0.0-rc.1.25451.107" />
     <PackageVersion Include="Microsoft.EntityFrameworkCore.InMemory" Version="10.0.0-rc.1.25451.107" />
     <PackageVersion Include="Microsoft.EntityFrameworkCore.Relational" Version="10.0.0-rc.1.25451.107" />
@@ -32,6 +33,7 @@
     <PackageVersion Include="Microsoft.Testing.Extensions.TrxReport" Version="1.8.4" />
     <PackageVersion Include="netDumbster" Version="3.1.1" />
     <PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />
+    <PackageVersion Include="Npgsql" Version="9.0.4" />
     <PackageVersion Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="10.0.0-rc.1" />
     <PackageVersion Include="NSubstitute" Version="5.3.0" />
     <PackageVersion Include="OpenTelemetry.Api" Version="1.13.1" />
@@ -43,6 +45,9 @@
     <PackageVersion Include="SimpleInjector.Integration.GenericHost" Version="5.5.0" />
     <PackageVersion Include="SimpleInjector" Version="5.5.0" />
     <PackageVersion Include="SimpleInjector.Integration.ServiceCollection" Version="5.5.0" />
+    <PackageVersion Include="Testcontainers.MsSql" Version="4.8.1" />
+    <PackageVersion Include="Testcontainers.PostgreSql" Version="4.8.1" />
+    <PackageVersion Include="xunit.abstractions" Version="2.0.3" />
     <PackageVersion Include="xunit.runner.visualstudio" Version="3.1.5" />
     <PackageVersion Include="xunit.v3.core" Version="3.1.0" />
     <PackageVersion Include="xunit.analyzers" Version="1.24.0" />

src/Email/test/SendEmailWithMockedClientTests.cs

@@ -2,13 +2,11 @@
 // Licensed under the MIT License. See LICENSE file in the project root for license information.
 
 using System.Globalization;
-using AwesomeAssertions;
 using Fusonic.Extensions.Email.Tests.Models;
 using MimeKit;
 using NSubstitute;
 using NSubstitute.ClearExtensions;
 using SimpleInjector;
-using Xunit;
 
 namespace Fusonic.Extensions.Email.Tests;
 

src/Hangfire/test/Hangfire.Tests.csproj

@@ -33,15 +33,10 @@
     </ItemGroup>
 
     <ItemGroup>
+        <ProjectReference Include="..\..\TestContainers\src\TestContainers.csproj" />
         <ProjectReference Include="..\..\UnitTests.EntityFrameworkCore.Npgsql\src\UnitTests.EntityFrameworkCore.Npgsql.csproj" />
         <ProjectReference Include="..\..\UnitTests.EntityFrameworkCore\src\UnitTests.EntityFrameworkCore.csproj" />
         <ProjectReference Include="..\..\UnitTests\src\UnitTests.csproj" />
         <ProjectReference Include="..\src\Hangfire.csproj" />
     </ItemGroup>
-
-    <ItemGroup>
-      <None Update="testsettings.json">
-        <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
-      </None>
-    </ItemGroup>
 </Project>

src/Hangfire/test/TestFixture.cs

@@ -51,7 +51,7 @@ private void RegisterDatabase(IServiceCollection services)
         var testStoreOptions = new NpgsqlDatabasePerTestStoreOptions
         {
             TemplateCreator = CreateDatabase,
-            ConnectionString = Configuration.GetConnectionString("Hangfire")!
+            ConnectionString = TestStartup.ConnectionString
         };
 
         var testStore = new NpgsqlDatabasePerTestStore(testStoreOptions);

src/Hangfire/test/TestStartup.cs

@@ -0,0 +1,25 @@
+// Copyright (c) Fusonic GmbH. All rights reserved.
+// Licensed under the MIT License. See LICENSE file in the project root for license information.
+
+using Fusonic.Extensions.Hangfire.Tests;
+using Npgsql;
+using Xunit.Sdk;
+using Xunit.v3;
+
+[assembly: TestPipelineStartup(typeof(TestStartup))]
+
+namespace Fusonic.Extensions.Hangfire.Tests;
+
+public class TestStartup : TestContainerStartup
+{
+    public static string ConnectionString { get; private set; } = null!;
+
+    public override async ValueTask StartAsync(IMessageSink diagnosticMessageSink)
+    {
+        var container = await StartPostgreSql();
+        ConnectionString = new NpgsqlConnectionStringBuilder(container.GetConnectionString())
+        {
+            Database = "hangfire"
+        }.ConnectionString;
+    }
+}