Environment variables

Every Precept setting can be set from the environment. This page is the complete list, generated by hand from the settings classes themselves — PreceptSettings, the module settings, and the three reporters' — and it is the reference a pipeline is written against.

• The rule
• Value formats
• The run
• Filter
• Web
• Api
• Assertions
• Grpc
• TestData
• Reqnroll
• ConnectionStrings
• Reporting
• Reporting:ReportPortal
• Reporting:Teams
• Reporting:AzureDevOps
• Sections of your own
• Test data values: a second namespace
• Variables Precept reads but does not own
• What has no variable
• Working with them

The rule#

PreceptSettings.Load builds its configuration from three sources, each overriding the last:

precept.json  →  precept.{environment}.json  →  PRECEPT_* environment variables

The variable name is the configuration key, prefixed with PRECEPT_, with every : written as a double underscore:

Names are case-insensitive: PRECEPT_WEB__HEADLESS and Precept_Web__Headless are the same variable. The __ is not decoration — .NET's environment provider rewrites it to : before matching, which is the only way to express a nested key in a name that has to be a valid environment variable.

PRECEPT_ is a namespace with an owner. Everything carrying that prefix is stripped of it and bound as a settings key, whether it names a real setting or not. Do not use it for a variable of your own — a pipeline's scratch values, a script's working state — because a name that happens to collide with a real key changes the run and nothing says so.

Value formats#

A boolean must be spelled out. The binder uses bool.Parse, and 1 is not a boolean to it — it fails the run before a test starts, not quietly:

Unhandled exception. System.InvalidOperationException: Failed to convert configuration value '1'
at 'IsContinuousIntegration' to type 'System.Boolean'.

Worth knowing because a CI system that writes 1 for a checkbox is not unusual, and because CI=1 — the one variable Precept reads for its value rather than binding — does work.

A dictionary entry is a variable of its own, and the key is whatever follows the last __:

PRECEPT_API__DEFAULTHEADERS__X-TENANT=acme        # Api:DefaultHeaders["X-Tenant"]
PRECEPT_REPORTING__TEAMS__FACTS__BRANCH=main      # Reporting:Teams:Facts["Branch"]

A list element is indexed:

PRECEPT_TESTDATA__FILES__0=testdata.json
PRECEPT_TESTDATA__FILES__1=vehicles.json

An empty value is a value. PRECEPT_FILTER__EXCLUDE= does not mean "the pipeline has no opinion"; it sets the exclude expression to empty and so overrides whatever precept.{environment}.json asked for. Unset the variable rather than blanking it.

The run#

Bound onto PreceptSettings itself, so these have no section in their name.

Filter#

Tests this run pretends were never written: absent from the run, from the report and from a test explorer's tree, rather than reported as skipped. This is the environment's own policy, and it is applied in discovery — --precept-filter cannot select a test it has removed.

Both are single expressions rather than lists, precisely so a later source can replace one outright. The expression language is the same one --precept-filter takes.

Web#

Api#

Assertions#

Read only by assertions that wait — those built with Assert.Eventually. An assertion over a value already in hand is decided immediately and reads none of this.

Grpc#

TestData#

These configure the module. The data itself lives in its own files, and has a namespace of its own.

Reqnroll#

Read as the first scenario starts, by Precept.Reqnroll's runtime plugin. The section's other keys — FEATURELANGUAGE, ALLOWROWTESTS, ADDNONPARALLELIZABLEMARKERFORTAGS, ALLOWDEBUGGENERATEDFILES, DISABLEFRIENDLYTESTNAMES — shape the generated code and are read from the project's precept.json while the feature files compile, so a variable cannot reach them; see configuring Reqnroll.

ConnectionStrings#

One variable per named connection, the name being whatever follows the last __. Db.Query(...) uses Default unless told otherwise.

PRECEPT_CONNECTIONSTRINGS__DEFAULT='Host=db.stage;Database=app;Username=tests;Password=…'
PRECEPT_CONNECTIONSTRINGS__WAREHOUSE='Server=…'

A connection string holds a password, so this is a variable and not a line in precept.json.

Reporting#

The pipeline itself. What each reporter does with the events is in its own subsection below.

PRECEPT_REPORTING__CIONLY=false is the single variable that makes a laptop report for one run. From there a missing API key is an error, because you have just asked that machine to report.

Reporting:ReportPortal#

Reporting:Teams#

Reporting:AzureDevOps#

Sections of your own#

The rule is not special to Precept's own settings. A class registered with services.AddPreceptSettings<AuthSettings>() binds from the Auth section — the type's name without a Precept prefix or a Settings/Options/Configuration/Config suffix — and so reads:

PRECEPT_AUTH__TOKENENDPOINT=https://id.acme.com/token
PRECEPT_AUTH__CLIENTID=test-runner
PRECEPT_AUTH__CLIENTSECRET=…            # from the build's secret store, never from precept.json

An explicit section name follows the same shape: services.AddPreceptSettings<AuthSettings>("Tenants:Primary") reads PRECEPT_TENANTS__PRIMARY__CLIENTSECRET.

Test data values: a second namespace#

Precept.TestData builds a configuration of its own for the data, and adds the environment to it under the prefix PRECEPT_TESTDATA__. That is how a password stays out of a data file:

PRECEPT_TESTDATA__USERS__ADMIN__PASSWORD=…      # users:admin:password

The path after the prefix is the data path, lowercased by convention and matched case-insensitively, so this overrides users.admin.password from testdata.json and its overlay.

One caveat, and only for variables. The two namespaces overlap: PRECEPT_TESTDATA__… is seen by the main configuration as well, under the TestData section — which is where the module's own settings live. So the four names in TestData mean both things at once, in both directions. PRECEPT_TESTDATA__DIRECTORY=/data sets the module's directory and injects a data value at path directory; overriding a root data path called files from a variable would also rewrite the module's file list.

Data files are unaffected — they are read by the test data store alone, so a JSON key named directory or files in testdata.json collides with nothing. It is only the environment that sees both. If a data set has a root key with one of those four names and it has to be overridable from CI, nest it a level down.

Data files can also read arbitrary variables through a token, which is a different mechanism again — it is resolved where the value is used, not bound to a setting:

{ "users": { "admin": { "note": "{{env:BUILD_BUILDNUMBER}}" } } }
{ "users": { "admin": { "note": "{{env:BUILD_BUILDNUMBER|local}}" } } }

Without a |fallback an unset variable fails the test that reads it, which is the difference between a suite that runs on a developer's machine and one that only runs on the agent.

Variables Precept reads but does not own#

The environment is not the only source for either of those two things. The full resolution order for the environment is --precept-environment, PRECEPT_ENVIRONMENT, DOTNET_ENVIRONMENT, the PreceptEnvironment MSBuild property, "Environment" in precept.json, then local; and IsContinuousIntegration is an ordinary setting whose default is the detection above, so PRECEPT_ISCONTINUOUSINTEGRATION and an overlay both override it.

What has no variable#

--precept-filter is a command-line option and nothing else. It says what this run selects rather than how the suite behaves, which is why it is not a setting — and why there is no PRECEPT_FILTER. That name would be misleading if it existed: Filter is the section holding Filter:Include and Filter:Exclude, which is the other filter, applied in discovery.

For an IDE with nowhere to type a runner argument, testconfig.json beside the project supplies command-line options from a file:

{ "commandLineOptions": { "precept-environment": "stage" } }

.runsettings does nothing here at all — it is VSTest-only, and Precept runs on Microsoft.Testing.Platform.

Working with them#

Set one for a single run:

PRECEPT_MAXPARALLELISM=3 dotnet run --project tests/Acme.Tests -- --list-tests

Every run states the two things most often set wrongly, so a variable that did not take effect is visible in the first line of output:

[Precept] Environment 'stage'. Up to 3 classes in parallel. Filter excluded 5 of 233 tests.
[Precept] There is no 'precept.stag.json' beside the test binary, so the run is using
          'precept.json' alone. Check the environment name if that is not what you meant.

The unit is classes or tests depending on ParallelScope, the filter clause appears only when the configuration filter actually removed something, and the missing-overlay warning is suppressed for local — which has no overlay by design.

On CI, keep endpoints and project names in precept.json where they can be reviewed, and pass only the credentials — the four marked Credential above, plus ConnectionStrings — from the build's secret store. Running a suite on CI is a worked Azure Pipelines example doing exactly that.