Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/tern-engine.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@e2e-dev/tern": minor
---

Add the Tern desktop/TUI engine, using Tern's structured control surface for semantic observation and standard e2e actions for input.
3 changes: 3 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,9 @@ suites that consume the built packages the way a user would.
The `@e2e-dev/mobile/tools` subpath holds the agent-side `open_app`, `swipe`,
and `alert` tools; focused-field typing uses the engine's keyboard grammar.
The main entry never loads the AI SDK.
- `packages/tern` — the published `@e2e-dev/tern` desktop/TUI engine. It
adapts Tern's control/TSP surfaces to the public `e2e/engine` contract,
keeping Tern-specific observation and input mechanics out of runner core.
- `packages/kernel` - the published `@e2e-dev/kernel` package: Kernel hosted
browsers for the web engine. An official integration with a hosted service
is one package per service, named after it (`@e2e-dev/<service>`), with the
Expand Down
5 changes: 3 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,7 @@ This project is a pnpm monorepo. `packages/` holds what publishes to npm,
- `packages/e2e`: the published `e2e` package (SDK, runner, CLI, engine contract)
- `packages/web`: the published `@e2e-dev/web` browser engine
- `packages/mobile`: the published `@e2e-dev/mobile` mobile engine
- `packages/tern`: the published `@e2e-dev/tern` desktop/TUI engine
- `packages/decision`: the decision-model executor on the public `StepExecutor` contract
- `apps/testbed`: private dogfood suite that consumes the built packages
- `apps/web-benchmark`: private Next.js app of hard-surface scenarios plus the e2e suites written against them
Expand Down Expand Up @@ -123,8 +124,8 @@ We use [changesets](https://github.com/changesets/changesets) to publish new
versions. It handles bumping the version based on semver, writing the
changelog, and creating tags and GitHub releases.

If your change affects `e2e`, `@e2e-dev/web`, `@e2e-dev/mobile`, or
`@e2e-dev/decision`, add a changeset:
If your change affects `e2e`, `@e2e-dev/web`, `@e2e-dev/mobile`,
`@e2e-dev/decision`, or `@e2e-dev/tern`, add a changeset:

```sh
pnpm changeset
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ Flutter, each a standalone project with a passing suite.
| [`e2e`](https://www.npmjs.com/package/e2e) | The SDK, runner, and CLI. |
| [`@e2e-dev/web`](https://www.npmjs.com/package/@e2e-dev/web) | Browser engine: Chromium, Firefox, and WebKit through Playwright. |
| [`@e2e-dev/mobile`](https://www.npmjs.com/package/@e2e-dev/mobile) | iOS and Android engine: simulators and emulators through agent-device. |
| [`@e2e-dev/tern`](https://www.npmjs.com/package/@e2e-dev/tern) | Desktop/TUI engine through Tern's structured control surface. |
| [`@e2e-dev/github`](https://www.npmjs.com/package/@e2e-dev/github) | Reporter that posts results as a pull request comment. |
| [`@e2e-dev/kernel`](https://www.npmjs.com/package/@e2e-dev/kernel) | Kernel hosted browsers for the web engine. |
| [`@e2e-dev/eas`](https://www.npmjs.com/package/@e2e-dev/eas) | EAS Simulators hosted iOS simulators and Android emulators for the mobile engine. |
Expand Down
1 change: 1 addition & 0 deletions docs/docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -143,6 +143,7 @@
"pages": [
"web",
"mobile",
"tern",
"api-testing"
]
},
Expand Down
43 changes: 43 additions & 0 deletions docs/tern.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
---
title: Tern
description: Test terminal and TUI surfaces through Tern's structured control plane.
icon: "terminal"
---

`ternEngine()` from `@e2e-dev/tern` connects e2e to a Tern pane through the
same public engine contract used by web and mobile.

It prefers Tern's structured control surface—accessibility nodes, element
geometry, pane state, and native input—so locators and agent actions operate on
current UI evidence instead of an opaque screenshot.

## Setup

```bash
pnpm add -D @e2e-dev/tern
```

```ts title="e2e.config.ts"
import type { E2EConfig } from 'e2e';
import { ternEngine } from '@e2e-dev/tern';

export default {
targets: [{
name: 'tui',
engine: ternEngine({ pane: process.env.TERN_PANE, control: process.env.TERN_CONTROL }),
app: {},
}],
} satisfies E2EConfig;
```

`control` defaults to `TERN_CONTROL` and then Tern's default control socket.
Without `pane`, the engine creates a fresh Tern tab for each attempt using
`command` and closes it during teardown.

With a reachable control socket it reads `state`, `a11y`, and `tree` and
maps them into e2e semantic nodes. If that surface is unavailable it falls back
to surface/scrollback capture; an optional TSP record can preserve tool-card
heads in that fallback.

Input stays on e2e's standard action vocabulary. No Tern-specific verbs are
added to runner core.
4 changes: 2 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
],
"type": "module",
"scripts": {
"build": "pnpm --filter e2e run build && pnpm --filter @e2e-dev/web run build && pnpm --filter @e2e-dev/mobile run build && pnpm --filter @e2e-dev/github run build && pnpm --filter @e2e-dev/kernel run build && pnpm --filter @e2e-dev/eas run build && pnpm --filter @e2e-dev/decision run build",
"build": "pnpm --filter e2e run build && pnpm --filter @e2e-dev/web run build && pnpm --filter @e2e-dev/mobile run build && pnpm --filter @e2e-dev/github run build && pnpm --filter @e2e-dev/kernel run build && pnpm --filter @e2e-dev/eas run build && pnpm --filter @e2e-dev/decision run build && pnpm --filter @e2e-dev/tern run build",
"check": "pnpm run lint && pnpm run check:dead-code && pnpm run typecheck && pnpm run docs:check-errors && pnpm run check:peer-ranges && pnpm run check:install-scripts && pnpm run docs:check",
"check:dead-code": "fallow dead-code",
"check:peer-ranges": "node scripts/check-peer-ranges.ts",
Expand All @@ -25,7 +25,7 @@
"canary": "node scripts/canary-changeset.ts && changeset version --snapshot canary && pnpm run build",
"canary:publish": "changeset publish --tag canary --no-git-tag && node scripts/restore-peer-ranges.ts",
"typecheck": "pnpm run build && pnpm -r run typecheck && tsc -p scripts",
"test": "pnpm run build && pnpm --filter e2e run test && pnpm --filter @e2e-dev/web run test && pnpm --filter @e2e-dev/mobile run test && pnpm --filter @e2e-dev/github run test && pnpm --filter @e2e-dev/kernel run test && pnpm --filter @e2e-dev/eas run test && pnpm --filter @e2e-dev/decision run test && pnpm run test:scripts",
"test": "pnpm run build && pnpm --filter e2e run test && pnpm --filter @e2e-dev/web run test && pnpm --filter @e2e-dev/mobile run test && pnpm --filter @e2e-dev/github run test && pnpm --filter @e2e-dev/kernel run test && pnpm --filter @e2e-dev/eas run test && pnpm --filter @e2e-dev/decision run test && pnpm --filter @e2e-dev/tern run test && pnpm run test:scripts",
"test:testbed": "pnpm run build && pnpm --filter @e2e-dev/testbed test",
"test:web-benchmark": "pnpm run build && pnpm --filter @e2e-dev/web-benchmark test",
"test:mobile-benchmark": "pnpm run build && pnpm --filter @e2e-dev/mobile-benchmark test",
Expand Down
4 changes: 4 additions & 0 deletions packages/tern/NOTICE
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
@e2e-dev/tern
Copyright 2026 contributors to tester-army/e2e

This product includes software developed for the tester-army/e2e project.
33 changes: 33 additions & 0 deletions packages/tern/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# @e2e-dev/tern

Tern desktop/TUI engine for [e2e](https://www.npmjs.com/package/e2e).

It reads Tern's structured control surface and drives input through Tern while
keeping the runner on the standard `e2e/engine` contract.

## Usage

```ts
import type { E2EConfig } from 'e2e';
import { ternEngine } from '@e2e-dev/tern';

export default {
targets: [{
name: 'tui',
engine: ternEngine({ pane: process.env.TERN_PANE, control: process.env.TERN_CONTROL }),
app: {},
}],
} satisfies E2EConfig;
```

When `pane` is omitted, every attempt gets a fresh Tern tab using `command`
(a shell by default), and teardown closes it.

## Credit

Initial Tern engine implementation by Kevin Rajan ([kvnloo](https://github.com/kvnloo)),
built on e2e's `defineEngine` contract and Tern/TSP's control surface.

## License

Apache-2.0
60 changes: 60 additions & 0 deletions packages/tern/package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
{
"name": "@e2e-dev/tern",
"version": "0.0.1",
"description": "Tern desktop engine for e2e agentic end-to-end testing",
"keywords": [
"e2e",
"end-to-end",
"testing",
"agentic",
"desktop-testing",
"terminal",
"tui",
"tern"
],
"license": "Apache-2.0",
"repository": {
"type": "git",
"url": "git+https://github.com/tester-army/e2e.git",
"directory": "packages/tern"
},
"bugs": {
"url": "https://github.com/tester-army/e2e/issues"
},
"homepage": "https://github.com/tester-army/e2e/tree/main/packages/tern#readme",
"publishConfig": {
"registry": "https://registry.npmjs.org/",
"access": "public",
"tag": "latest"
},
"type": "module",
"exports": {
".": {
"types": "./dist/index.d.ts",
"default": "./dist/index.js"
}
},
"files": [
"dist",
"NOTICE"
],
"scripts": {
"build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc --project tsconfig.build.json && node ../../scripts/stamp-dist.ts",
"prepublishOnly": "node ../../scripts/check-dist.ts",
"typecheck": "tsc --noEmit",
"test": "vitest run",
"test:watch": "vitest"
},
"peerDependencies": {
"e2e": ">=0.18.0 <1"
},
"devDependencies": {
"@types/node": "26.6.2",
"e2e": "workspace:*",
"typescript": "7.0.2",
"vitest": "5.0.1"
},
"engines": {
"node": "^22.22.3 || >=24.8.0"
}
}
56 changes: 56 additions & 0 deletions packages/tern/src/drive.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
import { parseKey, type Key, type ParsedKey } from "e2e/engine";

import type { Box } from "./tree.ts";

export interface Cell {
readonly col: number;
readonly row: number;
}

const NAMED: Readonly<Record<string, string>> = {
ArrowDown: "down",
ArrowLeft: "left",
ArrowRight: "right",
ArrowUp: "up",
Backspace: "backspace",
Delete: "delete",
End: "end",
Enter: "enter",
Escape: "escape",
Home: "home",
Insert: "insert",
PageDown: "pagedown",
PageUp: "pageup",
Space: "space",
Tab: "tab",
};

/** The cell under the center of `rect`, inside a pane of `cols` by `rows`. */
export function cellAt(rect: Box, pane: Box, cols: number, rows: number): Cell {
const width = pane.width / Math.max(1, cols);
const height = pane.height / Math.max(1, rows);
const col = Math.min(cols - 1, Math.max(0, Math.floor((rect.x + rect.width / 2 - pane.x) / width)));
const row = Math.min(rows - 1, Math.max(0, Math.floor((rect.y + rect.height / 2 - pane.y) / height)));
return { col, row };
}

/** A `press` key as `tern send` spells a combo. */
export function ternCombo(key: Key): string | undefined {
const parsed = parseKey(key);
if (parsed === undefined) return undefined;
return comboOf(parsed);
}

function comboOf(parsed: ParsedKey): string {
const mods = parsed.modifiers.map((mod) => (mod === "Control" || mod === "ControlOrMeta" ? "ctrl" : mod === "Alt" ? "alt" : mod === "Shift" ? "shift" : "super"));
const name = parsed.key.kind === "char" ? parsed.key.char : (NAMED[parsed.key.name] ?? parsed.key.name.toLowerCase());
return [...mods, name].join("+");
}

/** Keys that scroll the focused pane. A finger moving up reveals what is below. */
export function scrollKeys(direction: "up" | "down" | "left" | "right"): string {
if (direction === "up") return "pagedown";
if (direction === "down") return "pageup";
if (direction === "left") return "right";
return "left";
}
Loading
Loading