Files
kandev/apps/web/e2e/tests/terminal/mobile-terminal-scroll.spec.ts
T
João Salavisa 78609c005e feat(terminal): scroll mobile passthrough terminal scrollback via touch (#1046)
* feat(terminal): add touch-scroll helper for xterm scrollback

Pure helper that translates single-finger vertical drags into
`terminal.scrollLines(n)` calls. Handles threshold gating so taps still
reach xterm, ignores multi-touch, yields to horizontal-dominant drags.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* feat(terminal): wire mobile touch scrollback into passthrough terminal

Adds an `enableTouchScroll` prop on PassthroughTerminal and a thin hook
that calls `attachTouchScroll` while the terminal is mounted. The two
mobile mount points (terminal panel + chat-panel passthrough embed) opt
in; desktop callers are unaffected. Fixes the bug where xterm.js's
canvas absorbed touch gestures and left the scrollback unreachable.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* test(terminal): mobile e2e for passthrough touch-scroll

Pixel 5-emulated Playwright spec: produce 200 lines of output, simulate
a single-finger down-swipe, assert `terminal.buffer.active.viewportY`
moved into the scrollback, then swipe back to return. Extends the e2e
buffer reader to expose viewportY alongside `__xtermReadBuffer`.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* test(terminal): relax mobile swipe-back assertion against late shell output

Replace the exact `.toBe(bottomViewportY)` check with
`.toBeGreaterThanOrEqual` so the test doesn't flake if shell echo
arrives between the snapshot and the post-swipe read. xterm clamps at
the buffer boundary, so overshooting back-to-bottom is impossible.

Addresses PR #1046 Claude review thread 3293258085.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* docs(terminal): document useTouchScroll's isTerminalReady invariant

Adds a comment next to the eslint-disable explaining why the deps
array can safely omit terminalRef/xtermRef: useTerminalInit only flips
isTerminalReady false→true once per mount. A future refactor that
recreates the terminal mid-mount must add a new dep.

Addresses PR #1046 Claude review thread 3293258175.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* chore(terminal): clear all exposed buffer-reader fields on dispose

clearBufferReader now nulls `__xtermGetFontFamily` and
`__xtermGetFontSize` alongside the buffer readers. The two predated
this PR and were never cleaned up; keeping the teardown symmetric with
exposeBufferReader prevents stale references if the container is ever
reused.

Addresses PR #1046 Claude review thread 3293274674.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* test(terminal): reset document.body between touch-scroll cases

Adds an afterEach to wipe jsdom's body so orphan divs from one test
don't bleed into the next. Avoids cross-test pollution if a future
case queries document.body for containers.

Addresses PR #1046 Claude review thread 3293274769.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

---------

Co-authored-by: Kandev Agent <agent@kandev.dev>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-23 19:27:49 +01:00

175 lines
6.4 KiB
TypeScript

// Routing: /t/{taskId} (task-keyed). File name starts with "mobile-" so it
// runs on the mobile-chrome Playwright project (Pixel 5 emulation).
//
// Covers the bug: xterm.js's canvas absorbs touch events, so a vertical swipe
// over the mobile terminal does nothing. The mobile passthrough wires the
// container so single-finger drags translate into `terminal.scrollLines`.
import { type Page, expect } from "@playwright/test";
import { test } from "../../fixtures/test-base";
import type { SeedData } from "../../fixtures/test-base";
import type { ApiClient } from "../../helpers/api-client";
import { SessionPage } from "../../pages/session-page";
async function seedTaskWithSession(
testPage: Page,
apiClient: ApiClient,
seedData: SeedData,
title: string,
): Promise<SessionPage> {
const task = await apiClient.createTaskWithAgent(
seedData.workspaceId,
title,
seedData.agentProfileId,
{
description: "/e2e:simple-message",
workflow_id: seedData.workflowId,
workflow_step_id: seedData.startStepId,
repository_ids: [seedData.repositoryId],
},
);
await testPage.goto(`/t/${task.id}`);
const session = new SessionPage(testPage);
await session.waitForLoad();
await session.waitForChatIdle();
return session;
}
async function switchToTerminalPanel(testPage: Page): Promise<void> {
await testPage.getByRole("button", { name: "Terminal" }).tap();
}
async function waitForShellReady(testPage: Page, timeout = 45_000): Promise<void> {
await expect
.poll(() => readTerminalBuffer(testPage).then((b) => b.length > 0), {
timeout,
message: "Waiting for mobile terminal shell to connect",
})
.toBe(true);
}
async function readTerminalBuffer(page: Page): Promise<string> {
return page.evaluate(() => {
const panel = document.querySelector('[data-testid="terminal-panel"]');
const xtermEl = panel?.querySelector(".xterm");
type XC = HTMLElement & { __xtermReadBuffer?: () => string };
const container = xtermEl?.parentElement as XC | null | undefined;
return container?.__xtermReadBuffer?.() ?? "";
});
}
async function readViewportY(page: Page): Promise<number> {
return page.evaluate(() => {
const panel = document.querySelector('[data-testid="terminal-panel"]');
const xtermEl = panel?.querySelector(".xterm");
type XC = HTMLElement & { __xtermReadViewportY?: () => number };
const container = xtermEl?.parentElement as XC | null | undefined;
return container?.__xtermReadViewportY?.() ?? -1;
});
}
async function focusTerminalForTyping(session: SessionPage): Promise<void> {
await session.terminal.locator(".xterm").click();
}
/**
* Dispatch a synthetic single-finger swipe on the xterm container. We bypass
* Playwright's touchscreen because the gesture coordinates need to be relative
* to the .xterm element's bounding box, and we want guaranteed delivery
* regardless of overlay z-index.
*/
async function swipe(
page: Page,
direction: "down" | "up",
steps = 5,
rowsToScroll = 8,
): Promise<void> {
await page.evaluate(
({ direction, steps, rowsToScroll }) => {
const panel = document.querySelector('[data-testid="terminal-panel"]');
const xtermEl = panel?.querySelector(".xterm") as HTMLElement | null;
if (!xtermEl) throw new Error("xterm element not found");
const rect = xtermEl.getBoundingClientRect();
const cx = rect.left + rect.width / 2;
const startY = direction === "down" ? rect.top + 16 : rect.bottom - 16;
const rowHeight = rect.height / 24;
const totalDy = rowHeight * rowsToScroll * (direction === "down" ? 1 : -1);
const stepDy = totalDy / steps;
const makeTouch = (clientX: number, clientY: number) =>
({ clientX, clientY, identifier: 1 }) as unknown as Touch;
const fire = (type: string, clientY: number) => {
const event = new Event(type, { bubbles: true, cancelable: true }) as TouchEvent;
const touches = [makeTouch(cx, clientY)];
Object.defineProperty(event, "touches", { value: touches, configurable: true });
Object.defineProperty(event, "changedTouches", { value: touches, configurable: true });
xtermEl.dispatchEvent(event);
};
fire("touchstart", startY);
for (let i = 1; i <= steps; i++) {
fire("touchmove", startY + stepDy * i);
}
fire("touchend", startY + totalDy);
},
{ direction, steps, rowsToScroll },
);
}
async function typeAndRun(page: Page, command: string): Promise<void> {
await page.keyboard.type(command);
await page.keyboard.press("Enter");
}
test.describe("Mobile passthrough terminal — touch scroll", () => {
test.describe.configure({ retries: 1 });
test("user swipes down on the terminal to scroll into scrollback, then up to return", async ({
testPage,
apiClient,
seedData,
}) => {
test.setTimeout(120_000);
const session = await seedTaskWithSession(testPage, apiClient, seedData, "Touch scroll");
await switchToTerminalPanel(testPage);
await waitForShellReady(testPage);
await focusTerminalForTyping(session);
// Produce enough output to populate the scrollback past one viewport.
await typeAndRun(testPage, "for i in $(seq 1 200); do echo line $i; done");
await expect
.poll(() => readTerminalBuffer(testPage), {
timeout: 30_000,
message: "Waiting for the 200th echo to land",
})
.toContain("line 200");
const bottomViewportY = await readViewportY(testPage);
expect(bottomViewportY).toBeGreaterThan(0);
// Swipe down — finger drags down → reveals older lines → viewportY drops.
await swipe(testPage, "down");
await expect
.poll(() => readViewportY(testPage), {
timeout: 5_000,
message: "Downward swipe should scroll xterm into the scrollback (viewportY decreases)",
})
.toBeLessThan(bottomViewportY);
// Swipe up enough rows to return to the bottom of the buffer.
await swipe(testPage, "up", 5, 50);
// Match-or-beat: any late shell output that arrives between captures bumps
// the buffer's bottom further down, so the new viewportY may legitimately
// exceed the snapshot. xterm clamps at the buffer boundary, so overshoot
// is impossible.
await expect
.poll(() => readViewportY(testPage), {
timeout: 5_000,
message: "Upward swipe should return viewportY to the bottom",
})
.toBeGreaterThanOrEqual(bottomViewportY);
});
});