Skip to content
Merged
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
20 changes: 15 additions & 5 deletions examples/repl-bench/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -485,11 +485,15 @@ retained session again to verify that the current viewport supplies the size.
| `Terminal.Region` | The paired `name="sidekick-composer"`, `name="transcript"`, or `name="history"` selects a visible region for its body. Nested regions override the selection for their body. Focus and pane selection stay where they were. |
| `Terminal.WaitForText` | Waits for `text` in the nearest region or viewport. Optional `row` limits the match to a zero-based viewport row. Optional `at={{ row, column }}` matches its starting cell using zero-based coordinates. Optional `bold` matches the starting cell’s rendered bold attribute. `as` binds the unique positive match. Use `count` to wait for an exact number of matches. It cannot be combined with `as` or `present`. Zero matches or `present={false}` require the selected region to be visible. A `timeout` duration overrides the enclosing bench's wait duration. |
| `Terminal.Scroll` | `delta` is the signed number of wheel steps over the nearest region. Zero does nothing. Nonzero steps require a visible scroll target. Optional `at={{ row, column }}` targets a cell inside the selected region or viewport. |
| `Repl.Sidekick.Activate` | Clicks the visible Sidekick tab and waits for the composer to gain focus. Start with focus elsewhere to exercise tab activation. |
| `Repl.Sidekick.OpenAnswer` | Clicks the visible Sidekick answer control and waits for focus in the answer editor. |

For builds with numbered focus shortcuts, use the component for the region
that should receive the next input. For example, use `<Repl.Focus.Draft />`
before typing an entry. Each component sends the corresponding shortcut and
follows the [REPL focus rules](../../specs/repl-spec.md#move-between-regions-and-edit-within-them).
before typing an entry. Each component checks that its digit is offered, sends
it once, and waits for the REPL to dismiss the focus hints. An unavailable
digit fails the step and reports the offered shortcuts. See the
[REPL focus rules](../../specs/repl-spec.md#move-between-regions-and-edit-within-them).

| Region | Component |
| --- | --- |
Expand All @@ -508,9 +512,15 @@ screen inspection require an active launch. The acceptance journeys also use
`ReplBench` and `ReplBench.*`. Set initial dimensions on the enclosing
`Terminal`.

`waitTimeout` sets the default `WaitForText` duration for an `<XMD.Repl>` body,
including nested regions. It defaults to five seconds. Each bench supplies its
own duration, including when it uses `resume`. The enclosing `<Test>` deadline
Use the component that expresses the action you need. For a raw terminal gesture,
wait for the specific visible result before sending input that depends on it.
If the test exercises a burst of input, send the burst together and check its
result. Keep assertions for the journey’s outcome in the test.

`waitTimeout` sets the default wait duration for `WaitForText` and the
`Repl.Focus.*` and `Repl.Sidekick.*` actions in an `<XMD.Repl>` body, including
nested regions. It defaults to five seconds. Each bench supplies its own
duration, including when it uses `resume`. The enclosing `<Test>` deadline
can end a wait earlier.

Set `sidekick-agent` to an agent name or an explicit Markdown TestAgent path.
Expand Down
7 changes: 3 additions & 4 deletions examples/repl-bench/journeys/layout-queue.test.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@
<Terminal.WaitForText text="SIDEKICK" row={1} />
<Terminal.WaitForText text="HISTORY" row={29} />
<Terminal.Screenshot name="layout-medium" />
<Terminal.WaitForText text="SIDEKICK" row={1} as="mediumTab" />
<Terminal.Click at={mediumTab} />
<Repl.Focus.Draft />
<Repl.Sidekick.Activate />
<Terminal.Resize columns={72} rows={20} />
<Terminal.WaitForText text="* Sidekick" row={1} />
<Terminal.WaitForText text="message the sidekick" as="composer" />
Expand Down Expand Up @@ -51,8 +51,7 @@
<Terminal.WaitForText text="☑ Reproduce checkout" />
<Terminal.WaitForText text="TODO 3" />
<Terminal.Screenshot name="todo-three-open" />
<Terminal.WaitForText text="SIDEKICK" row={1} as="sidekickTab" />
<Terminal.Click at={sidekickTab} />
<Repl.Sidekick.Activate />
<Terminal.WaitForText text="TODO change acknowledged." />
<XMD.Repl.SidekickPrompt text="Finish the remaining TODOs." as="finished" />
<AssertStringIncludes actual={finished.output} expected="All TODOs complete." />
Expand Down
5 changes: 1 addition & 4 deletions examples/repl-bench/journeys/repl-bench.test.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,10 +27,7 @@
<ReplBench columns={120} rows={30} expectExit={true} as="closed">
<Cwd as="directory" />
<Repl.Focus.Draft />
<Terminal.WaitForText text="> DRAFT" />
<Terminal.WaitForText text="SIDEKICK" row={1} as="sidekickTab" />
<Terminal.Click at={sidekickTab} />
<Terminal.WaitForText text="> › message the sidekick" />
<Repl.Sidekick.Activate />
<ReplBench.Resize columns={72} rows={20} />
<ReplBench.WaitForText text="Entries * Sidekick" />
<ReplBench.WaitForText text="message the sidekick" />
Expand Down
14 changes: 11 additions & 3 deletions examples/repl-bench/journeys/repl-focus-shortcuts.test.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,16 +49,24 @@
<Repl.Focus.Draft />
<Terminal.WaitForText text="> DRAFT" bold={true} />
<Terminal.Type text="narrow-draft" />
<Repl.Focus.Tabs />
<Terminal.WaitForText text="> DRAFT" bold={true} />
<Try>
<Repl.Focus.Tabs />
<Fail message="The narrow viewport does not offer the Tabs shortcut" />
<Catch as="unavailable">
<AssertStringIncludes actual={unavailable.message} expected="Focus shortcut [5] is unavailable" />
</Catch>
</Try>
<Terminal.Key key="Escape" />
<Terminal.WaitForText text="move focus · Esc closes" present={false} />
<Terminal.Type text="-kept" />
<Terminal.WaitForText text="narrow-draft-kept" />

<Repl.Focus.History />
<Terminal.WaitForText text="> [history]" bold={true} />
<Terminal.Key key="Enter" />
<Terminal.WaitForText text="[close]" />
<Repl.Focus.Message />
<Terminal.Key key="Ctrl+G" />
<Terminal.Key key="1" />
<Terminal.WaitForText text="[close]" />
<Terminal.WaitForText text="message the sidekick" present={false} />
<Terminal.Key key="Escape" />
Expand Down
7 changes: 3 additions & 4 deletions examples/repl-bench/journeys/repl-inline-recovery.test.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,11 @@
<Test name="a saved Sidekick answer stays readable and ordinary Message continues after Stop" timeout="120s">
<ReplBench scenario="examples/repl-bench/fixtures/repl-sidekick-stopped-answer.md" columns={160} rows={36} waitTimeout="30s" expectExit={true} as="closed">
<Terminal.WaitForText text="SIDEKICK" row={1} as="sidekickTab" />
<Terminal.Click at={sidekickTab} />
<Repl.Focus.Draft />
<Repl.Sidekick.Activate />
<ReplBench.Type text="Ask me to save a decision." />
<ReplBench.WaitForText text="Ask me to save a decision." />
<ReplBench.Key key="Enter" />
<ReplBench.WaitForText text="[answer sidekick]" as="answer" />
<ReplBench.Click at={answer} />
<Repl.Sidekick.OpenAnswer />
<ReplBench.Type text="keep-answer" />
<ReplBench.WaitForText text="= keep-answer" />
<ReplBench.Key key="Enter" />
Expand Down
4 changes: 2 additions & 2 deletions examples/repl-bench/journeys/repl-saved-recovery.test.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<Test name="Saved recovery stays visible through resize without a new prompt" timeout="90s">
<ReplBench scenario="examples/repl-bench/fixtures/repl-sidekick-saved-recovery.md" columns={160} rows={36} waitTimeout="30s" expectExit={true} as="closed">
<Terminal.WaitForText text="SIDEKICK" row={1} as="sidekickTab" />
<Terminal.Click at={sidekickTab} />
<Repl.Focus.Draft />
<Repl.Sidekick.Activate />
<ReplBench.Type text="Inspect output." />
<ReplBench.Key key="Enter" />
<ReplBench.WaitForText text="Entry saved. Feedback receipt unknown." />
Expand Down
4 changes: 1 addition & 3 deletions examples/repl-bench/journeys/repl-scripted-sidekick.test.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,9 +101,7 @@
<ReplBench.WaitForText text="question" />
</ReplBench.Region>
<ReplBench.Key key="Enter" />
<ReplBench.WaitForText text="[answer sidekick]" as="answer" />
<ReplBench.Click at={answer} />
<ReplBench.WaitForText text="[submit]" />
<Repl.Sidekick.OpenAnswer />
<ReplBench.Type text="held-value" />
<ReplBench.WaitForText text="= held-value" />
<ReplBench.Key key="ArrowLeft" />
Expand Down
55 changes: 55 additions & 0 deletions examples/repl-bench/lib/driver-bun.ts
Original file line number Diff line number Diff line change
Expand Up @@ -323,6 +323,61 @@ export function useDriver(options: Launch) {
ACTION_TIMEOUT,
);
}
case "focus-shortcut": {
const { digit, timeout = ACTION_TIMEOUT } = command;
if (lastFrame().focusHints() === undefined) {
send(keyToAnsi(parseKey("Ctrl+G")));
}
const hints = yield* wait(
`the numbered focus hints for shortcut [${digit}]`,
(frame) => frame.focusHints(),
timeout,
);
if (!hints.includes(digit)) {
throw new Error(
`Focus shortcut [${digit}] is unavailable. Offered: ${hints.join(", ")}`,
);
}
send(digit);
// The REPL keeps the hints open when a numbered shortcut is refused.
return yield* wait(
`the REPL to accept focus shortcut [${digit}]`,
(frame) => (frame.focusHints() === undefined ? true : undefined),
timeout,
);
}
case "activate-sidekick": {
const { timeout = ACTION_TIMEOUT } = command;
const tab = yield* wait(
"the Sidekick tab",
(frame) => frame.sidekickControl(),
timeout,
);
if (lastFrame().composerFocused) {
throw new Error(
"Move focus out of the Sidekick composer before testing tab activation",
);
}
click(tab);
return yield* wait(
"the Sidekick composer to gain focus after clicking its tab",
(frame) => (frame.composerFocused ? true : undefined),
timeout,
);
}
case "open-sidekick-answer": {
const { timeout = ACTION_TIMEOUT } = command;
const answer = yield* waitFor({ text: "[answer sidekick]", unique: true, timeout });
if (answer === null || lastFrame().sidekickAnswerFocused) {
throw new Error("Expected a pending Sidekick question with its editor closed");
}
click(answer);
return yield* wait(
"the Sidekick answer field to gain focus",
(frame) => (frame.sidekickAnswerFocused ? true : undefined),
timeout,
);
}
case "type":
if (command.text.includes("\x1b[201~")) {
throw new Error("Text contains the terminal’s paste delimiter");
Expand Down
7 changes: 7 additions & 0 deletions examples/repl-bench/lib/protocol.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,13 @@ export const command = z.discriminatedUnion("action", [
z.object({ action: z.literal("ready") }),
z.object({ action: z.literal("attachment-ready"), path: z.string() }),
z.object({ action: z.literal("focus") }),
z.object({
action: z.literal("focus-shortcut"),
digit: z.string().regex(/^[1-9]$/),
timeout: z.int().positive().optional(),
}),
z.object({ action: z.literal("activate-sidekick"), timeout: z.int().positive().optional() }),
z.object({ action: z.literal("open-sidekick-answer"), timeout: z.int().positive().optional() }),
z.object({ action: z.literal("type"), text: z.string() }),
z.object({ action: z.literal("key"), key: z.string().min(1) }),
z.object({ action: z.literal("click"), at: point }),
Expand Down
28 changes: 28 additions & 0 deletions examples/repl-bench/lib/screen.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,10 @@ export function viewport(backend: TerminalBackend, size: Size) {
const colour = styled[row]?.[column]?.bg;
return colour == null ? undefined : (colour.r << 16) | (colour.g << 8) | colour.b;
}
function foreground({ row, column }: Point): number | undefined {
const colour = styled[row]?.[column]?.fg;
return colour == null ? undefined : (colour.r << 16) | (colour.g << 8) | colour.b;
}
const full: Box = { left: 0, right: size.columns, top: 0, bottom: size.rows };
const rows = cells.map((row) => row.join(""));

Expand Down Expand Up @@ -95,6 +99,30 @@ export function viewport(backend: TerminalBackend, size: Size) {
bold: ({ row, column }: Point) => styled[row]?.[column]?.bold === true,
composerLabel,
composerFocused: composerLabel !== undefined && hasFocusMarker(composerLabel),
focusHints(): string[] | undefined {
for (const { row, column } of matches(" move focus · Esc closes")) {
if (row !== 0 && background(row, column + 1) !== REPL_PALETTE.drawerSurface) {
continue;
}
const before = cells[row].slice(0, column).join("");
const offered = /(?:^|\s)([1-9](?: [1-9])*)$/.exec(before)?.[1]?.split(" ");
if (
offered !== undefined &&
[...matches(`[${offered[0]}]`)].some(
({ row, column }) => background(row, column) === REPL_PALETTE.focusHint,
)
) {
return offered;
}
}
return undefined;
},
get sidekickAnswerFocused(): boolean {
return (
[...matches("> = ")].some((point) => foreground(point) === REPL_PALETTE.focus) &&
matches("[submit]").next().value !== undefined
);
},
box(region?: Region): Box | undefined {
switch (region) {
case "sidekick-composer":
Expand Down
13 changes: 11 additions & 2 deletions examples/repl-bench/plugin.ts
Original file line number Diff line number Diff line change
Expand Up @@ -421,11 +421,19 @@ const focusActions = Object.entries({
SurfaceBar: "9",
}).map(([area, key]) =>
registration(`Repl.Focus.${area}`, function* () {
yield* action({ action: "key", key: "Ctrl+G" });
yield* action({ action: "key", key });
yield* action({ action: "focus-shortcut", digit: key, timeout: yield* WaitTimeout.get() });
}),
);

const sidekickActions = [
registration("Repl.Sidekick.Activate", function* () {
yield* action({ action: "activate-sidekick", timeout: yield* WaitTimeout.get() });
}),
registration("Repl.Sidekick.OpenAnswer", function* () {
yield* action({ action: "open-sidekick-answer", timeout: yield* WaitTimeout.get() });
}),
];

const terminalActions = [
registration(
"Terminal.Screenshot",
Expand Down Expand Up @@ -558,6 +566,7 @@ export default Plugin({
})),
...terminalActions,
...focusActions,
...sidekickActions,
...terminalActions.map((entry) => ({
...entry,
name: entry.name.replace("Terminal.", "ReplBench."),
Expand Down
18 changes: 18 additions & 0 deletions examples/repl-bench/tests/screen.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -41,3 +41,21 @@ Deno.test("recognizes the focused composer among lookalike queue and TODO rows",
backend.destroy();
}
});

Deno.test("reads the complete focus legend without treating document text as shortcuts", () => {
const backend = createXtermBackend({ cols: size.columns, rows: size.rows });
try {
backend.feed(encoder.encode("XMD REPL\r\n[1] 1 5 move focus · Esc closes\r\n"));
assert.equal(viewport(backend, size).focusHints(), undefined);

const badge = paint(REPL_PALETTE.focusHint, "[1]");
backend.feed(
encoder.encode(
`${badge} ${paint(REPL_PALETTE.drawerSurface, "1 2 8 move focus · Esc closes")}\r\n`,
),
);
assert.deepEqual(viewport(backend, size).focusHints(), ["1", "2", "8"]);
} finally {
backend.destroy();
}
});
Loading