model

type BasicAuth ¶

type BasicAuth struct {
	Username Expression
	Password Expression
}

BasicAuth holds HTTP Basic Authentication expressions.

type BrowserAction ¶

type BrowserAction struct {
	Kind     BrowserActionKind
	File     string
	Line     int
	Selector Expression
	Value    Expression
	URL      Expression
	Key      Expression
	Secure   Expression
	Timeout  Expression
	Interval Expression
	X        Expression
	Y        Expression
}

BrowserAction is one ordered browser action inside an actions block.

type BrowserActionKind ¶

type BrowserActionKind string

BrowserActionKind identifies the kind of UI action performed inside a browser step.

const (
	// BrowserActionGoto navigates to a URL.
	BrowserActionGoto BrowserActionKind = "goto"
	// BrowserActionClick clicks an element identified by a CSS selector.
	BrowserActionClick BrowserActionKind = "click"
	// BrowserActionFill types text into a form field after clearing it.
	BrowserActionFill BrowserActionKind = "fill"
	// BrowserActionClear erases the current value of a form field.
	BrowserActionClear BrowserActionKind = "clear"
	// BrowserActionPress presses a keyboard key, optionally on an element.
	BrowserActionPress BrowserActionKind = "press"
	// BrowserActionSubmit submits a form element.
	BrowserActionSubmit BrowserActionKind = "submit"
	// BrowserActionScroll scrolls the page (selector or offset variant).
	BrowserActionScroll BrowserActionKind = "scroll"
	// BrowserActionWaitVisible waits until a selector becomes visible.
	BrowserActionWaitVisible BrowserActionKind = "wait_visible"
	// BrowserActionWaitNotVisible waits until a selector is missing or hidden.
	BrowserActionWaitNotVisible BrowserActionKind = "wait_not_visible"
	// BrowserActionHover hovers the mouse over an element.
	BrowserActionHover BrowserActionKind = "hover"
	// BrowserActionSelect selects an option in a <select> element by value.
	BrowserActionSelect BrowserActionKind = "select"
	// BrowserActionCheck checks a checkbox / radio input.
	BrowserActionCheck BrowserActionKind = "check"
	// BrowserActionUncheck unchecks a checkbox / radio input.
	BrowserActionUncheck BrowserActionKind = "uncheck"
	// BrowserActionReload reloads the current page.
	BrowserActionReload BrowserActionKind = "reload"
	// BrowserActionBack navigates back in the session history.
	BrowserActionBack BrowserActionKind = "back"
	// BrowserActionForward navigates forward in the session history.
	BrowserActionForward BrowserActionKind = "forward"
)

type BrowserAttributeExpectation ¶

type BrowserAttributeExpectation struct {
	Selector Expression
	Name     Expression
	Expected Expression
	Timeout  Expression
	Interval Expression
}

BrowserAttributeExpectation matches a DOM attribute value.

type BrowserExpect ¶

type BrowserExpect struct {
	Visible    []BrowserVisibility
	NotVisible []BrowserVisibility
	Text       []BrowserValueExpectation
	Value      []BrowserValueExpectation
	Enabled    []BrowserStateExpectation
	Disabled   []BrowserStateExpectation
	Attribute  []BrowserAttributeExpectation
	URL        []BrowserURLExpectation
	Title      []BrowserTitleExpectation
	WebPerf    []BrowserWebPerfExpectation
}

BrowserExpect groups assertions for a browser step. Each slice may be empty.

type BrowserStateExpectation ¶

type BrowserStateExpectation struct {
	Selector Expression
	Timeout  Expression
	Interval Expression
}

BrowserStateExpectation asserts enabled / disabled state for an element.

type BrowserStep ¶

type BrowserStep struct {
	Target  Expression
	Actions []BrowserAction
	Expect  BrowserExpect
}

BrowserStep is the provider-specific payload attached to a Step when Provider == "browser".

func (b *BrowserStep) HasContent() bool

type BrowserTitleExpectation ¶

type BrowserTitleExpectation struct {
	Expected Expression
	Timeout  Expression
	Interval Expression
}

BrowserTitleExpectation matches the document title against a literal or matcher.

type BrowserURLExpectation ¶

type BrowserURLExpectation struct {
	Expected Expression
	Timeout  Expression
	Interval Expression
}

BrowserURLExpectation matches the document URL against a literal or matcher.

type BrowserValueExpectation ¶

type BrowserValueExpectation struct {
	Selector Expression
	Expected Expression
	Timeout  Expression
	Interval Expression
}

BrowserValueExpectation matches an element's text content or input value against an expected value or matcher.

type BrowserVisibility ¶

type BrowserVisibility struct {
	Selector Expression
	Timeout  Expression
	Interval Expression
}

BrowserVisibility is one element visibility expectation with optional polling timeout.

type BrowserWebPerfExpectation ¶

type BrowserWebPerfExpectation struct {
	Metric   string
	Expected Expression
}

BrowserWebPerfExpectation asserts a single web performance metric against an expected value (literal number / duration string or matcher object). Metric is the canonical snake_case name from the driver.PerformanceMetrics layer ("fcp_ms", "lcp_ms", "cls", …); surface aliases are resolved by the parser before this struct is built.

type ExecCall ¶

type ExecCall struct {
	Command Expression
	Args    Expression
	Env     Expression
	Stdin   Expression
	Timeout Expression
	Sandbox *ExecSandbox
	Expect  *ExecExpect
}

ExecCall holds parsed data for an exec provider step. Command is required; the rest are optional. Tales calls the executable directly with Args — it never interprets a shell, so command = "bash" args = ["script.sh"] runs bash, but command = "bash -c ..." is treated as a literal program name.

type ExecExpect ¶

type ExecExpect struct {
	ExitCode   Expression
	Stdout     Expression
	Stderr     Expression
	StdoutJSON Expression
}

ExecExpect holds the exec provider assertions. exit_code matches the process exit status; stdout / stderr match the captured streams (matchers welcome); stdout_json matches the parsed stdout JSON object.

type ExecSandbox ¶

type ExecSandbox struct {
	Mode    Expression
	Workdir Expression
	Env     Expression
	Network Expression
}

ExecSandbox holds the optional sandbox block. In V1 mode "process" is a soft sandbox (working directory, environment, timeout, output capture) and is NOT a security boundary; mode "docker" is reserved but not implemented.

type Expect ¶

type Expect struct {
	Status    Expression
	Headers   Expression
	JSON      Expression
	Body      Expression
	Strict    Expression
	Shortcuts []ExpectShortcut
}

Expect holds provider-agnostic assertions.

type ExpectShortcut ¶

type ExpectShortcut struct {
	Name     string
	Expected Expression
}

ExpectShortcut is a flat `key = matcher_or_value` assertion. The runtime resolves Name against the provider's Response map and runs MatchJSON. Load steps populate this with metric names like p95 or status_2xx_ratio so users can write the friendly form documented in the provider reference.

type Expression ¶

type Expression struct {
	Expr hcl.Expression
	File string
	Line int
}

Expression wraps HCL expression with source metadata.

func (e Expression) Empty() bool

type FileCall ¶

type FileCall struct {
	Path   Expression
	Expect *FileExpect
}

FileCall holds parsed data for a file provider step. Path is the file to inspect (resolved against scenario.workdir, or under project.dir when given as ${project.dir}/...). Expect holds the optional assertions.

type FileExpect ¶

type FileExpect struct {
	Exists    Expression
	SizeBytes Expression
	Text      Expression
	JSON      Expression
	Hashes    map[string]Expression
}

FileExpect holds the file provider assertions. Each field is optional; only the set ones run. Hashes maps an algorithm name (sha1, sha224, sha256, sha384, sha512, sha512_224, sha512_256) to its expected digest expression.

type Generator ¶

type Generator struct {
	Type   string
	Name   string
	File   string
	Params map[string]Expression
}

Generator declaration from DSL.

type Keyword ¶

type Keyword struct {
	Name    string
	File    string
	Inputs  map[string]Expression
	Steps   []*Step
	Outputs map[string]Expression
}

Keyword is parsed and validated, runtime support is intentionally minimal for now.

type KeywordCall ¶

type KeywordCall struct {
	Name   Expression
	Inputs Expression
}

KeywordCall is data for a keyword provider step.

type LoadCall ¶

type LoadCall struct {
	Request *Request
	Run     *LoadRun
}

LoadCall is the parsed payload of a load step. The HTTP request to replay is captured in Request (reuses the standard HTTP Request shape minus multipart, which the load provider rejects). Run carries the execution-mode parameters (duration / requests, concurrency, rate, warmup).

type LoadRun ¶

type LoadRun struct {
	Duration    Expression
	Requests    Expression
	Concurrency Expression
	Rate        Expression
	Warmup      Expression
}

LoadRun describes how the load runner should drive the request. Exactly one of Duration / Requests is set after decoding. Concurrency defaults to 1 when absent; Rate (RPS limit) and Warmup stay zero / Empty when not provided.

type MailAttachment ¶

type MailAttachment struct {
	Filename    Expression
	ContentType Expression
	Path        Expression
	Content     Expression
}

MailAttachment is one attachment block. Exactly one of Path / Content is set (enforced at parse time); Filename is required; ContentType is optional and inferred from the filename when omitted.

type MailCall ¶

type MailCall struct {
	Target  Expression
	Message *MailMessage
}

MailCall holds parsed data for a mail provider step. It mirrors the lazy, expression-bearing shape of SQLCall: every field is an unevaluated Expression resolved by the runtime before the provider runs.

type MailMessage ¶

type MailMessage struct {
	From    Expression
	To      Expression // list(string)
	Cc      Expression // list(string)
	Bcc     Expression // list(string)
	Subject Expression
	Headers Expression // map(string)
	Text    Expression
	HTML    Expression

	Attachments []MailAttachment
}

MailMessage is the message block of a mail step. From and the recipient lists drive the envelope; Headers carries arbitrary custom headers; Text and HTML select the MIME body shape; Attachments preserve declaration order.

type MobileAction ¶

type MobileAction struct {
	Kind MobileActionKind
	File string
	Line int
	ID   Expression
	// Label locates the element by accessibilityLabel instead of
	// accessibilityIdentifier. Mutually exclusive with ID; parser
	// enforces XOR. Reserved for iOS system controllers whose buttons
	// expose a label but leave the identifier empty
	// (PHPickerViewController, document picker, share sheet, ...).
	Label    Expression
	Value    Expression
	Secure   Expression
	Timeout  Expression
	Interval Expression
	// Direction is "up" / "down" / "left" / "right" for swipe and scroll.
	Direction Expression
	// Distance is the swipe/scroll travel as a fraction (0,1] of the
	// target element's relevant dimension. Optional; defaults applied
	// by the runtime.
	Distance Expression
	// Duration is the gesture duration for swipe / scroll / long_press.
	Duration Expression
	// First requests pre-order first-match resolution for the action's
	// element id, mirroring XCUITest's firstMatch. When true, sibling
	// elements that share the id no longer error with ErrDuplicate; the
	// first match in DFS order is used. Only consulted by actions that
	// resolve an element by id; the strict default is preserved when the
	// expression is unset or evaluates to false.
	First Expression
}

MobileAction is one ordered UI action inside an actions block.

type MobileActionKind ¶

type MobileActionKind string

MobileActionKind identifies the kind of UI action performed inside a mobile step.

const (
	// MobileActionTap taps an element identified by accessibility ID.
	MobileActionTap MobileActionKind = "tap"
	// MobileActionInputText types text into an element identified by accessibility ID.
	MobileActionInputText MobileActionKind = "input_text"
	// MobileActionClearText erases the current value of an element identified by accessibility ID.
	MobileActionClearText MobileActionKind = "clear_text"
	// MobileActionWaitVisible waits until an element exists and is visible.
	MobileActionWaitVisible MobileActionKind = "wait_visible"
	// MobileActionWaitNotVisible waits until an element is missing or not visible.
	MobileActionWaitNotVisible MobileActionKind = "wait_not_visible"
	// MobileActionSwipe drags one finger across an element in a direction.
	MobileActionSwipe MobileActionKind = "swipe"
	// MobileActionScroll scrolls an element's content in a direction.
	MobileActionScroll MobileActionKind = "scroll"
	// MobileActionLongPress presses and holds an element for a duration.
	MobileActionLongPress MobileActionKind = "long_press"
	// MobileActionDoubleTap taps an element twice in quick succession.
	MobileActionDoubleTap MobileActionKind = "double_tap"
	// MobileActionPressKey presses a hardware keyboard key (return, tab…).
	MobileActionPressKey MobileActionKind = "press_key"
	// MobileActionPressButton presses a device button (home, lock).
	MobileActionPressButton MobileActionKind = "press_button"
	// MobileActionSetOrientation changes the device orientation.
	MobileActionSetOrientation MobileActionKind = "set_orientation"
	// MobileActionDismissKeyboard tells the driver to dismiss the soft
	// keyboard if one is up. Idempotent: a no-op when no keyboard is
	// present. Useful before a /hierarchy snapshot on screens whose
	// keyboard subtree makes the full-application snapshot exceed the
	// driver's bounded timeout.
	MobileActionDismissKeyboard MobileActionKind = "dismiss_keyboard"
	// MobileActionScrollTo asks the driver to scroll the element
	// identified by id or label into the viewport. Idempotent (no-op
	// when the element is already in the safe area). Indispensable
	// before an input_text on a tall SwiftUI Form where the target
	// field is offscreen: the focus tap would otherwise miss, the
	// follow-up synth path would trip an XCTest API violation and tear
	// the runner down.
	MobileActionScrollTo MobileActionKind = "scroll_to"
)

type MobileExpect ¶

type MobileExpect struct {
	Visible    []MobileVisibility
	NotVisible []MobileVisibility
	Text       []MobileValueExpectation
	Value      []MobileValueExpectation
	Enabled    []MobileStateExpectation
	Disabled   []MobileStateExpectation
}

MobileExpect groups visibility expectations for a mobile step.

type MobileLaunch ¶

type MobileLaunch struct {
	ClearState Expression
}

MobileLaunch describes the optional launch block of a mobile step.

type MobilePermission ¶

type MobilePermission struct {
	Service  string
	Decision Expression
	File     string
	Line     int
}

MobilePermission is one privacy permission declared in a step's `permissions` block. Service is a simctl privacy service name (camera, photos, location, …); Decision evaluates to "allow" or "deny".

type MobileStateExpectation ¶

type MobileStateExpectation struct {
	ID       Expression
	Label    Expression
	Timeout  Expression
	Interval Expression
}

MobileStateExpectation checks enabled / disabled state for an element.

type MobileStep ¶

type MobileStep struct {
	Platform    Expression
	Target      Expression
	Launch      *MobileLaunch
	Terminate   *MobileTerminate
	Actions     []MobileAction
	Permissions []MobilePermission
	Expect      MobileExpect
}

MobileStep is the provider-specific payload attached to a Step when Provider == "mobile".

func (m *MobileStep) HasContent() bool

type MobileTerminate ¶

type MobileTerminate struct{}

MobileTerminate is the marker block requesting application termination.

type MobileValueExpectation ¶

type MobileValueExpectation struct {
	ID       Expression
	Label    Expression
	Expected Expression
	Timeout  Expression
	Interval Expression
}

MobileValueExpectation compares text/value content for an element.

type MobileVisibility ¶

type MobileVisibility struct {
	ID       Expression
	Label    Expression
	Timeout  Expression
	Interval Expression
}

MobileVisibility describes one element visibility expectation with optional polling timeout.

type MultipartBody ¶

type MultipartBody struct {
	Parts []MultipartPart
}

MultipartBody is a multipart/form-data payload. Parts preserve the declaration order from the .tales file so the wire representation is deterministic regardless of map iteration.

type MultipartFieldPart ¶

type MultipartFieldPart struct {
	Name  Expression
	Value Expression
}

MultipartFieldPart describes a non-file form field.

type MultipartFilePart ¶

type MultipartFilePart struct {
	Field       Expression
	Path        Expression
	Content     Expression
	Filename    Expression
	ContentType Expression
}

MultipartFilePart describes one file part. Field is the form name on the wire. Exactly one of Path / Content provides the payload bytes — Path is resolved at execution time relative to the .tales file, Content is evaluated as a string expression. Filename and ContentType are optional; when omitted, the provider derives them from Path / sniffs the content.

type MultipartPart ¶

type MultipartPart struct {
	File  *MultipartFilePart
	Field *MultipartFieldPart
}

MultipartPart is one part in a multipart body. Exactly one of File / Field is set; the runtime serializes each part via mime/multipart.

type Request ¶

type Request struct {
	Method  Expression
	URL     Expression
	Headers Expression
	Query   Expression
	Body    *RequestBody
	Timeout Expression
	Auth    *RequestAuth
}

Request holds provider-agnostic request inputs.

type RequestAuth ¶

type RequestAuth struct {
	Basic *BasicAuth
}

RequestAuth holds authentication configuration for a request.

type RequestBody ¶

type RequestBody struct {
	JSON      Expression
	Form      Expression
	Raw       Expression
	Multipart *MultipartBody
}

RequestBody holds one HTTP request body representation.

type Retry ¶

type Retry struct {
	Attempts int
	Interval time.Duration
}

Retry controls repeated execution of a step until it passes.

type SQLCall ¶

type SQLCall struct {
	Connection Expression
	Exec       *SQLOp
	Query      *SQLOp
}

SQLCall holds parsed data for a sql provider step.

type SQLOp ¶

type SQLOp struct {
	SQL  Expression
	Args Expression
}

SQLOp is one SQL operation (exec or query) declared by a sql step.

type SaveBlock ¶

type SaveBlock struct {
	Body Expression
}

SaveBlock persists part of an HTTP response to the scenario workspace. V1 supports body = "<path>", which writes the raw response body bytes; the path resolves under scenario.workdir. It is only valid on http steps.

type Scenario ¶

type Scenario struct {
	Name      string
	Tags      []string
	File      string
	Steps     []*Step
	Teardown  []*Step
	SkipRules []SkipRule
}

Scenario defines executable test flow.

type SkipKind ¶

type SkipKind string

SkipKind identifies how a skip rule is evaluated.

const (
	// SkipIf skips when the rule evaluates to true.
	SkipIf SkipKind = "skip_if"
	// SkipUnless skips when the rule does not evaluate to true.
	SkipUnless SkipKind = "skip_unless"
)

type SkipRule ¶

type SkipRule struct {
	Kind      SkipKind
	Condition Expression
	Reason    Expression
	OS        Expression
	Arch      Expression
	EnvSet    Expression
	Env       Expression
	Range     hcl.Range
}

SkipRule is one declarative skip directive attached to a scenario or step.

Attribute semantics inside a single rule are combined with AND: the rule "matches" only when every populated attribute is satisfied. For SkipIf, a matching rule triggers a skip; for SkipUnless, a non-matching rule triggers a skip. Multiple rules attached to the same element are evaluated in order and the first one that triggers wins.

func (r SkipRule) HasConditions() bool

type Step ¶

type Step struct {
	Provider  string
	Name      string
	File      string
	Line      int
	DependsOn []string
	When      Expression
	Vars      []StepVar
	Request   *Request
	Expect    *Expect
	Capture   map[string]Expression
	Save      *SaveBlock
	FileOp    *FileCall
	Exec      *ExecCall
	Keyword   *KeywordCall
	Mobile    *MobileStep
	SQL       *SQLCall
	Mail      *MailCall
	Browser   *BrowserStep
	Load      *LoadCall
	Webhook   *WebhookCall
	Retry     *Retry
	SkipRules []SkipRule
}

Step is one execution unit handled by a provider.

type StepVar ¶

type StepVar struct {
	Name string
	Expr Expression
}

StepVar is one step-local variable declared in a vars block. Vars are evaluated in declaration order before the provider runs and are scoped to the current step only — later vars and the request/expect/capture expressions can read them via vars.<name>.

type Suite ¶

type Suite struct {
	Version    int
	Files      []string
	ConfigExpr map[string]Expression
	Generators map[string]*Generator
	Keywords   map[string]*Keyword
	Scenarios  []*Scenario
}

Suite is the merged representation of one or more .tales files.

type WebhookCall ¶

type WebhookCall struct {
	Start  *WebhookStart
	Wait   *WebhookWait
	Stop   *WebhookStop
	Target Expression
	Expect *WebhookExpect
}

WebhookCall is the parsed payload of a webhook provider step. Exactly one of Start, Wait, or Stop is set (validated at decode time). Target is the step-level `target = ...` expression consumed by the wait operation; the stop operation carries its own target inside the Stop block.

type WebhookExpect ¶

type WebhookExpect struct {
	Request *WebhookRequestExpect
	HMAC    *WebhookHMACExpect
}

WebhookExpect holds the webhook-specific assertions evaluated by the runtime against the received request. Both blocks are optional.

type WebhookHMACExpect ¶

type WebhookHMACExpect struct {
	Header             Expression
	Secret             Expression
	Algorithm          Expression
	Format             Expression
	Payload            Expression
	TimestampTolerance Expression
	TimestampRequired  Expression
}

WebhookHMACExpect verifies a signature header on the received request. The signature material is parsed out of Header per Format (a literal pattern with {timestamp} / {signature} placeholders), the Payload expression is evaluated with a `timestamp` variable in scope, and an HMAC over it with Secret and Algorithm is compared in constant time against the parsed signature.

type WebhookRequestExpect ¶

type WebhookRequestExpect struct {
	Method  Expression
	Path    Expression
	Headers Expression
	Query   Expression
	JSON    Expression
	Body    Expression
}

WebhookRequestExpect asserts on the received request. Absent fields are not asserted; headers/query/json match partially (only declared keys).

type WebhookStart ¶

type WebhookStart struct {
	Address      Expression
	Path         Expression
	PublicURL    Expression
	PublicScheme Expression
	PublicHost   Expression
	PublicPort   Expression
	MaxBodySize  Expression
}

WebhookStart configures a temporary local HTTP receiver. Address binds the listener (default 127.0.0.1:0, a free port). Path is the route that records incoming requests. The Public* fields control how the externally reachable callback URL is built (see runtime/webhook.go buildWebhookURL).

type WebhookStop ¶

type WebhookStop struct {
	Target Expression
}

WebhookStop shuts down the receiver referenced by Target.

type WebhookWait ¶

type WebhookWait struct {
	Timeout Expression
	Count   Expression
}

WebhookWait blocks until at least Count requests have reached the receiver referenced by the step-level target, or Timeout elapses.