Files
sanderling/internal/driver/maestro/client.go
T
pj 7493945251 feat: LTL operators, sampling, and default generators (#17)
* feat(ltl): add Now/Next/Eventually/Implies/Or/And/Not formulas

Replace the fold-with-latch evaluator with a residual-formula reducer.
Each Observe() instantiates a fresh obligation from the root (stripping
an outer Always), reduces each pending obligation against current state,
latches Violated on first failure, and surfaces Pending verdicts for
deferred obligations. Existing Always/Pure/Thunk tests continue to pass.

* feat(ltl): support relative duration for eventually().within()

* feat(proto): add Swipe, PressKey, RecentLogs RPCs

* feat(verifier,runner): formula handles, new action kinds, rich state

- verifier: add formula-spec registry; bindNow/bindNext/bindEventually with
  chainable .implies/.or/.and/.not and .within(n,unit) on eventually; bindFrom
  for uniform sampling. bindAlways keeps accepting plain predicates.
- verifier: store lastTree, lastAction, step time, logs, exceptions on the
  Verifier; SnapshotInput replaces the (snapshots, tree) pair. stateObject now
  produces state.lastAction/time/logs/exceptions matching the TS State type.
- verifier: make taps/swipes/waitOnce/pressKey built-in generators actually
  fire; taps picks a clickable, enabled element from the last hierarchy.
- agent: add exceptions field to Message wire format.
- driver: add Swipe/PressKey/RecentLogs to Driver interface; wire maestro
  client and mock driver. LogEntry exposed for runner consumption.
- runner: apply Swipe/PressKey/Wait actions; collect logcat and exceptions;
  pass lastAction and step time into PushSnapshot.

* feat(spec-api): LTL operators, new actions, richer State

- ltl.ts exports now/next/eventually; always overload accepts a Formula
- types.ts: Formula gains implies/or/and/not; EventuallyFormula adds .within;
  State gains lastAction/time/logs/exceptions; Swipe/PressKey/Wait action types
- actions.ts: Swipe/PressKey/Wait/from constructors; waitOnce + pressKey
  default generators
- tests exercise the chaining, sampling, and new actions through a recorded
  fake runtime

* feat(sidecar): add swipe, pressKey, recentLogs RPC handlers

* feat(sdk-android): capture uncaught exceptions

Install a default uncaught handler on Uatu.start, chained with any
existing handler so Android's crash reporter still runs. Expose
Uatu.reportError for callers to forward caught throwables. A bounded
circular buffer (default 50) drains into each STATE message's new
exceptions field. Protocol.kt serializes/deserializes the field,
matching the Go wire format added to internal/agent/protocol.go.

* feat(spec-api): add @uatu/spec/defaults/properties bundle

* feat(sample-app): exercise new LTL operators + defaults

spec.ts now imports eventually/next/now/from from @uatu/spec and
noUncaughtExceptions from @uatu/spec/defaults/properties. It declares
three properties that exercise the new surface:

- accountCountNonNegative: plain always() safety
- addAccountAdvances: always(now(x).implies(next(y)))
- eventuallyLoggedIn: eventually(p).within(30, "seconds")
- noUncaughtExceptions: imported default

The weighted actions root uses from() for random phone/name sampling
and entries for taps/swipes/waitOnce/pressKey built-ins.

SampleApplication gains a debug hook gated on the system property
uatu.inject_error so the e2e run can synthesize an Uatu.reportError and
verify noUncaughtExceptions violates.

cmd/uatu/test_run.go adds a subpath alias so specs importing
"@uatu/spec/defaults/properties" resolve against the in-tree source
when running from the uatu checkout. The spec-integration tests swap
the old click-counter fixtures for the new login hierarchy.

* feat(trace): record swipe/key/wait details + exceptions

trace.Step gains an Exceptions array so the trace captures the
class/message/stackTrace for each SDK-reported throwable in a step.
trace.Action gains FromX/FromY/ToX/ToY/Key/DurationMillis so the full
payload of Swipe/PressKey/Wait actions is visible in trace.jsonl.

sample-app's debug error hook now gates on ApplicationInfo.DEBUGGABLE
instead of a system property (adb setprop fails on non-rooted
emulators).
2026-04-20 02:19:39 +07:00

157 lines
4.3 KiB
Go

package maestro
import (
"context"
"fmt"
"time"
"google.golang.org/grpc"
"google.golang.org/grpc/credentials/insecure"
"github.com/priyanshujain/uatu/internal/driver"
driverpb "github.com/priyanshujain/uatu/proto/driverpb"
)
type Client struct {
connection *grpc.ClientConn
stub driverpb.DriverClient
}
// Dial connects to the sidecar gRPC server at the given address.
// Address must be a host:port pair, typically "127.0.0.1:<sidecar-port>".
func Dial(address string) (*Client, error) {
connection, err := grpc.NewClient(address, grpc.WithTransportCredentials(insecure.NewCredentials()))
if err != nil {
return nil, fmt.Errorf("dial sidecar: %w", err)
}
return &Client{connection: connection, stub: driverpb.NewDriverClient(connection)}, nil
}
func (c *Client) Close() error { return c.connection.Close() }
// WaitForHealth polls the sidecar's Health RPC until it returns Ready=true
// or the context is canceled.
func (c *Client) WaitForHealth(ctx context.Context, pollInterval time.Duration) error {
if pollInterval <= 0 {
pollInterval = 100 * time.Millisecond
}
for {
response, err := c.stub.Health(ctx, &driverpb.Empty{})
if err == nil && response.GetReady() {
return nil
}
select {
case <-ctx.Done():
return ctx.Err()
case <-time.After(pollInterval):
}
}
}
func (c *Client) Launch(ctx context.Context, bundleID, launcherActivity string, clearState bool) error {
_, err := c.stub.Launch(ctx, &driverpb.LaunchRequest{
BundleId: bundleID,
ClearState: clearState,
LauncherActivity: launcherActivity,
})
return err
}
func (c *Client) Terminate(ctx context.Context) error {
_, err := c.stub.Terminate(ctx, &driverpb.Empty{})
return err
}
func (c *Client) Tap(ctx context.Context, x, y int) error {
_, err := c.stub.Tap(ctx, &driverpb.Point{X: int32(x), Y: int32(y)})
return err
}
func (c *Client) TapSelector(ctx context.Context, selector string) error {
_, err := c.stub.TapSelector(ctx, &driverpb.Selector{Value: selector})
return err
}
func (c *Client) InputText(ctx context.Context, text string) error {
_, err := c.stub.InputText(ctx, &driverpb.Text{Value: text})
return err
}
func (c *Client) Swipe(ctx context.Context, fromX, fromY, toX, toY int, duration time.Duration) error {
_, err := c.stub.Swipe(ctx, &driverpb.SwipeRequest{
From: &driverpb.Point{X: int32(fromX), Y: int32(fromY)},
To: &driverpb.Point{X: int32(toX), Y: int32(toY)},
DurationMillis: duration.Milliseconds(),
})
return err
}
func (c *Client) PressKey(ctx context.Context, key string) error {
_, err := c.stub.PressKey(ctx, &driverpb.PressKeyRequest{Key: key})
return err
}
func (c *Client) RecentLogs(ctx context.Context, since time.Time, minLevel string) ([]driver.LogEntry, error) {
sinceMillis := int64(0)
if !since.IsZero() {
sinceMillis = since.UnixMilli()
}
response, err := c.stub.RecentLogs(ctx, &driverpb.RecentLogsRequest{
SinceUnixMillis: sinceMillis,
LevelAtLeast: minLevel,
})
if err != nil {
return nil, err
}
entries := response.GetEntries()
result := make([]driver.LogEntry, 0, len(entries))
for _, entry := range entries {
result = append(result, driver.LogEntry{
UnixMillis: entry.GetUnixMillis(),
Level: entry.GetLevel(),
Tag: entry.GetTag(),
Message: entry.GetMessage(),
})
}
return result, nil
}
func (c *Client) Hierarchy(ctx context.Context) (string, error) {
response, err := c.stub.Hierarchy(ctx, &driverpb.Empty{})
if err != nil {
return "", err
}
return response.GetJson(), nil
}
func (c *Client) Screenshot(ctx context.Context) (driver.Image, error) {
response, err := c.stub.Screenshot(ctx, &driverpb.Empty{})
if err != nil {
return driver.Image{}, err
}
return driver.Image{
PNG: response.GetPng(),
Width: int(response.GetWidth()),
Height: int(response.GetHeight()),
}, nil
}
func (c *Client) WaitForIdle(ctx context.Context, duration time.Duration) error {
_, err := c.stub.WaitForIdle(ctx, &driverpb.Duration{Millis: duration.Milliseconds()})
return err
}
func (c *Client) Health(ctx context.Context) (driver.Health, error) {
response, err := c.stub.Health(ctx, &driverpb.Empty{})
if err != nil {
return driver.Health{}, err
}
return driver.Health{
Ready: response.GetReady(),
Version: response.GetVersion(),
Platform: response.GetPlatform(),
}, nil
}
var _ driver.Driver = (*Client)(nil)