plugin library
The runner-facing surface of the Tracera Dart core.
The runner packages import it to drive the reporting lifecycle. It is not
part of the customer API and carries no compatibility promise for test
authors — they use package:tracera/tracera.dart.
Keep this barrel tight: an export no runner (or e2e) uses is dead API.
Unit tests that need an internal seam import package:tracera/src/…
directly — do not widen this file for testability.
Classes
- AttachmentMeta
- References an uploaded blob on a step or on the result.
- BindTags
- A declarative bind read from runner tags.
- Client
- Talks to the Tracera Autotest API.
- EnvVarsExtraOptions
- Describes the synthetic Env keys a runner contributes.
- JobPool
- Runs blob materialize / upload jobs with bounded concurrency.
- Payload
- The customer-visible snapshot of one test result.
- PeerClaim
- The outcome of a peer claim.
- PendingResult
-
One buffered
TestResultawaiting upload. - ReporterState
- The per-process reporting lifecycle a runner drives.
- ResultBuffer
- Batches results and flushes on size / time / end of run.
- Session
- Holds the run this process reports into plus error accounting.
- StepHandle
- An open step. Close it exactly once.
- StepJson
- One flattened step on the wire.
- TestContext
- The active test pin: bind, section, step tree and extras.
Enums
- StepSection
- The lifecycle bucket a step lands in.
Constants
- handoffKeyEnv → const String
- Optional shared launch id for peer handoff.
- peerCountEnv → const String
- The expected number of peer processes for one launch.
- peerWorkerEnv → const String
- Opts a forked peer process into run-id handoff.
Properties
- resolveHostContext ↔ TestContext? Function()?
-
Optional runner hook that returns the pin for the host's current test.
getter/setter pair
- syncHostSection ↔ void Function()?
-
Optional runner hook consulted before customer APIs record anything.
getter/setter pair
Functions
-
beginReporting(
ReporterState state) → Future< void> - Resolves config, opens or attaches to a run, and arms the buffer.
-
beginStep(
String title) → StepHandle - Opens a step under the active context (plugin tier).
-
buildEnvVarsExtra(
[EnvVarsExtraOptions options = const EnvVarsExtraOptions()]) → Map< String, String> -
Returns the synthetic Env keys (
OS/ARCH/DART_VERSION) plus runner version and retry keys when supplied. -
claimPeerRun(
int projectId, String runTitle, Future< int> createRun(), {Map<String, String> ? env}) → Future<PeerClaim> - Attaches to the shared run id, creating it on first claim.
-
clearContext(
[TestContext? only]) → void - Drops the isolate-wide pin (plugin tier).
-
createReporterState(
) → ReporterState - Builds an idle reporter state.
-
createTestContext(
int testCaseId, String autotestName) → TestContext - Builds the pin for one test (plugin tier).
-
discardPeerRun(
int projectId, String runTitle, {Map< String, String> ? env}) → void - Drops the shared handoff state without finishing the run.
-
discardPendingBlobs(
Payload? payload) → void -
Drops the bodies behind every pending slot on
payload(result level and every step). -
durationMinutesFromMs(
num ms) → double -
Converts wall-clock milliseconds to
TestResult.durationMinutes: one decimal, half-up. -
endReporting(
ReporterState state) → Future< void> - Drains uploads, flushes results and closes the run.
-
enqueueResult(
ReporterState? state, PendingResult? item) → void - Resolves the result's pending attachments and buffers it for upload.
-
flushResults(
ReporterState state) → Future< void> - Drains attachment uploads and uploads the buffered results without closing the run.
-
formatFailureText(
Object? error, [StackTrace? stack]) → String - Renders a readable message plus stack when available.
-
getContext(
) → TestContext? -
Returns the pin for the current async context, falling back to the
host resolver and the isolate-wide pin, or
nulloutside a reported test. -
installContext(
TestContext? ctx) → void -
Pins
ctxisolate-wide until clearContext (plugin tier). -
logDebug(
String message) → void - Writes a debug line to stdout.
-
markSkipped(
TestContext? ctx, String? reason) → void - Shapes a Skipped result (plugin tier): the reason becomes the result comment, recorded steps are dropped and result-level fail text is cleared.
-
parseBindTags(
Iterable< String> tags) → BindTags -
Reads
tracera-id-‹id›and optionaltracera-name-‹name›from runner tags. -
payloadHasFailedStep(
Payload payload) → bool - Whether any step finished Failed.
-
payloadHasStepError(
Payload payload) → bool - Whether any step already carries the failure, so runners keep fail text XOR between step and result.
-
peerWorkerLabel(
[Map< String, String> ? env]) → String - Returns a short label when this process is an opted-in peer worker, else an empty string.
-
peerWorkerLabelFor(
String? worker) → String - Renders a worker id a runner detected itself (not from the env opt-in) as a log label.
-
recordFailure(
TestContext? ctx, Object? err, [StackTrace? stack]) → void - Puts fail text on the open step, else on the result (plugin tier).
-
releasePeerRun(
int projectId, String runTitle, Future< void> finish(), {Map<String, String> ? env}) → Future<void> -
Drops one participant; the last expected peer calls
finish. -
resetForRetry(
TestContext? ctx) → void - Drops everything a previous attempt recorded — steps, comments, errors and attachments — so a retried test reports its final attempt only (plugin tier). The bind (test case id and result name) is kept.
-
runWithContext<
T> (TestContext? ctx, T body()) → T -
Pins
ctxfor the duration ofbodyby forking a zone. -
sectionStep<
T> (StepSection section, String title, T body()) → T -
Runs
bodyas a step insidesection, restoring the previous section afterwards so the test body keeps reporting to Test (plugin tier). -
setPhase(
StepSection section) → void - Moves the active context into a lifecycle section (plugin tier).
-
snapshotPayload(
TestContext? ctx) → Payload - Freezes the step tree and extras for upload (plugin tier).
Exceptions / Errors
- Failure
- Carries a message plus an optional captured stack.