feat: Introduce a new Testcontainers.Xunit package

.github/workflows/cicd.yml

@@ -78,7 +78,8 @@ jobs:
           { name: "Testcontainers.RavenDb", runs-on: "ubuntu-22.04" },
           { name: "Testcontainers.Redis", runs-on: "ubuntu-22.04" },
           { name: "Testcontainers.Redpanda", runs-on: "ubuntu-22.04" },
-          { name: "Testcontainers.WebDriver", runs-on: "ubuntu-22.04" }
+          { name: "Testcontainers.WebDriver", runs-on: "ubuntu-22.04" },
+          { name: "Testcontainers.Xunit", runs-on: "ubuntu-22.04" }
         ]
 
     runs-on: ${{ matrix.test-projects.runs-on }}

Directory.Packages.props

@@ -17,8 +17,11 @@
         <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.11.1"/>
         <PackageVersion Include="Microsoft.Extensions.Diagnostics.Testing" Version="8.10.0"/>
         <PackageVersion Include="coverlet.collector" Version="6.0.2"/>
+        <PackageVersion Include="Dapper" Version="2.1.35"/>
         <PackageVersion Include="ReflectionMagic" Version="5.0.1"/>
+        <PackageVersion Include="xunit.extensibility.execution" Version="2.9.0"/>
         <PackageVersion Include="xunit.runner.visualstudio" Version="2.8.2"/>
+        <PackageVersion Include="xunit.v3.extensibility.core" Version="0.2.0-pre.69"/>
         <PackageVersion Include="xunit" Version="2.9.2"/>
         <!-- Third-party client dependencies to connect and interact with the containers: -->
         <PackageVersion Include="Apache.NMS.ActiveMQ" Version="2.1.0"/>

Testcontainers.sln

@@ -97,6 +97,10 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Testcontainers.Redpanda", "
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Testcontainers.WebDriver", "src\Testcontainers.WebDriver\Testcontainers.WebDriver.csproj", "{64A87DE5-29B0-4A54-9E74-560484D8C7C0}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Testcontainers.Xunit", "src\Testcontainers.Xunit\Testcontainers.Xunit.csproj", "{380BB29B-F556-404D-B13B-CA250599C565}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Testcontainers.XunitV3", "src\Testcontainers.XunitV3\Testcontainers.XunitV3.csproj", "{84911C93-C2A9-46E9-AE5E-D567306589E5}"
+EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Testcontainers", "src\Testcontainers\Testcontainers.csproj", "{EC76857B-A3B8-4B7A-A1B0-8D867A4D1733}"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Testcontainers.ActiveMq.Tests", "tests\Testcontainers.ActiveMq.Tests\Testcontainers.ActiveMq.Tests.csproj", "{AB93C67F-0A53-4525-AE6C-29B065820ABE}"
@@ -195,6 +199,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Testcontainers.Tests", "tes
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Testcontainers.WebDriver.Tests", "tests\Testcontainers.WebDriver.Tests\Testcontainers.WebDriver.Tests.csproj", "{EBA72C3B-57D5-43FF-A5B4-3D55B3B6D4C2}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Testcontainers.Xunit.Tests", "tests\Testcontainers.Xunit.Tests\Testcontainers.Xunit.Tests.csproj", "{E901DF14-6F05-4FC2-825A-3055FAD33561}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -372,6 +378,14 @@ Global
 		{64A87DE5-29B0-4A54-9E74-560484D8C7C0}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{64A87DE5-29B0-4A54-9E74-560484D8C7C0}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{64A87DE5-29B0-4A54-9E74-560484D8C7C0}.Release|Any CPU.Build.0 = Release|Any CPU
+		{380BB29B-F556-404D-B13B-CA250599C565}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{380BB29B-F556-404D-B13B-CA250599C565}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{380BB29B-F556-404D-B13B-CA250599C565}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{380BB29B-F556-404D-B13B-CA250599C565}.Release|Any CPU.Build.0 = Release|Any CPU
+		{84911C93-C2A9-46E9-AE5E-D567306589E5}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{84911C93-C2A9-46E9-AE5E-D567306589E5}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{84911C93-C2A9-46E9-AE5E-D567306589E5}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{84911C93-C2A9-46E9-AE5E-D567306589E5}.Release|Any CPU.Build.0 = Release|Any CPU
 		{EC76857B-A3B8-4B7A-A1B0-8D867A4D1733}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{EC76857B-A3B8-4B7A-A1B0-8D867A4D1733}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{EC76857B-A3B8-4B7A-A1B0-8D867A4D1733}.Release|Any CPU.ActiveCfg = Release|Any CPU
@@ -568,6 +582,10 @@ Global
 		{EBA72C3B-57D5-43FF-A5B4-3D55B3B6D4C2}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{EBA72C3B-57D5-43FF-A5B4-3D55B3B6D4C2}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{EBA72C3B-57D5-43FF-A5B4-3D55B3B6D4C2}.Release|Any CPU.Build.0 = Release|Any CPU
+		{E901DF14-6F05-4FC2-825A-3055FAD33561}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{E901DF14-6F05-4FC2-825A-3055FAD33561}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{E901DF14-6F05-4FC2-825A-3055FAD33561}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{E901DF14-6F05-4FC2-825A-3055FAD33561}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
 		{5365F780-0E6C-41F0-B1B9-7DC34368F80C} = {673F23AE-7694-4BB9-ABD4-136D6C13634E}
@@ -612,6 +630,8 @@ Global
 		{BFDA179A-40EB-4CEB-B8E9-0DF32C65E2C5} = {673F23AE-7694-4BB9-ABD4-136D6C13634E}
 		{45D6F69C-4D87-4130-AA90-0DB2F7460DAE} = {673F23AE-7694-4BB9-ABD4-136D6C13634E}
 		{64A87DE5-29B0-4A54-9E74-560484D8C7C0} = {673F23AE-7694-4BB9-ABD4-136D6C13634E}
+		{380BB29B-F556-404D-B13B-CA250599C565} = {673F23AE-7694-4BB9-ABD4-136D6C13634E}
+		{84911C93-C2A9-46E9-AE5E-D567306589E5} = {673F23AE-7694-4BB9-ABD4-136D6C13634E}
 		{EC76857B-A3B8-4B7A-A1B0-8D867A4D1733} = {673F23AE-7694-4BB9-ABD4-136D6C13634E}
 		{AB93C67F-0A53-4525-AE6C-29B065820ABE} = {7164F1FB-7F24-444A-ACD2-2C329C2B3CCF}
 		{8E1E0A6D-EEBB-4455-B8E8-A55AF9B2062C} = {7164F1FB-7F24-444A-ACD2-2C329C2B3CCF}
@@ -661,5 +681,6 @@ Global
 		{9E8E6AA5-65D1-498F-BEAB-BA34723A0050} = {7164F1FB-7F24-444A-ACD2-2C329C2B3CCF}
 		{27CDB869-A150-4593-958F-6F26E5391E7C} = {7164F1FB-7F24-444A-ACD2-2C329C2B3CCF}
 		{EBA72C3B-57D5-43FF-A5B4-3D55B3B6D4C2} = {7164F1FB-7F24-444A-ACD2-2C329C2B3CCF}
+		{E901DF14-6F05-4FC2-825A-3055FAD33561} = {7164F1FB-7F24-444A-ACD2-2C329C2B3CCF}
 	EndGlobalSection
 EndGlobal

docs/test_frameworks/xunit_net.md

@@ -0,0 +1,109 @@
+# Testing with xUnit.net
+
+The [Testcontainers.Xunit](https://www.nuget.org/packages/Testcontainers.Xunit) package simplifies writing tests with containers in [xUnit.net](https://xunit.net). By leveraging xUnit.net's [shared context](https://xunit.net/docs/shared-context), this package automates the setup and teardown of test resources, creating and disposing of containers as needed. This reduces repetitive code and avoids common patterns that developers would otherwise need to implement repeatedly.
+
+To get started, add the following dependency to your project file:
+
+```shell title="NuGet"
+dotnet add package Testcontainers.Xunit
+```
+
+## Creating an isolated test context
+
+To create a new test resource instance for each test, inherit from the `ContainerTest<TBuilderEntity, TContainerEntity>` class. Each test resource instance is isolated and not shared across other tests, making this approach ideal for destructive operations that could interfere with other tests. You can access the generic `TContainerEntity` container instance through the `Container` property.
+
+The example below demonstrates how to override the `Configure(TBuilderEntity)` method and pin the image version. This method allows you to configure the container instance specifically for your test case, with all container builder methods available. If your tests rely on a Testcontainers' module, the module's default configurations will be applied.
+
+=== "Configure a Redis Container"
+    ```csharp
+    --8<-- "tests/Testcontainers.Xunit.Tests/RedisContainerTest`1.cs:ConfigureRedisContainer"
+    ```
+
+!!!tip
+    Always pin the image version to avoid flakiness. This ensures consistency and prevents unexpected behavior, as the `latest` tag may pointing to a new version.
+
+The base class also receives an instance of xUnit.net's [ITestOutputHelper](https://xunit.net/docs/capturing-output) to capture and forward log messages to the running test.
+
+Considering that xUnit.net runs tests in a deterministic natural sort order (like `Test1`, `Test2`, etc.), retrieving the Redis (string) value in the second test will always return `null` since a new test resource instance (Redis container) is created for each test.
+
+=== "Run Tests"
+    ```csharp
+    --8<-- "tests/Testcontainers.Xunit.Tests/RedisContainerTest`1.cs:RunTests"
+    ```
+
+If you check the output of `docker ps`, you will notice that three container instances in total are run, with two of them being Redis instances.
+
+```title="List running containers"
+PS C:\Sources\dotnet\testcontainers-dotnet> docker ps
+CONTAINER ID   IMAGE                       COMMAND                  CREATED
+be115f3df138   redis:7.0                   "docker-entrypoint.s…"   3 seconds ago
+59349127f8c0   redis:7.0                   "docker-entrypoint.s…"   4 seconds ago
+45fa02b3e997   testcontainers/ryuk:0.9.0   "/bin/ryuk"              4 seconds ago
+```
+
+## Creating a shared test context
+
+Sometimes, creating and disposing of a test resource can be an expensive operation that you do not want to repeat for every test. By inheriting from the `ContainerFixture<TBuilderEntity, TContainerEntity>` class, you can share the test resource instance across all tests within the same test class.
+
+xUnit.net's fixture implementation does not rely on the `ITestOutputHelper` interface to capture and forward log messages; instead, it expects an implementation of `IMessageSink`. Make sure your fixture's default constructor accepts the interface implementation and forwards it to the base class.
+
+=== "Configure Redis Container"
+    ```csharp
+    --8<-- "tests/Testcontainers.Xunit.Tests/RedisContainerTest`2.cs:ConfigureRedisContainer"
+    ```
+
+This ensures that the fixture is created only once for the entire test class, which also improves overall test performance. You must implement the `IClassFixture<TFixture>` interface with the previously created container fixture type in your test class and add the type as argument to the default constructor.
+
+=== "Inject Redis Container"
+    ```csharp
+    --8<-- "tests/Testcontainers.Xunit.Tests/RedisContainerTest`2.cs:InjectContainerFixture"
+    ```
+
+In this case, retrieving the Redis (string) value in the second test will no longer return `null`. Instead, it will return the value added in the first test.
+
+=== "Run Tests"
+    ```csharp
+    --8<-- "tests/Testcontainers.Xunit.Tests/RedisContainerTest`2.cs:RunTests"
+    ```
+
+The output of `docker ps` shows that, instead of two Redis containers, only one runs.
+
+```title="List running containers"
+PS C:\Sources\dotnet\testcontainers-dotnet> docker ps
+CONTAINER ID   IMAGE                       COMMAND                  CREATED
+d29a393816ce   redis:7.0                   "docker-entrypoint.s…"   3 seconds ago
+e878f0b8f4bc   testcontainers/ryuk:0.9.0   "/bin/ryuk"              3 seconds ago
+```
+
+## Testing ADO.NET services
+
+In addition to the two mentioned base classes, the package contains two more classes: `DbContainerTest` and `DbContainerFixture`, which behave identically but offer additional convenient features when working with services accessible through an ADO.NET provider.
+
+Inherit from either the `DbContainerTest` or `DbContainerFixture` class and override the `Configure(TBuilderEntity)` method to configure your database service.
+
+In this example, we use the default configuration of the PostgreSQL module. The container image capabilities are used to instantiate the database, schema, and test data. During startup, the PostgreSQL container runs SQL scripts placed under the `/docker-entrypoint-initdb.d/` directory automatically.
+
+=== "Configure PostgreSQL Container"
+```csharp
+--8<-- "tests/Testcontainers.Xunit.Tests/PostgreSqlContainer.cs:ConfigurePostgreSqlContainer"
+```
+
+Inheriting from the database container test or fixture class requires you to implement the abstract `DbProviderFactory` property and resolve a compatible `DbProviderFactory` according to your ADO.NET service.
+
+=== "Configure DbProviderFactory"
+```csharp
+--8<-- "tests/Testcontainers.Xunit.Tests/PostgreSqlContainer.cs:ConfigureDbProviderFactory"
+```
+
+!!! note
+
+    Depending on how you initialize and access the database, it may be necessary to override the `ConnectionString` property and replace the default database name with the one actual in use.
+
+After configuring the dependent ADO.NET service, you can add the necessary tests. In this case, we run an SQL `SELECT` statement to retrieve the first record from the `album` table.
+
+=== "Run Tests"
+```csharp
+--8<-- "tests/Testcontainers.Xunit.Tests/PostgreSqlContainer.cs:RunTests"
+```
+
+--8<-- "docs/modules/_call_out_test_projects.txt"

mkdocs.yml

@@ -41,6 +41,7 @@ nav:
   - api/resource_reuse.md
   - api/wait_strategies.md
   - api/best_practices.md
+  - test_frameworks/xunit_net.md
   - Examples:
     - examples/dind.md
     - examples/aspnet.md

src/Testcontainers.Xunit/.editorconfig

@@ -0,0 +1 @@
+root = true

src/Testcontainers.Xunit/ContainerFixture.cs

@@ -0,0 +1,15 @@
+namespace Testcontainers.Xunit;
+
+/// <summary>
+/// Fixture for sharing a container instance across multiple tests in a single class.
+/// See <a href="https://xunit.net/docs/shared-context">Shared Context between Tests</a> from xUnit.net documentation for more information about fixtures.
+/// A logger is automatically configured to write diagnostic messages to xUnit's <see cref="IMessageSink" />.
+/// </summary>
+/// <param name="messageSink">An optional <see cref="IMessageSink" /> where the logs are written to. Pass <c>null</c> to ignore logs.</param>
+/// <typeparam name="TBuilderEntity">The builder entity.</typeparam>
+/// <typeparam name="TContainerEntity">The container entity.</typeparam>
+[PublicAPI]
+public class ContainerFixture<TBuilderEntity, TContainerEntity>(IMessageSink messageSink)
+    : ContainerLifetime<TBuilderEntity, TContainerEntity>(new MessageSinkLogger(messageSink))
+    where TBuilderEntity : IContainerBuilder<TBuilderEntity, TContainerEntity>, new()
+    where TContainerEntity : IContainer;

src/Testcontainers.Xunit/ContainerLifetime.cs

@@ -0,0 +1,91 @@
+namespace Testcontainers.Xunit;
+
+/// <summary>
+/// Base class managing the lifetime of a container.
+/// </summary>
+/// <typeparam name="TBuilderEntity">The builder entity.</typeparam>
+/// <typeparam name="TContainerEntity">The container entity.</typeparam>
+public abstract class ContainerLifetime<TBuilderEntity, TContainerEntity> : IAsyncLifetime
+    where TBuilderEntity : IContainerBuilder<TBuilderEntity, TContainerEntity>, new()
+    where TContainerEntity : IContainer
+{
+    private readonly Lazy<TContainerEntity> _container;
+
+    [CanBeNull]
+    private ExceptionDispatchInfo _exception;
+
+    protected ContainerLifetime(ILogger logger)
+    {
+        _container = new Lazy<TContainerEntity>(() => Configure(new TBuilderEntity().WithLogger(logger)).Build());
+    }
+
+    /// <summary>
+    /// Gets the container instance.
+    /// </summary>
+    public TContainerEntity Container
+    {
+        get
+        {
+            _exception?.Throw();
+            return _container.Value;
+        }
+    }
+
+    /// <inheritdoc />
+    LifetimeTask IAsyncLifetime.InitializeAsync() => InitializeAsync();
+
+#if !XUNIT_V3
+    /// <inheritdoc />
+    LifetimeTask IAsyncLifetime.DisposeAsync() => DisposeAsync();
+#else
+    /// <inheritdoc />
+    LifetimeTask IAsyncDisposable.DisposeAsync() => DisposeAsync();
+#endif
+
+    /// <summary>
+    /// Extension method to further configure the container instance.
+    /// </summary>
+    /// <example>
+    ///   <code>
+    ///   public class MariaDbRootUserFixture(IMessageSink messageSink) : DbContainerFixture&lt;MariaDbBuilder, MariaDbContainer&gt;(messageSink)
+    ///   {
+    ///     public override DbProviderFactory DbProviderFactory =&gt; MySqlConnectorFactory.Instance;
+    ///   <br />
+    ///     protected override MariaDbBuilder Configure(MariaDbBuilder builder)
+    ///     {
+    ///       return builder.WithUsername("root");
+    ///     }
+    ///   }
+    ///   </code>
+    /// </example>
+    /// <param name="builder">The container builder to configure.</param>
+    /// <returns>A configured instance of <typeparamref name="TBuilderEntity" />.</returns>
+    protected virtual TBuilderEntity Configure(TBuilderEntity builder)
+    {
+        return builder;
+    }
+
+    /// <inheritdoc cref="IAsyncLifetime" />
+    protected virtual async LifetimeTask InitializeAsync()
+    {
+        try
+        {
+            await Container.StartAsync()
+                .ConfigureAwait(false);
+        }
+        catch (Exception e)
+        {
+            _exception = ExceptionDispatchInfo.Capture(e);
+        }
+    }
+
+    /// <inheritdoc cref="IAsyncLifetime" />
+    protected virtual async LifetimeTask DisposeAsync()
+    {
+        if (_exception == null)
+        {
+            await Container.DisposeAsync()
+                .ConfigureAwait(false);
+        }
+    }
+}

src/Testcontainers.Xunit/ContainerTest.cs

@@ -0,0 +1,18 @@
+namespace Testcontainers.Xunit;
+
+/// <summary>
+/// Base class for tests needing a container per test method.
+/// A logger is automatically configured to write messages to xUnit's <see cref="ITestOutputHelper" />.
+/// </summary>
+/// <param name="testOutputHelper">An optional <see cref="ITestOutputHelper" /> where the logs are written to. Pass <c>null</c> to ignore logs.</param>
+/// <param name="configure">An optional callback to configure the container.</param>
+/// <typeparam name="TBuilderEntity">The builder entity.</typeparam>
+/// <typeparam name="TContainerEntity">The container entity.</typeparam>
+[PublicAPI]
+public abstract class ContainerTest<TBuilderEntity, TContainerEntity>(ITestOutputHelper testOutputHelper, Func<TBuilderEntity, TBuilderEntity> configure = null)
+    : ContainerLifetime<TBuilderEntity, TContainerEntity>(new TestOutputLogger(testOutputHelper))
+    where TBuilderEntity : IContainerBuilder<TBuilderEntity, TContainerEntity>, new()
+    where TContainerEntity : IContainer
+{
+    protected override TBuilderEntity Configure(TBuilderEntity builder) => configure != null ? configure(builder) : builder;
+}