docs(ClickHouse): Add example (#1421)

Co-authored-by: Andre Hofmeister <[email protected]>

Author: digital88

docs/modules/activemq.md

@@ -30,9 +30,9 @@ You can start an Apache ActiveMQ Artemis container instance from any .NET applic
 
 Connect to the container and produce a message:
 
-=== "EstablishesConnection"
+=== "Establish connection"
     ```csharp
-    --8<-- "tests/Testcontainers.ActiveMq.Tests/ArtemisContainerTest.cs:ArtemisContainerEstablishesConnection"
+    --8<-- "tests/Testcontainers.ActiveMq.Tests/ArtemisContainerTest.cs:EstablishConnection"
     ```
 
 The test example uses the following NuGet dependencies:

docs/modules/clickhouse.md

@@ -0,0 +1,42 @@
+# ClickHouse
+
+[ClickHouse](https://clickhouse.com/) is a high-performance, column-oriented SQL database management system (DBMS) for online analytical processing (OLAP).
+
+Add the following dependency to your project file:
+
+```shell title="NuGet"
+dotnet add package Testcontainers.ClickHouse
+```
+
+You can start a ClickHouse container instance from any .NET application. This example uses xUnit.net's `IAsyncLifetime` interface to manage the lifecycle of the container. The container is started in the `InitializeAsync` method before the test method runs, ensuring that the environment is ready for testing. After the test completes, the container is removed in the `DisposeAsync` method.
+
+=== "Test class"
+    ```csharp
+    --8<-- "tests/Testcontainers.ClickHouse.Tests/ClickHouseContainerTest.docs.cs:UseClickHouseContainer"
+    }
+    ```
+
+Connect to the container:
+
+=== "Establish connection"
+    ```csharp
+    --8<-- "tests/Testcontainers.ClickHouse.Tests/ClickHouseContainerTest.docs.cs:EstablishConnection"
+    ```
+
+Execute a SQL script:
+
+=== "Run SQL script"
+    ```csharp
+    --8<-- "tests/Testcontainers.ClickHouse.Tests/ClickHouseContainerTest.docs.cs:RunSQLScript"
+    ```
+
+The test example uses the following NuGet dependencies:
+
+=== "Package References"
+    ```xml
+    --8<-- "tests/Testcontainers.ClickHouse.Tests/Testcontainers.ClickHouse.Tests.csproj:PackageReferences"
+    ```
+
+To execute the tests, use the command `dotnet test` from a terminal.
+
+--8<-- "docs/modules/_call_out_test_projects.txt"

mkdocs.yml

@@ -53,6 +53,7 @@ nav:
     - modules/pulsar.md # Apache
     - modules/eventhubs.md # Azure
     - modules/servicebus.md # Azure
+    - modules/clickhouse.md
     - modules/db2.md
     - modules/elasticsearch.md
     - modules/mongodb.md

tests/Testcontainers.ActiveMq.Tests/ArtemisContainerTest.cs

@@ -31,7 +31,7 @@ await DisposeAsyncCore()
     }
     // # --8<-- [end:UseArtemisContainer]
 
-    // # --8<-- [start:ArtemisContainerEstablishesConnection]
+    // # --8<-- [start:EstablishConnection]
     [Fact]
     [Trait(nameof(DockerCli.DockerPlatform), nameof(DockerCli.DockerPlatform.Linux))]
     public async Task EstablishesConnection()
@@ -74,7 +74,7 @@ await producer.SendAsync(producedMessage)
 
         Assert.Equal(producedMessage.Text, receivedMessage.Body<string>());
     }
-    // # --8<-- [end:ArtemisContainerEstablishesConnection]
+    // # --8<-- [end:EstablishConnection]
 
     protected virtual ValueTask DisposeAsyncCore()
     {

tests/Testcontainers.ClickHouse.Tests/ClickHouseContainerTest.cs

@@ -1,6 +1,6 @@
 namespace Testcontainers.ClickHouse;
 
-public abstract class ClickHouseContainerTest(ClickHouseContainerTest.ClickHouseDefaultFixture fixture)
+public abstract partial class ClickHouseContainerTest(ClickHouseContainerTest.ClickHouseDefaultFixture fixture)
 {
     [Fact]
     [Trait(nameof(DockerCli.DockerPlatform), nameof(DockerCli.DockerPlatform.Linux))]

tests/Testcontainers.ClickHouse.Tests/ClickHouseContainerTest.docs.cs

@@ -0,0 +1,57 @@
+namespace Testcontainers.ClickHouse;
+
+public abstract partial class ClickHouseContainerTest
+{
+    // <!-- -8<- [start:UseClickHouseContainer] -->
+    public sealed class ClickHouseContainerExample : IAsyncLifetime
+    {
+        private readonly ClickHouseContainer _clickHouseContainer = new ClickHouseBuilder().Build();
+
+        public async ValueTask InitializeAsync()
+        {
+            await _clickHouseContainer.StartAsync(TestContext.Current.CancellationToken)
+                .ConfigureAwait(false);
+        }
+
+        public async ValueTask DisposeAsync()
+        {
+            await _clickHouseContainer.DisposeAsync()
+                .ConfigureAwait(false);
+        }
+        // <!-- -8<- [end:UseClickHouseContainer] -->
+
+        // <!-- -8<- [start:EstablishConnection] -->
+        [Fact]
+        [Trait(nameof(DockerCli.DockerPlatform), nameof(DockerCli.DockerPlatform.Linux))]
+        public void ConnectionStateReturnsOpen()
+        {
+            // Given
+            using DbConnection connection = new ClickHouseConnection(_clickHouseContainer.GetConnectionString());
+
+            // When
+            connection.Open();
+
+            // Then
+            Assert.Equal(ConnectionState.Open, connection.State);
+        }
+        // <!-- -8<- [end:EstablishConnection] -->
+
+        // <!-- -8<- [start:RunSQLScript] -->
+        [Fact]
+        [Trait(nameof(DockerCli.DockerPlatform), nameof(DockerCli.DockerPlatform.Linux))]
+        public async Task ExecScriptReturnsSuccessful()
+        {
+            // Given
+            const string scriptContent = "SELECT 1;";
+
+            // When
+            var execResult = await _clickHouseContainer.ExecScriptAsync(scriptContent, TestContext.Current.CancellationToken)
+                .ConfigureAwait(true);
+
+            // Then
+            Assert.True(0L.Equals(execResult.ExitCode), execResult.Stderr);
+            Assert.Empty(execResult.Stderr);
+        }
+        // <!-- -8<- [end:RunSQLScript] -->
+    }
+}

tests/Testcontainers.ClickHouse.Tests/Testcontainers.ClickHouse.Tests.csproj

@@ -6,11 +6,13 @@
         <OutputType>Exe</OutputType>
     </PropertyGroup>
     <ItemGroup>
+        <!-- -8<- [start:PackageReferences] -->
         <PackageReference Include="Microsoft.NET.Test.Sdk"/>
         <PackageReference Include="coverlet.collector"/>
         <PackageReference Include="xunit.runner.visualstudio"/>
         <PackageReference Include="xunit.v3"/>
         <PackageReference Include="ClickHouse.Client"/>
+        <!-- -8<- [end:PackageReferences] -->
     </ItemGroup>
     <ItemGroup>
         <ProjectReference Include="../../src/Testcontainers.ClickHouse/Testcontainers.ClickHouse.csproj"/>

tests/Testcontainers.ClickHouse.Tests/Usings.cs

@@ -1,5 +1,6 @@
 global using System.Data;
 global using System.Data.Common;
+global using System.Threading;
 global using System.Threading.Tasks;
 global using ClickHouse.Client.ADO;
 global using DotNet.Testcontainers.Builders;