How to run tests with TestContainers in WSL2 without Docker Desktop

docker_wsl2.md

Install docker

in case you haven't docker installed, please follow this instruction https://docs.docker.com/engine/install/ubuntu/

Expose docker port

First way

Create daemon.json file in /etc/docker, with content:

{"hosts": ["tcp://0.0.0.0:2375", "unix:///var/run/docker.sock"]}

Second way suggested by @maireadmccabe-fire

sudo mkdir -p /etc/systemd/system/docker.service.d
sudo vim /etc/systemd/system/docker.service.d/override.conf

# add the below to the override.conf file
[Service]
ExecStart=
ExecStart=/usr/bin/dockerd --host=tcp://0.0.0.0:2375 --host=unix:///var/run/docker.sock

Restart docker daemon

sudo systemctl daemon-reload and then sudo systemctl restart docker or sudo service docker restart

or just restart WSL2 by calling wsl --shutdown  in windows CMD/PowerShell and just open linux terminal once again

if you have run docker as sudo dockerd - stop it, and run sudo dockerd once again.

Check that port are exposed

after restart docker daemon or restart wsl, run in linux terminal netstat -nl | grep 2375 (install net-tools if you haven't it). You should see that port are open.

Add environment variables

add the following properties in Windows Env Variables:

Name	Value
DOCKER_HOST	tcp://localhost:2375
DOCKER_TLS_VERIFY	0
DOCKER_CERT_PATH	\\wsl$\home\$USER_NAME\.docker

⚠️ seems like there is kind of an issue in WSL, sometimes tcp://localhost:2375 should be replaced with tcp://$wsl_ip:2375, where $wsl_ip is IP of ifconfig eth0 ⚠️

✔️ There is a workaround suggest by @tacascer

@echo off
set port=:2375
set
(for /f "tokens=2" %%f in ('wsl ifconfig eth0 ^| findstr /c:"inet "') do (
    set dockerhost=tcp://%%f%port%
))
@REM echo %dockerhost%
setx DOCKER_HOST %dockerhost%

⚠️ port in DOCKER_HOST variable must be same as exposed above

⚠️ $USER_NAME -replace this placeholder with your linux user

⚠️ .testcontainers.properties - were empty

Restart IDE

To apply environment variables you need restart IDE (in my case is Intellij Idea) OR just specify in Run/Debug Configuration these env variables directly.

Protect the Docker daemon socket

If you are looking for secure access to docker follow the guide suggested by @gim-

A complete, clean workflow for running .NET Testcontainers tests with MsSql using Docker on WSL (without Docker Desktop) and without relying on wrappers (docker.cmd) or environment-variable configurations. This setup has been validated and is the recommended approach.

# Step 1 — Install prerequisites inside WSL

1. Open your WSL terminal (Ubuntu).
2. Install .NET SDK (.NET 8):

wget https://dot.net/v1/dotnet-install.sh -O dotnet-install.sh
chmod +x dotnet-install.sh
./dotnet-install.sh --channel 8.0
export PATH=$PATH:$HOME/.dotnet

3. Install Docker engine in WSL:

sudo apt update
sudo apt install docker.io -y
sudo service docker start

4. Test Docker:

docker version
docker ps

• You should see the Docker client and server versions.
• Ensure no errors.

# Step 2 — Create .testcontainers.properties

1. Go to your WSL home directory:

cd ~

2. Create .testcontainers.properties:

nano .testcontainers.properties

3. Paste the following:

testcontainers.docker.client.transport=cli
testcontainers.docker.client.executable=docker
testcontainers.log.level=debug

4. Save and exit (Ctrl+O, Enter, Ctrl+X).
5. Verify:

cat ~/.testcontainers.properties

# Step 3 — Structure your .NET solution

MySQLApp/
├─ MySQLApp/ # Main project
│ └─ Program.cs
└─ MySQLApp.Tests/ # Test project
└─ SQLServerContainerTests.cs

• Test project references your main project (MySQLApp.csproj).

---

# Step 4 — Create a sample .NET app
Below is a minimal, working example of an xUnit test project that uses .NET Testcontainers to spin up a Microsoft SQL Server container and run a simple database test.
using System;
using Microsoft.Data.SqlClient;
using System.Threading.Tasks;
using Testcontainers.MsSql;
using Xunit;

public class SQLServerContainerTests : IAsyncLifetime
{
private readonly MsSqlContainer _sqlContainer;
private string _connectionString = default!;

public SQLServerContainerTests()
{
    _sqlContainer = new MsSqlBuilder()
    .WithImage("mcr.microsoft.com/mssql/server:2022-latest")
    .WithPassword("YourStongPassword")
    .WithPortBinding(14333, 1433) // exposes container SQL port → host
    .Build();
}

public async Task InitializeAsync()
{
    await _sqlContainer.StartAsync();

    _connectionString =
    "Server=localhost,14333;User Id=sa;Password=YourStongPassword;TrustServerCertificate=True";

    using var connection = new SqlConnection(_connectionString);
    await connection.OpenAsync();     
}

public async Task DisposeAsync()
{
    await _sqlContainer.DisposeAsync();
}

[Fact]
public async Task CanConnectToSqlServerTestcontainer()
{
    using var connection = new SqlConnection(_connectionString);
    await connection.OpenAsync();
    Assert.Equal(System.Data.ConnectionState.Open, connection.State);
}

}
# Step 5 — Run your tests from WSL

cd /mnt/c/dev/MySQLApp/MySQLApp.Tests
dotnet test

Expected:

• Testcontainers connects to WSL Docker (unix:///var/run/docker.sock).
• MsSql container starts, readiness checks pass.
• Connection string and debug logs appear in console.
• Container stops automatically after the test.