[WIP] Testing with xUnit documentation

Author: 0xced

docs/api/testing_xunit.md

@@ -0,0 +1,65 @@
+# Testing with xUnit
+
+The [Testcontainers.Xunit](https://www.nuget.org/packages/Testcontainers.Xunit) package provides classes that simplify writing tests using Docker containers with [xUnit](https://xunit.net). Starting and disposing containers is handled automatically. Setting up logging is straightforward.
+
+## Use a container per test method
+
+If you need a fresh contaner per test method, inherit `ContainerTest<TBuilderEntity, TContainerEntity>` and use its `Container` property.
+
+```csharp
+using System.Threading.Tasks;
+using StackExchange.Redis;
+using Testcontainers.Redis;
+using Testcontainers.Xunit;
+using Xunit;
+using Xunit.Abstractions;
+
+namespace MyProject.Tests;
+
+public sealed class RedisContainerTest(ITestOutputHelper output)
+    : ContainerTest<RedisBuilder, RedisContainer>(output)
+{
+    protected override RedisBuilder Configure(RedisBuilder builder)
+    {
+        // 👇 Pin the Redis image to version 7.4.0 (alpine)
+        return builder.WithImage("redis:7.4.0-alpine");
+    }
+
+    [Fact]
+    public async Task Test1()
+    {
+        // 👆 A new fresh container is started before the test is run
+
+        // 👇 get the connection string from the container
+        var connectionString = Container.GetConnectionString();
+        using var redis = ConnectionMultiplexer.Connect(connectionString);
+        await redis.GetDatabase().StringSetAsync("key", "value");
+
+        // 👇 The container is disposed after the test has finished running
+    }
+
+    [Fact]
+    public async Task Test2()
+    {
+        // 👆 Another fresh container is started before the second test is run
+
+        var connectionString = Container.GetConnectionString();
+        using var redis = ConnectionMultiplexer.Connect(connectionString);
+        string value = await redis.GetDatabase().StringGetAsync("key");
+        Assert.Null(value); // 👈 value is null since the container is not shared
+
+        // 👇 The container is disposed after the test has finished running
+    }
+}
+```
+
+Injecting a `ITestOutputHelper` allows Testcontainers logs to be printed into the test runner output.
+
+## Use a container per test class
+
+Using a container per test method might be too heavy, especially if the container is slow to start. You might want to share a single container across all tests of a single class by using the `ContainerFixture<TBuilderEntity, TContainerEntity>` class that can be injected into your test classes.
+
+```csharp
+// TODO: sample code
+```
+

mkdocs.yml

@@ -35,6 +35,7 @@ nav:
   - api/resource_reuse.md
   - api/wait_strategies.md
   - api/best_practices.md
+  - api/testing_xunit.md
   - Examples:
     - examples/dind.md
     - examples/aspnet.md