Precept 0.14.0

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.

.runsettings does 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 --settings option at all. Its replacement is testconfig.json in 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.json only for one machine's override that should not touch the project file. It outranks precept.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"

Precept 0.14.0 · MIT · © 2026

Esc