Vocabulary

Every ProtoTest word the docs and the lessons use, in one plain sentence. Each row links the lesson that teaches the word and the page with the details. The trace, the reports and the viewer use the same words.

The run and what it shares

Word	In plain words	Learn it	Details
run	One dotnet test invocation and everything it does.	Run the sample suite	Host and lifecycle
host	The one ProtoHost per test process. It starts what the tests share, owns it and stops it after the last test.	Know when the host starts and stops	Host and lifecycle
setup class	The class in your test project that tells the host what to start. Your runner calls it once.	Know when the host starts and stops	Runners
integration	A ProtoTest package for one kind of system, such as REST, SQL or a browser.	Add and remove an integration	Integrations
capability	Something the run can do for a test, such as "there is a broker". A test that needs a missing capability skips with a reason.	Read what your run provides	Skip conditions
target	A named thing the suite needs, such as the database, the broker or the API.	Run the suite on containers	Environment resolution
address	Where a target is reached, read from configuration, such as ProtoTest:Applications:{name}:BaseUrl or a connection string.	Point the suite at a real stack	Environment resolution
provider chain	The ordered ways to get one target. The first that applies wins, such as a configured address before a container.	Run the suite on containers	Environment resolution
in-process	The application runs inside the test process, so a test can reach its services and its clock.	Read what your run provides	ASP.NET Core
loopback	The application started on a free local port as a separate server, for a browser to reach.	Wait for readiness, not for time	Infrastructure
AppHost	An Aspire project that declares an application's processes and services, so they start together.	Let Aspire start the topology	Aspire
run gate	A check over the whole run after the last test. A failed gate fails the run, even when every test passed.	Why the run is red when every test is green	Host and lifecycle

One test

Word	In plain words	Learn it	Details
test context	The per-test ProtoExecutionContext behind Proto.Context: this test's clients, data, identity and files.	Write your first test	Test context
client	The object a test uses to talk to a system, such as Proto.Context.Rest().	Write your first test	Clients
attribute	A C# attribute on a test that prepares something before it and undoes it after.	Write your own attribute	Attributes
hook	Code that runs around every test, or around the whole run.	Write an integration	Hooks
data surface	Proto.Context.Data(): where a test asks for test data. A registered provisioner creates it and registers its cleanup.	Create test data with a provisioner	Provisioners
test-owned, run-owned	Who releases a resource: the test's teardown, or the host after the last test.	Check that a test cleans up	Infrastructure recipes
tenant	In the Northstar sample, one customer's isolated data. Each test gets its own.	Give each test its own state

The trace

Word	In plain words	Learn it	Details
trace	The .prototrace file a run writes: a zip with everything the run did.	See why a test failed	ProtoTrace
viewer	The page at trace.prototest.dev that opens a trace in your browser.	See why a test failed	ProtoTrace
operation	One recorded step: a call, a check, a setup step. Its kind, such as http.request, says what sort of step.	See why a test failed	ProtoTrace
phase	Setup, execution or teardown: the parts of every test in the trace.	See why a test failed	Lifecycle phases below
run layer	The part of the trace that belongs to no single test: the host's capabilities, resources and releases.	Know when the host starts and stops	Lifecycle phases below
trace entity	One thing whose state the run recorded, such as a client or the test user. Operations point at it by id.	Check that a test cleans up	Trace entity kinds below
check	An assertion as the trace records it, with what it expected and what it read.	Read a failing trace	Assertions
observation, finding, attachment	A fact a test learned, something worth reporting that is not the result, and a file the test kept.	Why a passing test can still leave an error	Three different things below
digest	The short failure summary prototest summary prints, and CI posts as a comment.	Keep the evidence when CI fails	Diagnosis
MCP	Model Context Protocol: how a coding agent calls tools. ProtoTest's MCP server lets it read traces.	Run the evidence loop with an agent	Agent setup

Lifecycle phases

Every trace entry belongs to one phase:

Phase	What runs
Setup	the test hooks, then the attributes, before the body
Execution	the test body
Teardown	attributes and hooks in reverse, attachments publish, resources release
Rollback	teardown after a failed setup, in place of Teardown
Run	run-level work: run hooks, gates and infrastructure. The viewer calls this the run layer.

The order, the failure rules and the rollback walk are in Host and lifecycle.

Trace entity kinds

Entities are state, not history: each appears once in the archive with its latest state and its versions. An operation names the entity it acted on, so a reader can follow a call to the client that made it:

state.json (l1-first-journey)3 notes

1{1
2"id": "client:System.Net.Http.HttpClient:Northstar",
3"client.name": "Northstar",
4"client.owned": true,
5"client.initializer": "AspNetCoreClientInitializer`1",
6"resource.state": "released"
7}
8{2
9"id": "Northstar.ProtoTest.NorthstarMemberContext",
10"context.type": "Northstar.ProtoTest.NorthstarMemberContext",
11"context.value": { "Id": "owner", "Token": "[REDACTED]" }
12}
13{3
14"kind": "http.request",
15"name": "REST · POST /api/v1/projects",
16"entity": "client:System.Net.Http.HttpClient:Northstar",
17"http.response.status_code": 201
18}

1. 1
   A client entity

   The in-process client the test used. Owned by the test, created by the ASP.NET Core initializer, released at teardown.

2. 2
   A context entity

   Typed state the member attribute set. Secrets are redacted in the archive, so the token reads [REDACTED].

3. 3
   The operation that points at it

   The POST names the client entity by id and carries what it returned: status 201.

Two entities and the operation that points at them, from docs/static/lessons/l1-first-journey.prototrace.

Example ids come from the lesson archives (l1-first-journey, l3-clock-window).

Kind	Id	Example id	What it records
client	client:{fullTypeName}:{name}	client:System.Net.Http.HttpClient:Northstar	a client a test resolved
context	{fullTypeName}, or {key}:{fullTypeName} when set with a key	Northstar.ProtoTest.NorthstarMemberContext	typed state an attribute or hook set
auth	auth:user	auth:user	the test user and how it signed in
server	server:{entryPointFullName}:{application}	server:ProtoTest.SampleApp.Program:Northstar	the in-process application server
capability	{kind}:{name}, with :{instance} when the descriptor carries one	server:ASP.NET Core:Northstar	what the run can serve
clock	clock:run for the run, and a clock per test	clock:725654000001	the clocks a test can advance
device	device:{client}:{deviceType}:{id}	a pattern; no lesson archive records one	a device session

Tracked values are state items with kind value and an id of the form {type}:{identity}. Infrastructure and resources use their own ids. The entry kinds themselves, from test.setup to the last assertion, are listed in ProtoTrace.

Observations, findings and attachments

Three different things, three different destinations:

	Observation	Finding	Attachment
What it is	a fact a test learned	something worth reporting that is not a failure	a file a test produced
Who records it	integrations; you with RecordObservation	you with AddFinding; a teardown failure becomes one	integrations; you with AddAttachment
Where it goes	collectors, then reports, and the trace	reports and run gates, and the trace	the runner, and the archive
What it does not do	fail a test or a gate	replace a body failure. A passing test whose cleanup failed is reported as failed unless CleanupFailures is Report	count as coverage

Coverage is built from observations, which is why this distinction matters: a fact a test did not state is not coverage. See Coverage and observations and Attachments.