Environments
The environment is a name such as staging or local. It selects the overlay files: staging
loads precept.staging.json, and Precept.TestData loads testdata.staging.json beside every data
file.
The environment is resolved once per run. The first of these sources to say anything wins:
| Source | Typical use | |
|---|---|---|
| 1 | --precept-environment staging |
CI, and anything driven from a shell |
| 2 | PRECEPT_ENVIRONMENT |
a build agent, a container |
| 3 | DOTNET_ENVIRONMENT |
a suite that already sets it |
| 4 | the build configuration | switching environments in an IDE |
| 5 | "Environment" in precept.json |
the team's default |
| 6 | — | local |
An "Environment" key in an overlay does nothing, because the overlay is chosen before it is read.
dotnet run --project Checkout.Tests -- --precept-environment staging
dotnet test --project Checkout.Tests/Checkout.Tests.csproj -- --precept-environment staging
Every run prints which environment it used, and says when the overlay for it is missing. That is what a typo looks like, and without the message the suite would quietly run against the defaults:
[Precept] Environment 'staging'. Filter excluded 5 of 33 tests.
[Precept] There is no 'precept.nope.json' beside the test binary, so the run is using 'precept.json' alone.
Switching environments from an IDE#
Neither Visual Studio's Test Explorer nor VS Code's testing pane has anywhere to type a runner argument. Editing a committed file to switch leaves a modified working tree you have to remember not to push. Make each environment a build configuration instead. The IDE already has a picker for those.
Declare them once, in the test project or in Directory.Build.props:
<PropertyGroup>
<Configurations>Debug;Release;Dev;Stage</Configurations>
</PropertyGroup>
<PropertyGroup Condition="'$(Configuration)' == 'Dev'">
<PreceptEnvironment>dev</PreceptEnvironment>
</PropertyGroup>
<PropertyGroup Condition="'$(Configuration)' == 'Stage'">
<PreceptEnvironment>stage</PreceptEnvironment>
</PropertyGroup>
That is all. Precept.TestPlatform writes PreceptEnvironment into runtimeconfig.json as a
Precept.Environment property, and Precept reads it back at startup. Pick Stage from the
configuration list and Test Explorer runs against Stage; pick Dev and it runs against Dev.
Nothing is edited and nothing is pushed by accident, because the selected configuration is IDE
state, not a file in the repository. From a shell it is dotnet test -c Stage.
Each configuration builds to its own directory, such as bin/Stage/, so switching costs a rebuild
and the two never overwrite each other's output. Add the configurations to the solution too
(Visual Studio: Build → Configuration Manager) so the picker offers them.
An environment variable or --precept-environment still overrides the build configuration, which
keeps CI in charge of its own runs.
.runsettingsdoes not work here. It is a VSTest concept, and Precept is a Microsoft.Testing.Platform framework with no VSTest bridge:dotnet test --settings …runs zero tests and exits 5. The platform has no--settingsoption at all. Its replacement istestconfig.jsonin the project directory, which sets any runner option and is copied to the output as{AssemblyName}.testconfig.json:{ "commandLineOptions": { "precept-environment": "stage" } }Prefer a build configuration. Reach for
testconfig.jsononly for one machine's override that should not touch the project file. It outranksprecept.json, so gitignore it if that is how you use it.
To run against two environments at once, for example a smoke pack against staging while a regression pack runs locally, use two shells:
dotnet run --project Checkout.Tests -- --precept-environment staging --precept-filter "smoke" &
dotnet run --project Checkout.Tests -- --precept-environment local --precept-filter "not smoke"