journeys

type Assertion struct {
	Subject  Subject   `json:"subject"`
	Target   *Selector `json:"target,omitempty"`
	Operator Operator  `json:"operator"`
	// Expected is the value compared against, typed by the subject: a string for a
	// text subject, a number for a numeric one, a bool for a boolean one, and an
	// array of those for is_one_of. An operator taking no operand rejects it.
	Expected any `json:"expected,omitempty"`
	// Message is a human description of what is being verified, carried through to
	// the assertion's PASS/FAIL line whether or not it polled.
	Message string `json:"message,omitempty"`
	// Wait turns a single evaluation into a polled one. Absent, the condition is
	// checked once.
	Wait *Wait `json:"wait,omitempty"`

	// Comparison modifiers, all defaulting off so behaviour is never implicit.
	IgnoreCase         bool `json:"ignore_case,omitempty"`
	Trim               bool `json:"trim,omitempty"`
	CollapseWhitespace bool `json:"collapse_whitespace,omitempty"`
}

type ElementFacts struct {
	Value    string
	Checked  bool
	Selected bool
	Enabled  bool
	Expanded bool

	HasValue          bool
	HasToggle         bool
	HasSelection      bool
	HasInvoke         bool
	HasExpandCollapse bool
}

type Event struct {
	Kind EventKind

	// Click fields.
	X, Y int // physical-pixel screen coordinates of the click
	// AutomationID is the developer-assigned id of the clicked element, when the
	// application sets one. It is the top rung of the selector ladder: unlike the
	// accessible name it survives translation.
	AutomationID string
	Name         string // resolved accessible name of the clicked element ("" if none)
	ControlType  string // e.g. Button, Edit, ListItem
	Button       string // left | right | middle (default left)
	Double       bool   // a double-click
	// Facts is what the element could do and held at capture time. Empty when the
	// tree reported nothing, in which case inference falls back to the control type.
	Facts ElementFacts

	// Char fields.
	Char rune // the typed rune
	// Secure marks a keystroke into a password-class field. Secure runs are
	// redacted: their characters are never written to the journey. This is the
	// recorder's one security-critical signal, pinned by a never-contains-secret test.
	Secure bool

	// Key fields.
	Key string // the named key: "Enter", "Tab", "Escape", "Backspace", …
}

type EventKind string

type Journey struct {
	Version     int    `json:"version"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Steps       []Step `json:"steps"`
	// ExpectedEvidence lists evidence labels the journey is expected to produce, so
	// a reviewer can state up front what artifacts a passing run must contain. Every
	// entry must be captured by some step, or the expectation can never be met — and
	// a run that does not actually capture one fails, even if every assertion passed.
	ExpectedEvidence []string `json:"expected_evidence,omitempty"`
}

type NameMatch string

type Occurrence struct {
	Mode  OccurrenceMode
	Index int
}

type OccurrenceMode string

type Operator string

type Origin struct {
	// StepIndex is the journey step this came from, or -1 for a step that belongs
	// to no journey step.
	StepIndex int
	Kind      OriginKind
	// Index is the position among the step's assertions or captures.
	Index int

	Verb     Verb
	Selector *Selector

	Subject  Subject
	Operator Operator
	Expected any
	Message  string
	Wait     *Wait

	Label string
}

type OriginKind string

type Scope string

type Selector struct {
	AutomationID string `json:"automation_id,omitempty"`
	Name         string `json:"name,omitempty"`
	ControlType  string `json:"control_type,omitempty"`
	// NameMatch qualifies Name and belongs only with it. Empty means MatchExact.
	NameMatch NameMatch `json:"name_match,omitempty"`
	// Occurrence decides what happens when the selector matches more than one
	// element. Empty means OccurrenceUnique, under which ambiguity is a failure.
	//
	// omitzero, not omitempty: omitempty has no effect on a struct field, so the
	// zero value would be written out as an occurrence of "" and fail to parse back
	// — which is exactly what a recorded journey does on its round trip to disk.
	Occurrence Occurrence `json:"occurrence,omitzero"`
	// Point is a coordinate target: legal, because a recorder must be able to
	// capture a control with no name, and marked non-durable wherever it appears.
	Point []int `json:"point,omitempty"`
	// Scope is how wide the search is. Empty means ScopeForeground.
	Scope Scope `json:"scope,omitempty"`
}

type Step struct {
	Name string `json:"name,omitempty"`
	Verb Verb   `json:"verb"`

	// Target selects the element or window the verb acts on.
	Target *Selector `json:"target,omitempty"`

	App        string  `json:"app,omitempty"`        // open_app
	Window     string  `json:"window,omitempty"`     // focus_window, resize_window, close_window
	URL        string  `json:"url,omitempty"`        // navigate
	Value      string  `json:"value,omitempty"`      // set_value
	Text       string  `json:"text,omitempty"`       // type_text
	Keys       string  `json:"keys,omitempty"`       // press_keys
	Credential string  `json:"credential,omitempty"` // enter_credential
	Label      string  `json:"label,omitempty"`      // capture
	Direction  string  `json:"direction,omitempty"`  // scroll
	Amount     int     `json:"amount,omitempty"`     // scroll
	Seconds    float64 `json:"seconds,omitempty"`    // pause
	Submit     bool    `json:"submit,omitempty"`     // type_text, enter_credential
	Scope      Scope   `json:"scope,omitempty"`      // observe
	Position   []int   `json:"position,omitempty"`   // resize_window
	Size       []int   `json:"size,omitempty"`       // resize_window

	// Assertions lists conditions checked after the action; a failed one fails the
	// step. Named to match the plural-noun convention every other array field uses.
	Assertions []Assertion `json:"assertions,omitempty"`
	// Evidence lists captions for evidence to capture after the action.
	Evidence []string `json:"evidence,omitempty"`
}

type Subject string

type ValueType string

type Verb string

type Wait struct {
	// Timeout is the budget in seconds. Zero takes DefaultWaitTimeout.
	Timeout float64 `json:"timeout,omitempty"`
	// Interval is the poll period in seconds. Zero takes DefaultWaitInterval.
	Interval float64 `json:"interval,omitempty"`
}