Installing
Precept ships as a set of NuGet packages. Pick the ones for what you are testing. Each brings in
Precept.Core and everything else it needs.
| Package | Install it to |
|---|---|
Precept.TestPlatform |
Run Precept tests. This is the runner, and every test project starts here. |
Precept.Reqnroll |
Write scenarios in .feature files. Carries both Reqnroll plugins, so nothing else is needed for Gherkin. |
Precept.Api |
Call HTTP APIs. |
Precept.Web |
Drive a browser through Playwright. |
Precept.Screenplay |
Write the suite as actors performing interactions. Brings Precept.Web with it. |
Precept.Data |
Talk to a database over ADO.NET. |
Precept.TestData |
Manage the users, clients, vehicles and other records the tests need. |
Precept.Files |
Write and read Excel, CSV, JSON and XML files. |
Precept.Grpc |
Call gRPC services. |
Precept.Containers |
Start Docker dependencies for the run. |
Precept.Reporting.ReportPortal |
Report runs to ReportPortal. |
Precept.Reporting.Teams |
Post a run summary to a Teams channel. |
Precept.Reporting.AzureDevOps |
File results against Azure DevOps test cases. |
Precept.Core is published too. Reference it directly only for a library of shared step definitions
or helpers that must not depend on the runner, or for a
reporter of your own.
A complete test project#
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Precept.TestPlatform" Version="0.14.0" />
<PackageReference Include="Precept.Reqnroll" Version="0.14.0" />
<PackageReference Include="Precept.Api" Version="0.14.0" />
</ItemGroup>
</Project>
That is the whole file. Precept.TestPlatform makes the project an executable and generates the
entry point, so there is no Main and no OutputType to write. Precept.Reqnroll brings the
code-behind generator, so .feature files compile on their own. The first build writes a commented
precept.json into the project; see Configuration.
global.json#
dotnet test on the .NET 10 SDK has to be told to use Microsoft.Testing.Platform, and that setting
lives in global.json:
{
"test": {
"runner": "Microsoft.Testing.Platform"
}
}
Put it at the repository root, beside the solution. If the repository already has a global.json
that pins an SDK version, merge the test section into it.
The SDK reads global.json from the directory you run dotnet test in and the directories above
it, not from the project's directory. A copy inside the project directory only works when the
command is run from inside that directory, and it replaces the root's SDK pin for that subtree.
Without it dotnet test fails with "Testing with VSTest target is no longer supported". Running
the test binary directly, with dotnet run -- --list-tests, works either way.
precept_diagnose_project reports a missing declaration as PMCP003, and one that sits inside a
project under a repository root as PMCP010.
The MCP server#
Precept.Mcp is published as a dotnet tool, not a library. It is a server a coding agent
talks to, so nothing in a test project references it:
dotnet tool install --global Precept.Mcp
Point an MCP client at the precept-mcp command, or at dnx Precept.Mcp to run it without
installing anything. See Precept.Mcp and
Working with a coding agent for the skills and the Copilot agent that go with it.
The tool bundles its own copy of Precept.Core, so it answers from its version rather than the
project's. A global install is one version for the whole machine, so it can answer a second
repository with the first one's rules. Every answer names the version behind it, and
precept_diagnose_project raises PMCP008 when the two could disagree. Use
dnx Precept.Mcp@<version> to pin it per project.
Upgrading#
Move every Precept.* package to the new version at once. They are released together and a mixed
set is not supported.
While the major version is 0, a minor release may rename an API or a setting. Plan for a short pass over the suite rather than a version bump on its own.
Start with the release notes. The entries between the version you reference and the one you are moving to say which areas changed, which is where to look hardest. They narrow the search rather than end it: an entry names a change, not every line it touched.
After the bump, three things tell you what changed. Work through all of them:
| Check | Finds |
|---|---|
| Build the solution | Types and members that were renamed or removed. |
| Compare every settings file against the schema | Keys the new version no longer knows. |
| Compare the values you rely on against the settings reference | Defaults that moved. |
The middle one is the one to be deliberate about. A precept.json key that no longer exists is not
an error and is not underlined in an editor — the schema accepts your own sections
and cannot tell them from a mistake. The key simply stops doing anything, and the suite keeps
passing with the setting ignored.
Update the tooling in the same change, so it describes the version you now reference:
npx skills add autom3tion/precept-skills
dotnet tool update --global Precept.Mcp
precept_diagnose_project reports a server that could disagree with the project as PMCP008. Run
it after the upgrade, then run the suite.
If .feature files stop producing tests, delete every *.feature.cs and rebuild. Reqnroll caches
the generated code against the feature file, so a new generator does not regenerate anything by
itself. See Working with a coding agent for the precept-upgrading skill, which
walks an agent through all of this.