feat: Add Flyway example (#1002)

.config/dotnet-tools.json

@@ -3,7 +3,7 @@
  "isRoot": true,
  "tools": {
  "cake.tool": {
- "version": "3.0.0",
+ "version": "3.1.0",
  "commands": [
  "dotnet-cake"
  ]

.github/workflows/cicd.yml

@@ -131,7 +131,7 @@ jobs:
  uses: actions/setup-java@v3
  with:
  distribution: temurin
- java-version: 11
+ java-version: 17
 
  - name: Setup .NET
  uses: actions/setup-dotnet@v3

build.cake

@@ -1,6 +1,6 @@
-#tool nuget:?package=dotnet-sonarscanner&version=5.13.0
+#tool nuget:?package=dotnet-sonarscanner&version=5.13.1
 
-#addin nuget:?package=Cake.Sonar&version=1.1.31
+#addin nuget:?package=Cake.Sonar&version=1.1.32
 
 #addin nuget:?package=Cake.Git&version=3.0.0
 

examples/Flyway/.editorconfig

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

examples/Flyway/.gitattributes

@@ -0,0 +1 @@
+* text=auto

examples/Flyway/Directory.Build.props

@@ -0,0 +1,28 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project>
+ <PropertyGroup>
+ <SolutionDir Condition=" '$(SolutionDir)' == '' ">$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildProjectDirectory), Flyway.sln))/</SolutionDir>
+ </PropertyGroup>
+ <PropertyGroup>
+ <Version>0.1.0</Version>
+ <PackageId>$(AssemblyName)</PackageId>
+ <AssemblyVersion>$(Version)</AssemblyVersion>
+ <FileVersion>$(Version)</FileVersion>
+ <InformationalVersion>$(Version)</InformationalVersion>
+ <NeutralLanguage>en-US</NeutralLanguage>
+ <Authors>Andre Hofmeister</Authors>
+ <Company></Company>
+ <Description></Description>
+ <Summary></Summary>
+ <PackageIconUrl></PackageIconUrl>
+ <PackageLicenseExpression></PackageLicenseExpression>
+ <PackageProjectUrl></PackageProjectUrl>
+ <PackageTags></PackageTags>
+ <RepositoryType>git</RepositoryType>
+ <RepositoryUrl>https://github.com/testcontainers/testcontainers-dotnet-sample</RepositoryUrl>
+ </PropertyGroup>
+ <PropertyGroup>
+ <LangVersion>10.0</LangVersion>
+ <Nullable>enable</Nullable>
+ </PropertyGroup>
+</Project>

examples/Flyway/Flyway.sln

@@ -0,0 +1,26 @@
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio Version 17
+VisualStudioVersion = 17.0.31903.59
+MinimumVisualStudioVersion = 10.0.40219.1
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tests", "tests", "{424CFC36-D6F7-4DBB-BD1C-0C84FE30E665}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Flyway.Tests", "tests\Flyway.Tests\Flyway.Tests.csproj", "{1E882BFE-4A5E-4E58-A533-81E1BE9E9BFD}"
+EndProject
+Global
+ GlobalSection(SolutionConfigurationPlatforms) = preSolution
+ Debug|Any CPU = Debug|Any CPU
+ Release|Any CPU = Release|Any CPU
+ EndGlobalSection
+ GlobalSection(SolutionProperties) = preSolution
+ HideSolutionNode = FALSE
+ EndGlobalSection
+ GlobalSection(ProjectConfigurationPlatforms) = postSolution
+ {1E882BFE-4A5E-4E58-A533-81E1BE9E9BFD}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+ {1E882BFE-4A5E-4E58-A533-81E1BE9E9BFD}.Debug|Any CPU.Build.0 = Debug|Any CPU
+ {1E882BFE-4A5E-4E58-A533-81E1BE9E9BFD}.Release|Any CPU.ActiveCfg = Release|Any CPU
+ {1E882BFE-4A5E-4E58-A533-81E1BE9E9BFD}.Release|Any CPU.Build.0 = Release|Any CPU
+ EndGlobalSection
+ GlobalSection(NestedProjects) = preSolution
+ {1E882BFE-4A5E-4E58-A533-81E1BE9E9BFD} = {424CFC36-D6F7-4DBB-BD1C-0C84FE30E665}
+ EndGlobalSection
+EndGlobal

examples/Flyway/Packages.props

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project>
+ <ItemGroup>
+ <PackageReference Update="JetBrains.Annotations" Version="2023.2.0" PrivateAssets="all"/>
+ <PackageReference Update="Testcontainers.PostgreSql" Version="3.5.0"/>
+ <PackageReference Update="Microsoft.NET.Test.Sdk" Version="17.7.2"/>
+ <PackageReference Update="xunit.runner.visualstudio" Version="2.5.0"/>
+ <PackageReference Update="xunit" Version="2.5.0"/>
+ <PackageReference Update="Npgsql" Version="6.0.10"/>
+ </ItemGroup>
+</Project>

examples/Flyway/README.md

@@ -0,0 +1,9 @@
+# Testcontainers for .NET Flyway example
+
+This example demonstrates how to use Testcontainers in conjunction with Flyway to execute database migrations and prepare a dependent database before running tests. The `FlywayTest` test class executes its tests against the pre-configured PostgreSQL database, interacting with the table that is created, altered, and seeded beforehand. This test class receives a class fixture, which provides access to the prepared database through the `DbConnection` property. The database is started, created, and seeded once and is shared across the tests within the `FlywayTest` test collection. Checkout and run the tests on your machine:
+
+```console
+git clone --branch develop [email protected]:testcontainers/testcontainers-dotnet.git
+cd ./testcontainers-dotnet/examples/Flyway/
+dotnet test Flyway.sln --configuration=Release
+```

examples/Flyway/tests/Flyway.Tests/DbFixture.cs

@@ -0,0 +1,74 @@
+namespace Flyway.Tests;
+
+[UsedImplicitly]
+public sealed class DbFixture : IAsyncLifetime
+{
+ private readonly INetwork _network = new NetworkBuilder().Build();
+
+ private readonly IContainer _postgreSqlContainer;
+
+ private readonly IContainer _flywayContainer;
+
+ public DbFixture()
+ {
+ // Testcontainers starts the dependent database (PostgreSQL) and the database
+ // migration tool Flyway. It establishes a network connection between these two
+ // containers. Before starting the Flyway container, Testcontainers copies the SQL
+ // migration files into it. When the Flyway container starts, it initiates the
+ // dependent database container, connects to it, and begins the database migration
+ // as soon as the database is ready. Once the migration is finished, the Flyway
+ // container exits, and the database container becomes available for tests.
+
+ _postgreSqlContainer = new PostgreSqlBuilder()
+ .WithImage("postgres:15-alpine")
+ .WithNetwork(_network)
+ .WithNetworkAliases(nameof(_postgreSqlContainer))
+ .Build();
+
+ // The member `WithResourceMapping(string, string)` copies the SQL migration files
+ // from the test host into the Flyway container before it starts. This ensures that
+ // the files are available as soon as the container starts. Flyway will
+ // automatically pick them up and start the database migration process.
+
+ _flywayContainer = new ContainerBuilder()
+ .WithImage("flyway/flyway:9-alpine")
+ .WithResourceMapping("migrate/", "/flyway/sql/")
+ .WithCommand("-url=jdbc:postgresql://" + nameof(_postgreSqlContainer) + "/")
+ .WithCommand("-user=" + PostgreSqlBuilder.DefaultUsername)
+ .WithCommand("-password=" + PostgreSqlBuilder.DefaultPassword)
+ .WithCommand("-connectRetries=3")
+ .WithCommand("migrate")
+ .WithNetwork(_network)
+ .DependsOn(_postgreSqlContainer)
+ .WithWaitStrategy(Wait.ForUnixContainer().AddCustomWaitStrategy(new MigrationCompleted()))
+ .Build();
+ }
+
+ public DbConnection DbConnection => new NpgsqlConnection(((PostgreSqlContainer)_postgreSqlContainer).GetConnectionString());
+
+ public Task InitializeAsync()
+ {
+ return _flywayContainer.StartAsync();
+ }
+
+ public Task DisposeAsync()
+ {
+ // We do not need to manually dispose Docker resources. If resources depend on each
+ // other, it is necessary to dispose them in the correct order. Testcontainers'
+ // Resource Reaper (Ryuk) will reliably take care of these resources and dispose
+ // them after the test automatically.
+ return Task.CompletedTask;
+ }
+
+ private sealed class MigrationCompleted : IWaitUntil
+ {
+ // The Flyway container will exit after executing the database migration. We do not
+ // check if the migration was successful. To verify its success, we can either
+ // check the exit code of the container or the console output, respectively the
+ // standard output (stdout) or error output (stderr).
+ public Task<bool> UntilAsync(IContainer container)
+ {
+ return Task.FromResult(TestcontainersStates.Exited.Equals(container.State));
+ }
+ }
+}

examples/Flyway/tests/Flyway.Tests/Flyway.Tests.csproj

@@ -0,0 +1,17 @@
+<Project Sdk="Microsoft.NET.Sdk">
+ <Sdk Name="Microsoft.Build.CentralPackageVersions" Version="2.1.3"/>
+ <PropertyGroup>
+ <TargetFrameworks>net6.0</TargetFrameworks>
+ </PropertyGroup>
+ <ItemGroup>
+ <PackageReference Include="JetBrains.Annotations"/>
+ <PackageReference Include="Testcontainers.PostgreSql"/>
+ <PackageReference Include="Microsoft.NET.Test.Sdk"/>
+ <PackageReference Include="xunit.runner.visualstudio"/>
+ <PackageReference Include="xunit"/>
+ <PackageReference Include="Npgsql"/>
+ </ItemGroup>
+ <ItemGroup>
+ <None Include="migrate/*.sql" CopyToOutputDirectory="PreserveNewest"/>
+ </ItemGroup>
+</Project>

examples/Flyway/tests/Flyway.Tests/FlywayTest.cs

@@ -0,0 +1,34 @@
+namespace Flyway.Tests;
+
+public sealed class FlywayTest : IClassFixture<DbFixture>, IDisposable
+{
+ private readonly DbConnection _dbConnection;
+
+ public FlywayTest(DbFixture db)
+ {
+ _dbConnection = db.DbConnection;
+ _dbConnection.Open();
+ }
+
+ public void Dispose()
+ {
+ _dbConnection.Dispose();
+ }
+
+ [Fact]
+ public void UsersTableContainsJohnDoe()
+ {
+ // Given
+ using var command = _dbConnection.CreateCommand();
+ command.CommandText = "SELECT username, email, age FROM users;";
+
+ // When
+ using var dataReader = command.ExecuteReader();
+
+ // Then
+ Assert.True(dataReader.Read());
+ Assert.Equal("john_doe", dataReader.GetString(0));
+ Assert.Equal("[email protected]", dataReader.GetString(1));
+ Assert.Equal(30, dataReader.GetInt32(2));
+ }
+}

examples/Flyway/tests/Flyway.Tests/Usings.cs

@@ -0,0 +1,11 @@
+global using System;
+global using System.Data.Common;
+global using System.Threading.Tasks;
+global using DotNet.Testcontainers.Builders;
+global using DotNet.Testcontainers.Configurations;
+global using DotNet.Testcontainers.Containers;
+global using DotNet.Testcontainers.Networks;
+global using JetBrains.Annotations;
+global using Npgsql;
+global using Testcontainers.PostgreSql;
+global using Xunit;

examples/Flyway/tests/Flyway.Tests/migrate/V1.0__create_users_table.sql

@@ -0,0 +1,7 @@
+CREATE TABLE users
+(
+ id SERIAL PRIMARY KEY,
+ username VARCHAR(50) NOT NULL,
+ email VARCHAR(100) NOT NULL,
+ created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);

examples/Flyway/tests/Flyway.Tests/migrate/V1.1__alter_users_table.sql

@@ -0,0 +1 @@
+ALTER TABLE users ADD COLUMN age INT;

examples/Flyway/tests/Flyway.Tests/migrate/V2.0__seed_example_users.sql

@@ -0,0 +1 @@
+INSERT INTO users (username, email, age) VALUES ('john_doe', '[email protected]', 30);

tests/Testcontainers.PostgreSql.Tests/Testcontainers.PostgreSql.Tests.csproj

@@ -9,7 +9,7 @@
  <PackageReference Include="coverlet.collector" Version="6.0.0"/>
  <PackageReference Include="xunit.runner.visualstudio" Version="2.5.0"/>
  <PackageReference Include="xunit" Version="2.5.0"/>
- <PackageReference Include="Npgsql" Version="6.0.9"/>
+ <PackageReference Include="Npgsql" Version="6.0.10"/>
  </ItemGroup>
  <ItemGroup>
  <ProjectReference Include="$(SolutionDir)src/Testcontainers.PostgreSql/Testcontainers.PostgreSql.csproj"/>