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

BindTags

A declarative bind read from runner tags.

EnvVarsExtraOptions

Describes the synthetic Env keys a runner contributes.

Payload

The customer-visible snapshot of one test result.

PendingResult

One buffered TestResult awaiting upload.

ReporterState

The per-process reporting lifecycle a runner drives.

TestContext

The active test pin: bind, section, step tree and extras.

Enums

StepSection

The lifecycle bucket a step lands in.

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.

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.

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).

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.

getContext() → TestContext?

Returns the pin for the current async context, falling back to the host resolver and the isolate-wide pin, or null outside a reported test.

installContext(TestContext? ctx) → void

Pins ctx isolate-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 optional tracera-name-‹name› from runner tags.

recordFailure(TestContext? ctx, Object? err, [StackTrace? stack]) → void

Puts fail text on the open step, else on the result (plugin tier).

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.

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.