feat: Add Grafana module (#1509)

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

Author: thomhurst

Testcontainers.sln

@@ -62,6 +62,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Testcontainers.Firestore",
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Testcontainers.GCloud", "src\Testcontainers.GCloud\Testcontainers.GCloud.csproj", "{D7CE8744-E58B-4277-BBB7-6840A4FF2049}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Testcontainers.Grafana", "src\Testcontainers.Grafana\Testcontainers.Grafana.csproj", "{A2E5D4B5-7F2C-4E8D-9B3A-6C2D8F9E1A3B}"
+EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Testcontainers.InfluxDb", "src\Testcontainers.InfluxDb\Testcontainers.InfluxDb.csproj", "{8F483B83-7BD4-4BD5-9F03-DFC26E1CE678}"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Testcontainers.JanusGraph", "src\Testcontainers.JanusGraph\Testcontainers.JanusGraph.csproj", "{C5AF86A8-2F11-41B6-BB01-325AD9016B94}"
@@ -180,6 +182,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Testcontainers.FirebirdSql.
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Testcontainers.Firestore.Tests", "tests\Testcontainers.Firestore.Tests\Testcontainers.Firestore.Tests.csproj", "{2F0D7CD6-7EA9-46FC-B8F2-25D55699525F}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Testcontainers.Grafana.Tests", "tests\Testcontainers.Grafana.Tests\Testcontainers.Grafana.Tests.csproj", "{C3F5E8D2-9A1B-4F7E-8D6C-5B9A2E4F7C8D}"
+EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Testcontainers.InfluxDb.Tests", "tests\Testcontainers.InfluxDb.Tests\Testcontainers.InfluxDb.Tests.csproj", "{B45B0EF2-5852-4ED3-904A-8FC62A3253D7}"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Testcontainers.JanusGraph.Tests", "tests\Testcontainers.JanusGraph.Tests\Testcontainers.JanusGraph.Tests.csproj", "{BEFC4109-4511-4FBD-AC4F-3D3B388B8CAD}"
@@ -358,6 +362,10 @@ Global
 		{D7CE8744-E58B-4277-BBB7-6840A4FF2049}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{D7CE8744-E58B-4277-BBB7-6840A4FF2049}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{D7CE8744-E58B-4277-BBB7-6840A4FF2049}.Release|Any CPU.Build.0 = Release|Any CPU
+		{A2E5D4B5-7F2C-4E8D-9B3A-6C2D8F9E1A3B}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{A2E5D4B5-7F2C-4E8D-9B3A-6C2D8F9E1A3B}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{A2E5D4B5-7F2C-4E8D-9B3A-6C2D8F9E1A3B}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{A2E5D4B5-7F2C-4E8D-9B3A-6C2D8F9E1A3B}.Release|Any CPU.Build.0 = Release|Any CPU
 		{8F483B83-7BD4-4BD5-9F03-DFC26E1CE678}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{8F483B83-7BD4-4BD5-9F03-DFC26E1CE678}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{8F483B83-7BD4-4BD5-9F03-DFC26E1CE678}.Release|Any CPU.ActiveCfg = Release|Any CPU
@@ -594,6 +602,10 @@ Global
 		{2F0D7CD6-7EA9-46FC-B8F2-25D55699525F}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{2F0D7CD6-7EA9-46FC-B8F2-25D55699525F}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{2F0D7CD6-7EA9-46FC-B8F2-25D55699525F}.Release|Any CPU.Build.0 = Release|Any CPU
+		{C3F5E8D2-9A1B-4F7E-8D6C-5B9A2E4F7C8D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{C3F5E8D2-9A1B-4F7E-8D6C-5B9A2E4F7C8D}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{C3F5E8D2-9A1B-4F7E-8D6C-5B9A2E4F7C8D}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{C3F5E8D2-9A1B-4F7E-8D6C-5B9A2E4F7C8D}.Release|Any CPU.Build.0 = Release|Any CPU
 		{B45B0EF2-5852-4ED3-904A-8FC62A3253D7}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{B45B0EF2-5852-4ED3-904A-8FC62A3253D7}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{B45B0EF2-5852-4ED3-904A-8FC62A3253D7}.Release|Any CPU.ActiveCfg = Release|Any CPU
@@ -797,6 +809,7 @@ Global
 		{31BAF2C4-0608-4C0F-845A-14FE7C0A1670} = {673F23AE-7694-4BB9-ABD4-136D6C13634E}
 		{B3CC460D-0DFD-48A8-9502-54E9828B7B05} = {673F23AE-7694-4BB9-ABD4-136D6C13634E}
 		{D7CE8744-E58B-4277-BBB7-6840A4FF2049} = {673F23AE-7694-4BB9-ABD4-136D6C13634E}
+		{A2E5D4B5-7F2C-4E8D-9B3A-6C2D8F9E1A3B} = {673F23AE-7694-4BB9-ABD4-136D6C13634E}
 		{8F483B83-7BD4-4BD5-9F03-DFC26E1CE678} = {673F23AE-7694-4BB9-ABD4-136D6C13634E}
 		{C5AF86A8-2F11-41B6-BB01-325AD9016B94} = {673F23AE-7694-4BB9-ABD4-136D6C13634E}
 		{111B840F-9DB0-4166-83E6-0580FD418F07} = {673F23AE-7694-4BB9-ABD4-136D6C13634E}
@@ -856,6 +869,7 @@ Global
 		{9F27AA1B-C25D-400C-BCB0-6B0BF1A1DCEA} = {7164F1FB-7F24-444A-ACD2-2C329C2B3CCF}
 		{E39095AC-9B34-4178-A486-04C902B6FD33} = {7164F1FB-7F24-444A-ACD2-2C329C2B3CCF}
 		{2F0D7CD6-7EA9-46FC-B8F2-25D55699525F} = {7164F1FB-7F24-444A-ACD2-2C329C2B3CCF}
+		{C3F5E8D2-9A1B-4F7E-8D6C-5B9A2E4F7C8D} = {7164F1FB-7F24-444A-ACD2-2C329C2B3CCF}
 		{B45B0EF2-5852-4ED3-904A-8FC62A3253D7} = {7164F1FB-7F24-444A-ACD2-2C329C2B3CCF}
 		{BEFC4109-4511-4FBD-AC4F-3D3B388B8CAD} = {7164F1FB-7F24-444A-ACD2-2C329C2B3CCF}
 		{F0F40AE2-70FF-4191-ADDA-26A19E0D1A0F} = {7164F1FB-7F24-444A-ACD2-2C329C2B3CCF}

docs/modules/grafana.md

@@ -0,0 +1,44 @@
+# Grafana
+
+[Grafana](https://grafana.com/) is an open-source platform for monitoring, visualization, and analytics. It allows you to query, visualize, alert on, and explore metrics, logs, and traces from various data sources through customizable dashboards.
+
+Add the following dependency to your project file:
+
+```shell title="NuGet"
+dotnet add package Testcontainers.Grafana
+```
+
+You can start a Grafana container instance from any .NET application. Here, we create different container instances and pass them to the base test class. This allows us to test different configurations.
+
+=== "Create Container Instance"
+    ```csharp
+    --8<-- "tests/Testcontainers.Grafana.Tests/GrafanaContainerTest.cs:CreateGrafanaContainer"
+    ```
+
+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.
+
+=== "Usage Example"
+    ```csharp
+    --8<-- "tests/Testcontainers.Grafana.Tests/GrafanaContainerTest.cs:UseGrafanaContainer"
+    ```
+
+The test example queries the Grafana API endpoint `GET /api/org/` to retrieve the current organization. This API endpoint requires authentication, so the HTTP client's authorization header is set with Basic authentication using the username and password configured through the Grafana builder. The default configuration uses the username `admin` and password `admin`.
+
+The test example uses the following NuGet dependencies:
+
+=== "Package References"
+    ```xml
+    --8<-- "tests/Testcontainers.Grafana.Tests/Testcontainers.Grafana.Tests.csproj:PackageReferences"
+    ```
+
+To execute the tests, use the command `dotnet test` from a terminal.
+
+--8<-- "docs/modules/_call_out_test_projects.txt"
+
+## Enable anonymous access
+
+Developers can enable anonymous access using the Grafana builder API `WithAnonymousAccessEnabled()`. This will enable anonymous access and no authentication is necessary to access Grafana:
+
+```csharp
+GrafanaContainer _grafanaContainer = new GrafanaBuilder().WithAnonymousAccessEnabled().Build();
+```

docs/modules/index.md

@@ -42,6 +42,7 @@ await moduleNameContainer.StartAsync();
 | FakeGcsServer     | `fsouza/fake-gcs-server:1.47`                                       | [NuGet](https://www.nuget.org/packages/Testcontainers.FakeGcsServer) | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.FakeGcsServer) |
 | Firebird          | `jacobalberty/firebird:v4.0`                                        | [NuGet](https://www.nuget.org/packages/Testcontainers.FirebirdSql)   | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.FirebirdSql)   |
 | Firestore         | `gcr.io/google.com/cloudsdktool/google-cloud-cli:446.0.1-emulators` | [NuGet](https://www.nuget.org/packages/Testcontainers.Firestore)     | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.Firestore)     |
+| Grafana           | `grafana/grafana:12.2`                                              | [NuGet](https://www.nuget.org/packages/Testcontainers.Grafana)       | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.Grafana)       |
 | InfluxDB          | `influxdb:2.7`                                                      | [NuGet](https://www.nuget.org/packages/Testcontainers.InfluxDb)      | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.InfluxDb)      |
 | JanusGraph        | `janusgraph/janusgraph:1.0.0`                                       | [NuGet](https://www.nuget.org/packages/Testcontainers.JanusGraph)    | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.JanusGraph)    |
 | K3s               | `rancher/k3s:v1.26.2-k3s1`                                          | [NuGet](https://www.nuget.org/packages/Testcontainers.K3s)           | [Source](https://github.com/testcontainers/testcontainers-dotnet/tree/develop/src/Testcontainers.K3s)           |

docs/modules/pulsar.md

@@ -48,7 +48,7 @@ string pulsarServiceUrl = _pulsarContainer.GetHttpServiceUrl();
 If you need to use token authentication, use the following builder configuration to enable authentication:
 
 ```csharp
-PulsarContainer _pulsarContainer = PulsarBuilder().WithTokenAuthentication().Build();
+PulsarContainer _pulsarContainer = new PulsarBuilder().WithTokenAuthentication().Build();
 ```
 
 Start the container and obtain an authentication token with a specified expiration time
@@ -70,5 +70,5 @@ var authToken = await container.CreateAuthenticationTokenAsync(Timeout.InfiniteT
 If you need to use Pulsar Functions, use the following builder configuration to enable it:
 
 ```csharp
-PulsarContainer _pulsarContainer = PulsarBuilder().WithFunctions().Build();
+PulsarContainer _pulsarContainer = new PulsarBuilder().WithFunctions().Build();
 ```

mkdocs.yml

@@ -56,6 +56,7 @@ nav:
     - modules/clickhouse.md
     - modules/db2.md
     - modules/elasticsearch.md
+    - modules/grafana.md
     - modules/mongodb.md
     - modules/mssql.md
     - modules/neo4j.md

src/Testcontainers.Grafana/.editorconfig

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

src/Testcontainers.Grafana/GrafanaBuilder.cs

@@ -0,0 +1,105 @@
+namespace Testcontainers.Grafana;
+
+/// <inheritdoc cref="ContainerBuilder{TBuilderEntity, TContainerEntity, TConfigurationEntity}" />
+[PublicAPI]
+public sealed class GrafanaBuilder : ContainerBuilder<GrafanaBuilder, GrafanaContainer, GrafanaConfiguration>
+{
+    public const string GrafanaImage = "grafana/grafana:12.2";
+
+    public const ushort GrafanaPort = 3000;
+
+    public const string DefaultUsername = "admin";
+
+    public const string DefaultPassword = "admin";
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="GrafanaBuilder" /> class.
+    /// </summary>
+    public GrafanaBuilder()
+        : this(new GrafanaConfiguration())
+    {
+        DockerResourceConfiguration = Init().DockerResourceConfiguration;
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="GrafanaBuilder" /> class.
+    /// </summary>
+    /// <param name="resourceConfiguration">The Docker resource configuration.</param>
+    private GrafanaBuilder(GrafanaConfiguration resourceConfiguration)
+        : base(resourceConfiguration)
+    {
+        DockerResourceConfiguration = resourceConfiguration;
+    }
+
+    /// <inheritdoc />
+    protected override GrafanaConfiguration DockerResourceConfiguration { get; }
+
+    /// <summary>
+    /// Sets the Grafana username.
+    /// </summary>
+    /// <param name="username">The Grafana username.</param>
+    /// <returns>A configured instance of <see cref="GrafanaBuilder" />.</returns>
+    public GrafanaBuilder WithUsername(string username)
+    {
+        return Merge(DockerResourceConfiguration, new GrafanaConfiguration(username: username))
+            .WithEnvironment("GF_SECURITY_ADMIN_USER", username);
+    }
+
+    /// <summary>
+    /// Sets the Grafana password.
+    /// </summary>
+    /// <param name="password">The Grafana password.</param>
+    /// <returns>A configured instance of <see cref="GrafanaBuilder" />.</returns>
+    public GrafanaBuilder WithPassword(string password)
+    {
+        return Merge(DockerResourceConfiguration, new GrafanaConfiguration(password: password))
+            .WithEnvironment("GF_SECURITY_ADMIN_PASSWORD", password);
+    }
+
+    /// <summary>
+    /// Enables the anonymous access.
+    /// </summary>
+    /// <returns>A configured instance of <see cref="GrafanaBuilder" />.</returns>
+    public GrafanaBuilder WithAnonymousAccessEnabled()
+    {
+        return WithEnvironment("GF_AUTH_ANONYMOUS_ENABLED", "true")
+            .WithEnvironment("GF_AUTH_ANONYMOUS_ORG_ROLE", "Admin");
+    }
+
+    /// <inheritdoc />
+    public override GrafanaContainer Build()
+    {
+        Validate();
+        return new GrafanaContainer(DockerResourceConfiguration);
+    }
+
+    /// <inheritdoc />
+    protected override GrafanaBuilder Init()
+    {
+        return base.Init()
+            .WithImage(GrafanaImage)
+            .WithPortBinding(GrafanaPort, true)
+            .WithUsername(DefaultUsername)
+            .WithPassword(DefaultPassword)
+            .WithWaitStrategy(Wait.ForUnixContainer().UntilHttpRequestIsSucceeded(request =>
+                request.ForPath("/api/health").ForPort(GrafanaPort)));
+    }
+
+    /// <inheritdoc />
+    protected override GrafanaBuilder Clone(IResourceConfiguration<CreateContainerParameters> resourceConfiguration)
+    {
+        return Merge(DockerResourceConfiguration, new GrafanaConfiguration(resourceConfiguration));
+    }
+
+    /// <inheritdoc />
+    protected override GrafanaBuilder Clone(IContainerConfiguration resourceConfiguration)
+    {
+        return Merge(DockerResourceConfiguration, new GrafanaConfiguration(resourceConfiguration));
+    }
+
+    /// <inheritdoc />
+    protected override GrafanaBuilder Merge(GrafanaConfiguration oldValue, GrafanaConfiguration newValue)
+    {
+        return new GrafanaBuilder(new GrafanaConfiguration(oldValue, newValue));
+    }
+}

src/Testcontainers.Grafana/GrafanaConfiguration.cs

@@ -0,0 +1,71 @@
+namespace Testcontainers.Grafana;
+
+/// <inheritdoc cref="ContainerConfiguration" />
+[PublicAPI]
+public sealed class GrafanaConfiguration : ContainerConfiguration
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="GrafanaConfiguration" /> class.
+    /// </summary>
+    /// <param name="username">The Grafana username.</param>
+    /// <param name="password">The Grafana password.</param>
+    public GrafanaConfiguration(
+        string username = null,
+        string password = null)
+    {
+        Username = username;
+        Password = password;
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="GrafanaConfiguration" /> class.
+    /// </summary>
+    /// <param name="resourceConfiguration">The Docker resource configuration.</param>
+    public GrafanaConfiguration(IResourceConfiguration<CreateContainerParameters> resourceConfiguration)
+        : base(resourceConfiguration)
+    {
+        // Passes the configuration upwards to the base implementations to create an updated immutable copy.
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="GrafanaConfiguration" /> class.
+    /// </summary>
+    /// <param name="resourceConfiguration">The Docker resource configuration.</param>
+    public GrafanaConfiguration(IContainerConfiguration resourceConfiguration)
+        : base(resourceConfiguration)
+    {
+        // Passes the configuration upwards to the base implementations to create an updated immutable copy.
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="GrafanaConfiguration" /> class.
+    /// </summary>
+    /// <param name="resourceConfiguration">The Docker resource configuration.</param>
+    public GrafanaConfiguration(GrafanaConfiguration resourceConfiguration)
+        : this(new GrafanaConfiguration(), resourceConfiguration)
+    {
+        // Passes the configuration upwards to the base implementations to create an updated immutable copy.
+    }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="GrafanaConfiguration" /> class.
+    /// </summary>
+    /// <param name="oldValue">The old Docker resource configuration.</param>
+    /// <param name="newValue">The new Docker resource configuration.</param>
+    public GrafanaConfiguration(GrafanaConfiguration oldValue, GrafanaConfiguration newValue)
+        : base(oldValue, newValue)
+    {
+        Username = BuildConfiguration.Combine(oldValue.Username, newValue.Username);
+        Password = BuildConfiguration.Combine(oldValue.Password, newValue.Password);
+    }
+
+    /// <summary>
+    /// Gets the Grafana username.
+    /// </summary>
+    public string Username { get; }
+
+    /// <summary>
+    /// Gets the Grafana password.
+    /// </summary>
+    public string Password { get; }
+}

src/Testcontainers.Grafana/GrafanaContainer.cs

@@ -0,0 +1,27 @@
+namespace Testcontainers.Grafana;
+
+/// <inheritdoc cref="DockerContainer" />
+[PublicAPI]
+public sealed class GrafanaContainer : DockerContainer
+{
+    private readonly GrafanaConfiguration _configuration;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="GrafanaContainer" /> class.
+    /// </summary>
+    /// <param name="configuration">The container configuration.</param>
+    public GrafanaContainer(GrafanaConfiguration configuration)
+        : base(configuration)
+    {
+        _configuration = configuration;
+    }
+
+    /// <summary>
+    /// Gets the Grafana base address.
+    /// </summary>
+    /// <returns>The Grafana base address.</returns>
+    public string GetBaseAddress()
+    {
+        return new UriBuilder(Uri.UriSchemeHttp, Hostname, GetMappedPublicPort(GrafanaBuilder.GrafanaPort)).ToString();
+    }
+}

src/Testcontainers.Grafana/Testcontainers.Grafana.csproj

@@ -0,0 +1,12 @@
+<Project Sdk="Microsoft.NET.Sdk">
+    <PropertyGroup>
+        <TargetFrameworks>net8.0;net9.0;netstandard2.0;netstandard2.1</TargetFrameworks>
+        <LangVersion>latest</LangVersion>
+    </PropertyGroup>
+    <ItemGroup>
+        <PackageReference Include="JetBrains.Annotations" VersionOverride="2023.3.0" PrivateAssets="All"/>
+    </ItemGroup>
+    <ItemGroup>
+        <ProjectReference Include="../Testcontainers/Testcontainers.csproj"/>
+    </ItemGroup>
+</Project>