Skip to content

[DRAFT_NOT_POSTED_TO_ORIGIN] RFC: optional Tern semantic engine for native terminal/TUI e2e #8

Open

Description

@kvnloo

Downstream issue for upstream discussion; not posted to tester-army/e2e. On PR #974, @okwasniewski requested an issue-first agreement about engine scope, who maintains it and how CI can actually run it. The earlier draft PR is closed, not merged; this RFC seeks that agreement rather than treating implementation as accepted.

Motivation

e2e supports web/mobile surfaces, but terminal-native and TUI apps need a semantic engine that can locate actual UI controls, operate them and assert rendered state, rather than relying on text heuristics or screenshots. Tern offers structured accessibility/tree/control surfaces that may support that model.

Proposed boundary (requesting feedback)

  • Optional external engine/package @e2e-dev/tern, integrated via existing defineEngine/e2e locator and action vocabulary. No new test-runner-specific verbs; keep native-only code outside core.
  • Observe fresh Tern accessibility/tree/state per operation; preserve stable IDs and report duplicate/ambiguous locators rather than guess.
  • Explicit session provider and attempt-scoped ownership: distinguish leased/fresh sessions from borrowed/read-only sessions, avoid controlling any unrelated human pane or focus.
  • Gate all native actions on known supported vendor readiness and the exact owned/focused window. Stop on missing, active, signed-out or unknown gates; never bypass licensing or conceal native errors via screenshot/plain-text fallbacks.
  • Protect password/secure values, timeouts and cancellation; do not silently retry uncertain dispatched input. Assert actual rendered state rather than treating an input-delivery receipt as test success.
  • No CODEOWNERS, mandatory CI or release-workflow changes without maintainer agreement on supported runtime and ownership.

Example shape (API illustrative, not final):

targets: [{
  name: 'terminal',
  engine: ternEngine({ provider: attachedTern({ pane, control, mode: 'native' }) }),
}]

Explicitly separate: Sway isolated seat RFC #10 and Hyprland owned-output RFC #11. Neither is required to decide whether an optional Tern engine belongs in e2e. The virtual-desktop testing skill #9 is guidance, not an engine.

Proposed maintainer arrangement

@kvnloo volunteers to own initial Tern adapter code, docs, compatibility updates, issue triage and native regression fixes. This does not imply upstream maintainers have agreed to own it or can review/run it. Could this be a community-owned optional engine or even an independently distributed adapter first? Who would review changes, and what support lifecycle would be acceptable?

CI plan and blockers

  1. Always runnable: semantic-tree, locator, secure-field, deadline, cancellation and session-ownership unit tests using inert deterministic fixtures; package build/typecheck and consumer contract tests on the normal Linux runner.
  2. Real native Linux: run a disposable inert Tern SDK app and verify rendered text, edit/clear, click state, ambiguity, secure-value omission, input receipts vs visible effects and teardown on a pinned supported runtime.
  3. Required prerequisite: legally distributable vendor-supported Tern runtime and supported signed-in isolated test context, version pin/hash, clear maintainers for runner upkeep. The historical 0.6.1-beta native run later showed a sign-in gate; complete real native acceptance was not established in closed PR #974. No personal profiles, account automation, copied credentials or privately distributed binaries.
  4. Fail honestly: if runtime/access prerequisites are unavailable, native CI is blocked, not green; keep the integration out of required upstream checks or out-of-tree pending an agreed path. Do not add a mandatory failing workflow or alter CODEOWNERS now.

Minimum acceptance before another upstream PR

  • Maintainer-approved scope/ownership/distribution model and compatible CI runner.
  • Isolated native fixture proves effects on rendered values and input on the exact supported Tern version, including refusal/fail-closed cases.
  • Narrow diff separated from Sway/Hyprland isolation and unrelated workflows.

Prior work / provenance

Questions for maintainers

Would an opt-in semantic Tern engine fit e2e's roadmap? Is independent packaging preferred? What executable, version, licensing and signed-in test environment would make real CI sustainable, and who could own that runner?

Activity

  1. changed the title [-][DRAFT_NOT_POSTED_TO_ORIGIN] Tern desktop/TUI engine[/-] [+][DRAFT_NOT_POSTED_TO_ORIGIN] RFC: optional Tern semantic engine for native terminal/TUI e2e[/+] on Oct 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions