plesty.server.model.field_test

A device’s field test: what to run, and what a run published.

Every hub device scaffolded with plesty init field-test carries tests/field_test.py (the host tier — opens the instrument itself) and may carry tests/field_test_client.py (the client tier — talks to a running server). Both are the repository’s own scripts, so they exist only in a git checkout, run with the checkout’s interpreter, and publish reports/<instrument>/field-test.json (field-test-client.json for the client tier) — the artifact hub.plesty.net and manager.plesty.net read. The markdown and JSONL beside it carry the address and serial and stay on the bench.

This module is the data only: FieldTestRun turns a request into the script’s argument list, FieldTestReport reads what a run published. Running it is a job (plesty.server.services.jobs); stopping the device server for a host-tier run and restarting it afterwards is the presenter’s choreography.

Attributes

TIER_SCRIPTS
TIER_ARTIFACTS
REPORT_BASENAME
JOB_KIND
STANDARD_GATES

Exceptions

FieldTestError

A field test cannot be set up as asked.

Classes

FieldTestRun	One field-test request.
GateResult	One gate of a published report.
FieldTestReport	What a field test published — the summary a bench needs, not the whole document.

Functions

gates_in_help(→ tuple[str, Ellipsis])	The gate names a script's --help offers for --gates, in its order; empty if none.
options_in_help(→ set[str])	The long options an argparse --help text mentions (--address, --mock …).
field_test_script(→ pathlib.Path | None)	The tier's script inside checkout, or None when the module has none.
find_reports(→ list[FieldTestReport])	Every published field-test report under <checkout>/reports/, newest first.

Module Contents

plesty.server.model.field_test.TIER_SCRIPTS: collections.abc.Mapping[str, str]

plesty.server.model.field_test.TIER_ARTIFACTS: collections.abc.Mapping[str, str]

plesty.server.model.field_test.REPORT_BASENAME = 'reports/field-test-run'

plesty.server.model.field_test.JOB_KIND = 'field-test'

plesty.server.model.field_test.STANDARD_GATES: tuple[str, Ellipsis] = ('discovery', 'connect_lifecycle', 'param_roundtrip', 'param_constraints', 'functions',...

exception plesty.server.model.field_test.FieldTestError

Bases: plesty.server.model.errors.FleetError

A field test cannot be set up as asked.

Initialize self. See help(type(self)) for accurate signature.

plesty.server.model.field_test.gates_in_help(text: str) → tuple[str, Ellipsis]

The gate names a script’s --help offers for --gates, in its order; empty if none.

Parameters:

text (str)

Return type:

tuple[str, Ellipsis]

plesty.server.model.field_test.options_in_help(text: str) → set[str]

The long options an argparse --help text mentions (--address, --mock …).

Parameters:

text (str)

Return type:

set[str]

plesty.server.model.field_test.field_test_script(checkout: pathlib.Path, tier: str = 'host') → pathlib.Path | None

The tier’s script inside checkout, or None when the module has none.

Raises:

FieldTestError – On an unknown tier.

Parameters:

• checkout (pathlib.Path)

• tier (str)

Return type:

pathlib.Path | None

class plesty.server.model.field_test.FieldTestRun

One field-test request.

Variables:

• tier – host (instrument, server must be stopped) or client (running server).

• address – --address — host tier: instrument address or mock; client tier: tcp://…; None lets the script use .env.

• gates – Run only these gates (None = all).

• repetitions – --repetitions for the timing gates (None = script default).

• keep_going – Carry on after a failed gate.

• keep_server – Host tier: leave a running server alone (only right for mock or another instrument).

• extra – Further arguments passed to the script unchanged.

tier: str = 'host'

address: str | None = None

gates: tuple[str, Ellipsis] | None = None

repetitions: int | None = None

keep_going: bool = False

keep_server: bool = False

extra: tuple[str, Ellipsis] = ()

__post_init__() → None

Validate the request.

Return type:

None

property script: str

The script this request runs, relative to the checkout.

Return type:

str

property artifact: str

The published file name this tier writes.

Return type:

str

property needs_instrument: bool

Whether the run opens the instrument itself (host tier, not mock).

Return type:

bool

argv(report_base: str | None = REPORT_BASENAME, supports: collections.abc.Collection[str] | None = None) → list[str]

The script’s arguments for this request.

Parameters:

• report_base (str | None) – --report for the host tier’s internal .md/.jsonl pair; None leaves it to the script.

• supports (collections.abc.Collection[str] | None) – The option names the script accepts (from its --help), or None to assume the current scaffold. Older scaffolds take --port PORT and --mock where the current one takes --address; the request is spelled in whichever the script understands, and options it lacks are left out.

Return type:

list[str]

command(python: pathlib.Path, checkout: pathlib.Path, supports: collections.abc.Collection[str] | None = None) → list[str]

The full command line: python running the tier’s script in checkout.

Parameters:

• python (pathlib.Path) – The checkout’s interpreter.

• checkout (pathlib.Path) – The module checkout.

• supports (collections.abc.Collection[str] | None) – The script’s option names (see argv()).

Raises:

FieldTestError – When the checkout has no script for this tier.

Return type:

list[str]

to_dict() → dict[str, Any]

Record form (stored on the job’s detail).

Return type:

dict[str, Any]

classmethod from_dict(data: collections.abc.Mapping[str, Any]) → FieldTestRun

Rebuild a request from to_dict() output.

Parameters:

data (collections.abc.Mapping[str, Any])

Return type:

FieldTestRun

class plesty.server.model.field_test.GateResult

One gate of a published report.

name: str

status: str

duration_s: float

reason: str

class plesty.server.model.field_test.FieldTestReport

What a field test published — the summary a bench needs, not the whole document.

Variables:

• path – The field-test*.json file.

• tier – host or client, from the file name.

• instrument – The reports/<instrument>/ directory name.

• module – Module name from the document.

• version – Module version the run tested.

• ok – Overall outcome.

• passed – Gates passed.

• failed – Gates failed.

• skipped – Gates skipped.

• gates – Per-gate results, in run order.

• findings – Count of findings per severity (error/warning/info).

• modified_utc – ISO timestamp of the file — when the run ended.

path: pathlib.Path

tier: str

instrument: str

module: str

version: str

ok: bool

passed: int

failed: int

skipped: int

gates: tuple[GateResult, Ellipsis] = ()

findings: collections.abc.Mapping[str, int]

modified_utc: str = ''

property summary: str

pm100d 0.2.1 [host] ok 9/9 style.

Type:

One line

Return type:

str

classmethod from_path(path: pathlib.Path) → FieldTestReport

Read a published report.

Raises:

FieldTestError – When the file is not a field-test document.

Parameters:

path (pathlib.Path)

Return type:

FieldTestReport

plesty.server.model.field_test.find_reports(checkout: pathlib.Path, since_utc: str | None = None) → list[FieldTestReport]

Every published field-test report under <checkout>/reports/, newest first.

Parameters:

• checkout (pathlib.Path) – The module checkout.

• since_utc (str | None) – Only reports modified at or after this ISO timestamp — what a run that started then produced.

Return type:

list[FieldTestReport]