Precept 0.14.0

Configuration

Precept reads its settings from precept.json beside the test binary. Two more sources overlay it, each one winning over the last:

precept.json  →  precept.{environment}.json  →  PRECEPT_* environment variables
{
  "MaxParallelism": 8,
  "ParallelScope": "Class",
  "RunTimeoutMinutes": 180,
  "Web": { "BaseUrl": "https://staging.example.com", "Browser": "chromium", "Headless": true },
  "Api": { "BaseUrl": "https://api.staging.example.com" },
  "ConnectionStrings": { "Default": "Host=localhost;Database=app" }
}

Comments and trailing commas are allowed in these files. .NET's JSON configuration provider skips them.

Every setting can also be set from the environment. Web:Headless becomes PRECEPT_WEB__HEADLESS. That is how a pipeline overrides a run, and how a credential stays out of source control. Environment variables is the complete list, with each default.

Getting the files into the output directory#

Precept.TestPlatform copies precept.json and every precept.*.json beside it to the output directory. Adding one of these files is all there is to it; there is no <None Update> to write. Set <EnablePreceptSettingsCopy>false</EnablePreceptSettingsCopy> to take that over yourself. A file the project already gives CopyToOutputDirectory is left alone either way.

You do not have to write the first one. A project that builds with no precept*.json gets a commented precept.json from the package, created and copied to the output directory in that same build. From then on it is yours to edit and commit. The file is only written when the project has no precept*.json at all, so an existing file is never touched, and a suite that keeps only an overlay is left alone. Deleting the file is not remembered, though: the next build writes it again unless the project says otherwise:

<PropertyGroup>
  <EnablePreceptSettingsScaffold>false</EnablePreceptSettingsScaffold>
</PropertyGroup>

Completion in an editor#

Precept publishes a JSON schema for these files, generated from the settings classes themselves. Every key, its type, its default and its documentation are the ones this version of Precept reads. Name the schema at the top of the file and an editor completes the sections, offers the values an enum accepts, and shows each setting's description as you type:

{
  "$schema": "https://autom3tion.github.io/precept-docs/precept.schema.json",
  "Web": { "Browser": "chromium" }
}

The templates and the scaffolded precept.json already carry that line. It belongs in the precept.{environment}.json overlays too, since they bind the same shape. Precept itself reads nothing from it; $schema is just a key that nothing binds to.

Sections and keys the schema does not name are allowed everywhere, at the top level and inside any block. A suite's own settings are as legitimate as Precept's, so they complete nothing and warn about nothing. Two things follow from that:

  • Completion is case-sensitive, and binding is not. "headless" binds exactly as "Headless" does, but the schema will not have suggested it and will not describe it. Nothing is underlined; it is simply a key the editor has nothing to say about.

  • Comments are the editor's business, not the schema's. Precept and .NET's configuration provider both allow // comments and trailing commas, but an editor that reads precept.json as strict JSON flags them anyway. Tell it otherwise once:

    { "files.associations": { "precept*.json": "jsonc" } }

The schema is precept.schema.json. It is regenerated on every release, so a key added by a new version is offered as soon as the project is on it. Every setting is the same information as one file you can read top to bottom: a precept.json with every key at its default, generated from the same place.

Where a section comes from#

It is one file, but not one owner.

The runner owns the top level: MaxParallelism, ParallelScope, RunTimeoutMinutes, DefaultTimeoutMilliseconds, DefaultRetries, ArtifactDirectory, Environment and IsContinuousIntegration, plus the Filter, Assertions, Reporting and ConnectionStrings sections. Those are on PreceptSettings, the object startup is handed.

Every other section belongs to the package that reads it, and is registered by that package's AddPrecept… call: Web by Precept.Web, Api by Precept.Api, Grpc by Precept.Grpc, TestData by Precept.TestData, Files by Precept.Files, and each Reporting:<Name> subsection by its reporter. A browser setting is versioned with the browser module, and a project that never installed a module is never offered its settings. Reqnroll is the one section with no registration call: Precept.Reqnroll's plugins read it themselves, at build time and as the first scenario starts. See configuring Reqnroll.

Two things follow:

  • A section is read only if its module is registered. A Web block in a project that never calls AddPreceptWeb() is read by nothing. The MCP server's precept_explain_module says so for each module, because configuration that does nothing looks identical to configuration that works.

  • Overriding a module's setting in code is an argument to its registration, not an assignment on PreceptSettings. See startup:

    services.AddPreceptWeb(web => web.BaseUrl = stub.BaseUrl);

The file itself does not care who owns what. Every section sits at the top level of precept.json, and every section is overlaid and overridden by environment variables the same way.

Your own settings#

Precept does not try to model everything a suite might need to configure: authentication, tenants, feature flags, a service address. Put those in the same file, under a section of your own, and bind them onto a class you write:

{
  "Api": { "BaseUrl": "https://api.staging.example.com" },
  "Auth": { "TokenEndpoint": "https://id.example.com/token", "ClientId": "test-runner" }
}
public sealed class AuthSettings
{
    public string? TokenEndpoint { get; set; }
    public string? ClientId { get; set; }
    public string? ClientSecret { get; set; }
    public int TimeoutMilliseconds { get; set; } = 10_000;
}

public sealed class Startup : IPreceptStartup
{
    public void ConfigureServices(IServiceCollection services, PreceptSettings settings)
    {
        services.AddPreceptSettings<AuthSettings>();
        services.AddSingleton<ITokenProvider, TokenProvider>();
    }
}

AuthSettings is then a singleton like any other, injected into step definitions, page objects and fixtures:

[Binding]
public class AuthSteps(AuthSettings auth, ITokenProvider tokens) { }

The section name defaults to the type's name without a Precept prefix or a Settings/Options suffix, so AuthSettings reads "Auth". Pass a name for anything else, including nested sections:

services.AddPreceptSettings<AuthSettings>("Tenants:Primary");
services.AddPreceptSettings<AuthSettings>(configure: a => a.ClientSecret = Vault.Read("client-secret"));

Custom sections get the same treatment as the built-in ones. They are overlaid by precept.{environment}.json and then overridden by environment variables: PRECEPT_AUTH__CLIENTSECRET sets Auth:ClientSecret, which is how a secret stays out of source control. Properties absent from configuration keep their defaults, so a section is optional. A configure callback runs after binding and wins.

To read a section without registering it, for example to branch on it while wiring services, use settings.GetSection<T>(). The raw IConfiguration is on settings.Configuration.

Precept 0.14.0 · MIT · © 2026

Esc