A WebApplicationFactory suite for an ASP.NET Core 10 API passes on developers' machines but fails in CI with a missing connection string. How do the factory's environment defaults explain it?
answer
- the environment nobody set
- user secrets load only in Development
- UseEnvironment inside ConfigureWebHost
- UseSetting travels as command-line args
- ConfigureAppConfiguration lands only at Build()
basics
~10 sThe factory runs the app in Development, so WebApplication.CreateBuilder loads each developer's user secrets, which CI lacks. Pin the environment with UseEnvironment and supply test settings explicitly through UseSetting or ConfigureAppConfiguration.
solid answer
~40 sUnless told otherwise, `WebApplicationFactory<Program>` sets the environment to `Development`. In that environment `WebApplication.CreateBuilder` adds `appsettings.Development.json` and the user-secrets store for the app's `UserSecretsId`, turns on `ValidateScopes` and `ValidateOnBuild`, and adds the developer exception page. On a developer's machine the connection string comes from `secrets.json`; the CI agent has no such file, so the same tests fail. The fix is to make the test host self-sufficient: call `builder.UseEnvironment("Testing")` (or another explicit name) in `ConfigureWebHost`, and provide every required value from the test. `UseSetting(key, value)` writes host configuration that the factory passes to `Program.cs` as command-line arguments, so it is visible even to code that reads `builder.Configuration` before `Build()`. `ConfigureAppConfiguration` sources arrive only when the host is built, too late for such reads.
code
csharp · 15 linesusing Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc.Testing;
public sealed class JobBoardApiFactory : WebApplicationFactory<Program>
{
public string JobsConnectionString { get; set; } = "";
protected override void ConfigureWebHost(IWebHostBuilder builder)
{
builder.UseEnvironment("Testing");
// Host setting: reaches Program.cs as an argument, visible before Build()
builder.UseSetting("ConnectionStrings:Jobs", JobsConnectionString);
}
}go deeper
Recall that the factory's default environment is Development and that UseEnvironment in ConfigureWebHost changes it.
List what Development turns on in WebApplication.CreateBuilder and explain the difference between UseSetting and ConfigureAppConfiguration timing.
Diagnose machine-dependent test results from user secrets and Development-only files, and make the factory supply every value so CI and laptops boot the same app.
Set a suite-wide rule for which environment integration tests run in and how test configuration is sourced, so environment drift never decides whether a build is green.
## What the factory chooses for you When `WebApplicationFactory<Program>` prepares the host it sets two host settings before `Program.cs` runs: the **application name** (the app's assembly name) and the **environment, `Development`**. The factory hands host settings to the entry point as **command-line arguments**, and `WebApplication.CreateBuilder(args)` adds the command line after the `ASPNETCORE_` and `DOTNET_` environment variables. So setting `ASPNETCORE_ENVIRONMENT` on a CI agent does not change the factory's choice; only the test's own `UseEnvironment` does. ## What Development switches on `WebApplication.CreateBuilder` treats Development specially: | Behaviour | In Development | Consequence in tests | |---|---|---| | `appsettings.Development.json` | loaded | values meant for local runs leak into tests | | user secrets | loaded when the app assembly has a `UserSecretsId` | each developer's machine supplies values CI never has | | `ValidateScopes`, `ValidateOnBuild` | `true` | captive dependencies fail at startup in tests but not in production | | developer exception page | added automatically | unhandled exceptions render the developer page, not your production error body | | `IsDevelopment()` branches in `Program.cs` | taken | e.g. `MapOpenApi()` or a relaxed CORS policy is active in tests but not in production | The CI failure in the question is row two: the connection string lives in a developer's `secrets.json`, the build agent has none, and the app starts without it. ## Fixing it 1. **Pin the environment.** In the factory's `ConfigureWebHost`, call `builder.UseEnvironment("Testing")`. A custom name keeps Development-only code paths off and lets the app load an `appsettings.Testing.json` if you want one. Use `Production` when the test should see exactly the production branches. 2. **Supply settings from the test.** Do not rely on any machine-level source: provide the connection string (often from a container the test started) and every other required value in the factory. 3. **Fail fast.** Validate required options at startup so a missing value fails loudly in every environment rather than surfacing as a later null. ## Two ways to inject values, and when each is visible The factory delivers host settings differently from app configuration: - **`UseSetting(key, value)`** (and `UseEnvironment`, which is a `UseSetting` for the `environment` key) writes host configuration. The factory turns host configuration into **command-line arguments** for the entry point, so `WebApplication.CreateBuilder(args)` sees them immediately. Code in `Program.cs` that reads `builder.Configuration["ConnectionStrings:Jobs"]` before `Build()` gets the test value. This requires `Program.cs` to pass `args` to `CreateBuilder`, as the templates do. - **`ConfigureAppConfiguration(...)`** adds a configuration source, such as an in-memory collection, that the factory applies when the app calls `builder.Build()`. Services that read `IConfiguration` or options later see it, but code that read configuration **before** `Build()` already used the old value. | Mechanism | Visible before `Build()` in Program.cs | Typical use | |---|---|---| | `UseEnvironment(name)` | yes | choose the environment | | `UseSetting(key, value)` | yes | a connection string read during registration | | `ConfigureAppConfiguration` | no | options bound lazily by services | | `ConfigureTestServices` with `Configure<TOptions>` | n/a | override an options object directly | ## A checklist for a CI-proof factory - The environment is named explicitly in `ConfigureWebHost`, never inherited. - Every connection string and secret the app requires is set by the factory, typically from a container or fake the test controls. - No test depends on `appsettings.Development.json` or user secrets existing. - Options the app needs are validated at startup, so a missing value fails with a clear message. - At least one test boots the app in the environment production uses, so production-only branches are exercised somewhere. ## Interview-grade diagnosis - A test passing locally and failing in CI with a missing value points first at user secrets or `appsettings.Development.json`, both loaded only because the factory chose Development. - A test that sets a value through `ConfigureAppConfiguration` yet sees the old one points at a read before `Build()`; move the value to `UseSetting` or move the read into a service. - A test that throws at startup about a scoped service resolved from a singleton is Development's scope validation doing its job; fix the lifetime rather than switching environments to hide it. - An error-response test whose body is HTML or a stack trace is reading the developer exception page; run that test in a non-Development environment so the production exception handling applies.
- Program.cs reads builder.Configuration["Features:Alerts"] before Build(). A test adds it with ConfigureAppConfiguration and nothing changes. Why?The factory applies `ConfigureAppConfiguration` sources when the app calls `builder.Build()`, after that line already ran. Use `builder.UseSetting("Features:Alerts", "true")`, which the factory passes as a command-line argument to `CreateBuilder(args)`, or move the read into a service resolved later.
- Switching the factory to Production makes a startup error about a scoped service disappear. Why is that not a fix?Outside Development the container skips `ValidateScopes` and `ValidateOnBuild`, so a captive scoped dependency no longer throws at build. The bug still exists; it now shows up as state shared across requests. Fix the lifetime instead.
- WebApplicationFactory runs the app as Production unless the test changes it.
- Setting ASPNETCORE_ENVIRONMENT on the CI agent changes the factory's environment.
- ConfigureAppConfiguration values are visible to Program.cs code before Build().
- User secrets are loaded in every environment, so CI behaves like a laptop.
- Switching tests away from Development is how you fix a scope-validation failure.