What configuration precedence rules apply when overriding connection strings in ASP.NET Core integration tests using WebApplicationFactory?

Direct Answers

Which source wins when both an environment variable and a user secret are defined for the same key? The user secret wins. In the default configuration builder order, user secrets are added after environment variables, so they override environment-variable values for the same key.

Does setting a connection string through an environment variable guarantee that any user-secret value for that key is ignored? No. Because user secrets load later in the default pipeline, a user secret with the same key will take precedence over the environment variable.

Can testcontainers be combined with environment-variable overrides without risking that the container's internal configuration overrides the test host's settings? Yes, but only if you inject the testcontainer connection string via ConfigureAppConfiguration (e.g., AddInMemoryCollection) after the default sources. Adding it as an environment variable alone is not sufficient because a user secret would still win.

Why This Happens: Default Configuration Order

ASP.NET Core builds configuration in this sequence (later sources override earlier ones):

1. appsettings.json
2. appsettings.{Environment}.json
3. Environment variables
4. User secrets (only when Environment.IsDevelopment())

WebApplicationFactory preserves this order. When you call builder.ConfigureAppConfiguration in a test, your custom source is appended after all the defaults, giving it the highest precedence for that test host.

Guaranteeing the Test Connection String Wins

To ensure a testcontainer or any test-specific connection string dominates user secrets and environment variables, add it through ConfigureAppConfiguration:

var factory = new WebApplicationFactory<Program>()
    .WithWebHostBuilder(builder =>
    {
        builder.ConfigureAppConfiguration((context, config) =
        {
            config.AddInMemoryCollection(new Dictionary<string, string>
            {
                ["ConnectionStrings:MyDb"] = testContainerConnectionString
            });
        });
    });

This in-memory collection is added last, so it overrides any user secret or environment variable with the same key.

Verification Steps

1. Create a test project with WebApplicationFactory<Program>.
2. Add a user secret ConnectionStrings:MyDb=UserSecretValue in Development.
3. Set an environment variable ConnectionStrings:MyDb=EnvVarValue before building the factory.
4. Run a test without the in-memory override; IConfiguration["ConnectionStrings:MyDb"] should return UserSecretValue.
5. Run the same test with the AddInMemoryCollection override shown above; the value should be testContainerConnectionString.

Diagnostic Detail Needed

Are your integration tests running with ASPNETCORE_ENVIRONMENT=Development (the default for WebApplicationFactory)? If they run under a different environment name, user secrets are not loaded at all, and the environment variable would win by default.