e2e

package
v0.0.5 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: Apache-2.0 Imports: 3 Imported by: 0

README

Starlark E2E harness

The harness executes .star scenarios against a real Go application, Sable transport and native GPUI renderer. It consumes the public uitest package for input, application driving, event barriers, lifecycle cleanup, suite deadlines and worker reports. Starlark evaluation, builtins, source diagnostics and value conversion live in uitest/starlark; the old e2e Go package forwards its public API. uitest/gpui owns native driving and Application/Factory. Fixtures and presentation live in examples/e2eapp and examples/reactiveapp; runner factories adapt their application types without a harness dependency in those applications.

Commands

Run from the repository root with the normal pinned toolchains and native graphical prerequisites:

make e2e-check       # parse AND resolve all scenarios; no native library/display
make build-e2e      # opt-in instrumented native archive and bin/gpui-e2e
make e2e            # build and run all passing scenarios
make e2e-no-display # Linux without a display; all but clipboard, which that platform lacks
./bin/gpui-e2e --timeout 45s e2e/scenarios/text-input.star
make e2e E2E_SCENARIOS='e2e/scenarios/controls.star e2e/scenarios/composition.star'
make test-e2e-native # GPUI unit tests with the instrumentation compiled
make uitest         # Go-only consumer of the same shared package

The Rust automation feature and Go gpui_e2e tag are independent opt-ins. Locally built native archives do not advertise test-automation-v1 and reject automation requests unless built through e2e-lib. Published prebuilt modules enable the feature, so they only need the Go tag. build-e2e preserves its archive as target/release/libgpui_go_e2e.a and forces a fresh Go link. Ordinary native targets rebuild without instrumentation. --check also works with go run ./cmd/gpui-e2e, without native tags.

The parent starts one native worker for the suite. Each file gets a deadline (30 seconds by default), an interpreter step budget and cleanup with an independent five-second deadline. Windows, handlers, models and clipboard text are cleaned up on success, assertion failure or cancellation. Shared uitest code supervises the worker and validates its atomic version-1 completion report before reporting success. This matters on macOS because AppKit may terminate the native process with status zero without returning from GPUI's application loop. Missing reports, malformed reports, assertions and crashes fail the suite. Reports remain under .agents-workspace/tmp/e2e-run-*/result.json.

Writing scenarios

Use the shared Page/Locator API for new scenarios:

page = open_page()
name = page.get_by_role("textbox", name = "Name", exact = True)
name.fill("Hello 日本語")
expect(name).to_have_value("Hello 日本語")
expect(name).to_be_focused()
page.get_by_role("button", name = "Increment native model").click()
expect(page.get_by_test_id("count")).to_have_text("Count: 1")
page.close()

page.locator(name) and get_by_test_id(name) use fixture selector names, while get_by_role and get_by_text query current native snapshot metadata. Locators are live and strict: an ambiguous action fails; .nth(index), .first and .last select explicitly. Actions include .click(), .fill(value), .press(key), .focus(), .hover(), .check() and .uncheck(). Getters include .count(), .input_value() and .inspect(). page.keyboard.press accepts GPUI or common Playwright key names; insert_text uses the focused native input handler.

expect(locator) supports to_have_text, to_have_value, to_have_count, to_be_visible, to_be_hidden, to_be_enabled, to_be_disabled, to_be_focused, to_be_checked and not_to_be_checked. Actions and expectations accept timeout_ms; page.set_default_timeout(ms) changes the five-second default. The shared Go core owns readiness checks, virtual-row reveal, assertion polling and timeout diagnostics. The Starlark adapter only unpacks arguments and returns values. See shared API semantics and limits.

page.state() and page.update(operation, value="") expose application fixture state/updates. The earlier free-function API below remains available for low-level input and composition scenarios.

open_page("reactive") opens the reactive component example. Its selectors include counter, name, greeting, details, and keyed item-1, item-2, etc. The fixture exposes counter/batch/toggle/reverse/add/remove operations and binding execution counts. to_have_text includes descendant text on containers; text queries match leaves, and input values remain separate.

Top-level for/if and reassignment are supported. Check and execution share their language options and builtin registry. Scripts are trusted repository test code; arbitrary shell/file APIs and Starlark module loading are not provided.

app = open_app("workbench")
click(app, "name")
type_text(app, "Hello 日本語")
assert_eq(state(app)["name"], "Hello 日本語")
key(app, "home shift-end")
assert_eq(inspect(app, "name")["selection"], [0, 9])
close_app(app)
Builtin Behavior
open_app(fixture="workbench") Open an independent application fixture and return its token
close_app(app) Release that application's window, handlers, model and subscription
click(app, element, x=None, y=None) Dispatch native pointer move/down/up; omitted coordinates use the clipped rendered center
mouse_down, mouse_up, mouse_move Dispatch individual pointer phases; pressed=True marks a drag move; explicit coordinates are window-relative
key(app, keystrokes) Dispatch space-separated native key strokes with key-up; chords use the real keymap
type_text(app, text) Insert a text payload through the currently focused platform input handler
compose(app, element, text, commit=False) Simulate native text-service composition/commit callbacks on the focused field
inspect(app, element="root") Read native revision, focus, clipped bounds, rendered status, text, and input state
state(app) Read the Go application's state after event dispatch settles
update(app, operation, value="") Invoke an explicit fixture operation, such as authoritative replacement or an unrelated snapshot commit
clipboard(text=None) Read/write real clipboard text, reserving its previous text for cleanup
assert_eq, assert_true, assert_contains, log Assertions with source backtraces and progress output

inspect reports UTF-16 selection and marked ranges; marked is None after commit. Input text_bounds is the actual text-layout rectangle, useful for mouse selection without assuming container padding. rendered=False identifies an offscreen virtual row; clicking a target without rendered bounds is an error. state is a Go-side observation; assert native input state or rendered text as well when a scenario needs to prove that Go and native entities agree.

The native target uses inspect barriers and published event watermarks to drain callbacks and their resulting view commits. It does not use arbitrary sleeps to guess when updates are visible. A maximum of 64 barriers catches applications that never settle.

The workbench exposes root, increment, count, name, mirror, reset, disabled, other, list, selected and row-0 through row-999. Its updates are replace (new input value), rerender, disable ("false" re-enables), and scroll_last. Other applications can implement their own factory and selectors without adding presentation or application state to the harness.

Scenarios and evidence limits

Scenario Observes
controls Native clicks/misses, keyboard activation, model observation, shortcut chords surviving commits
locators Shared Page/Locator/expect API, role/text/test-ID queries, fill/press, checkbox idempotence, current snapshots and automatic virtual-row reveal
reactive One template build, selective/batched bindings, memo equality, branch disposal, keyed input identity/focus/selection through reordering
GoX counter Generated counter view, native click/Enter activation, rendered/Go counts and stable count-node identity
text input Decomposed accents/emoji/Japanese, grapheme deletion, UTF-16 selection, Go epochs, mixed-control Tab navigation
composition Mark replacement, commit, Go echoes and authoritative resets through native composition callbacks
disabled input Disabled edits/click focus, skipped Tab stops and re-enabling
mouse selection Pointer drag selection through Unicode and selection deletion
clipboard Copy/cut/paste shortcuts, clipboard text and single-line normalization
virtual list Actual last-row prepaint after scrolling, native row click and retained scroll state
window isolation Independent inputs/models, closing one window, and reopening after the last close

The clipboard scenario changes the actual pasteboard and restores its previous text. It does not preserve rich clipboard formats. Use an explicit scenario list excluding clipboard.star if those formats must be retained.

These are synthetic GPUI inputs in a native graphical process. They exercise actual renderer/input/Go transport behavior, but do not inject OS events, drive an installed OS IME, validate screen-reader output or compare pixels. Composition is explicitly simulated. Native validation currently targets macOS/arm64; Linux/Windows runtime results remain unverified. The separate GPL Zed editor host retains its own smoke tests and is not linked by this runner.

The deliberately failing assertion control is excluded from the passing suite. Verify failure reporting, cleanup and process status with:

./bin/gpui-e2e e2e/testdata/assertion-fails.star e2e/scenarios/controls.star
# Expected: assertion traceback, controls PASS, final exit status 1.

The excluded strictness control similarly rejects an ambiguous textbox fill before mutating a field. Follow it with e2e/scenarios/locators.star to verify cleanup and continuation; the final status must be 1.

Cornus provenance

The structure follows Cornus's Starlark harness: scenario files, Go builtins, a replaceable target, matching check/run language options, per-file cleanup and explicit assertions. The inspected local Cornus revision was 6997fb55d23f209b5afec6afc74b1f3b14ebe7f4. This implementation is specific to GPUI and does not import Cornus or its infrastructure dependencies. Starlark is pinned independently in go.mod.

Documentation

Overview

Package e2e forwards the original Starlark harness API. Deprecated: import github.com/moriyoshi/gpui-go/uitest/starlark instead.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Check

func Check(path string) error

Types

type Harness

type Harness = starlarktest.Harness

func New

func New(target uitest.Target, out io.Writer) *Harness

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL