Отладка интерфейса в браузере

Текст

---
name: "playwright-interactive"
description: "Постоянная работа с браузером и Electron через `js_repl` для быстрой итеративной отладки интерфейса."
---

Скилл Playwright Interactive

Используй постоянную сессию Playwright в js_repl, чтобы отлаживать локальные веб-приложения и приложения на Electron, сохранять одни и те же дескрипторы (handles) живыми между итерациями и проводить функциональную и визуальную проверку качества (QA), не перезапуская весь набор инструментов, пока не сменился владелец процесса.

Предварительные условия

• Для этого скилла должен быть включён js_repl.
• Если js_repl нет, включи его в ~/.codex/config.toml:

[features]
js_repl = true

• Можно также запустить новую сессию с --enable js_repl (это равнозначно -c features.js_repl=true).
• После включения js_repl начни новую сессию Codex, чтобы список инструментов обновился.
• Пока что запускай этот рабочий процесс с отключённой песочницей: стартуй Codex с --sandbox danger-full-access (или с эквивалентной настройкой sandbox_mode=danger-full-access). Это временное требование: поддержка js_repl и Playwright внутри песочницы ещё не доделана.
• Выполняй настройку из той же папки проекта, которую нужно отлаживать.
• Относись к js_repl_reset как к средству восстановления, а не к обычной уборке. Сброс ядра уничтожает твои дескрипторы Playwright.

Разовая настройка

test -f package.json || npm init -y
npm install playwright
# Web-only, for headed Chromium or mobile emulation:
# npx playwright install chromium
# Electron-only, and only if the target workspace is the app itself:
# npm install --save-dev electron
node -e "import('playwright').then(() => console.log('playwright import ok')).catch((error) => { console.error(error); process.exit(1); })"

Если позже ты переключишься на другое рабочее пространство, повтори настройку там.

Основной рабочий процесс

1. Перед тестированием коротко составь перечень проверок QA:
2. Собери перечень из трёх источников: требования пользователя, видимые пользователю функции и поведение, которые ты действительно реализовал, и утверждения, которые ты собираешься сделать в итоговом ответе.
3. Всё, что есть хотя бы в одном из этих трёх источников, перед приёмкой должно соответствовать хотя бы одной проверке QA.
4. Перечисли видимые пользователю утверждения, которые ты собираешься подтвердить.
5. Перечисли каждый значимый элемент управления, переключатель режима или реализованное интерактивное поведение, доступные пользователю.
6. Перечисли изменения состояния или вида, которые может вызвать каждый элемент управления или реализованное поведение.
7. Используй этот перечень как общий список охвата и для функциональной, и для визуальной проверки.
8. Для каждого утверждения или пары «элемент управления — состояние» отметь предполагаемую функциональную проверку, конкретное состояние, в котором нужно провести визуальную проверку, и доказательство, которое ты рассчитываешь получить.
9. Если требование визуально важно, но субъективно, преврати его в наблюдаемую проверку QA, а не оставляй неявным.
10. Добавь минимум 2 исследовательских сценария или сценария вне «счастливого пути», которые могут вскрыть хрупкое поведение.
11. Один раз выполни ячейку начальной настройки (bootstrap).
12. Запусти или проверь любой нужный сервер разработки в постоянной TTY-сессии.
13. Запусти нужную среду выполнения и продолжай использовать одни и те же дескрипторы Playwright.
14. После каждого изменения кода перезагружай страницу, если менялся только рендерер, и перезапускай приложение, если менялся главный процесс или запуск.
15. Проведи функциональную проверку с обычным пользовательским вводом.
16. Проведи отдельный проход визуальной проверки.
17. Проверь, что содержимое помещается в окно просмотра (viewport), и сделай снимки экрана, нужные для подтверждения твоих утверждений.
18. Закрывай сессию Playwright, только когда задача действительно закончена.

Начальная настройка (выполняется один раз)

var chromium;
var electronLauncher;
var browser;
var context;
var page;
var mobileContext;
var mobilePage;
var electronApp;
var appWindow;

try {
  ({ chromium, _electron: electronLauncher } = await import("playwright"));
  console.log("Playwright loaded");
} catch (error) {
  throw new Error(
    `Could not load playwright from the current js_repl cwd. Run the setup commands from this workspace first. Original error: ${error}`
  );
}

Правила привязки:

• Для общих дескрипторов Playwright верхнего уровня используй var, потому что последующие ячейки js_repl используют их повторно.
• Ячейки настройки ниже намеренно короткие и описывают самый простой путь. Если дескриптор выглядит устаревшим, присвой этой переменной undefined и перезапусти ячейку, вместо того чтобы добавлять логику восстановления повсюду.
• Лучше иметь один именованный дескриптор на каждую нужную поверхность (page, mobilePage, appWindow), чем снова и снова искать страницы в контексте.

Общие вспомогательные функции для веба:

var resetWebHandles = function () {
  context = undefined;
  page = undefined;
  mobileContext = undefined;
  mobilePage = undefined;
};

var ensureWebBrowser = async function () {
  if (browser && !browser.isConnected()) {
    browser = undefined;
    resetWebHandles();
  }

  browser ??= await chromium.launch({ headless: false });
  return browser;
};

var reloadWebContexts = async function () {
  for (const currentContext of [context, mobileContext]) {
    if (!currentContext) continue;
    for (const p of currentContext.pages()) {
      await p.reload({ waitUntil: "domcontentloaded" });
    }
  }
  console.log("Reloaded existing web tabs");
};

Выбор режима сессии

Для веб-приложений по умолчанию используй явно заданный viewport, а режим родного окна считай отдельным проходом проверки.

• Используй явный viewport для обычных итераций, проверки точек перелома (breakpoints), воспроизводимых снимков экрана, сравнения снимков и локализации элементов с помощью модели. Это вариант по умолчанию, потому что он стабилен на разных машинах и не зависит от оконного менеджера хоста.
• Когда нужно детерминированное поведение на экранах высокой плотности, оставь явный viewport и добавь deviceScaleFactor, а не переходи сразу в режим родного окна.
• Режим родного окна (viewport: null) используй для отдельного прохода с видимым окном, когда нужно проверить размер запущенного окна, поведение DPI на уровне ОС, взаимодействие с элементами интерфейса браузера или ошибки, которые могут зависеть от конфигурации дисплея хоста.
• Для Electron всегда исходи из поведения родного окна. Electron запускается через Playwright с noDefaultViewport, поэтому относись к нему как к настоящему окну рабочего стола и проверяй размер и раскладку при запуске, прежде чем что-либо менять в размерах.
• Когда приёмка зависит и от раскладки на разных точках перелома, и от поведения на реальном рабочем столе, проведи оба прохода: сначала явный viewport для детерминированной проверки, затем проверку в родном окне для итоговых проверок, зависящих от среды.
• Считай переключение режимов сбросом контекста. Не используй повторно context с эмуляцией viewport для прохода в родном окне, и наоборот: закрой старые page и context и создай новые для нового режима.

Запуск или повторное использование веб-сессии

Сессии для настольной и мобильной версий сайта используют общие browser, вспомогательные функции и процесс QA. Главное отличие в том, какую пару context и page ты создаёшь.

Контекст для настольной версии сайта

Задай в TARGET_URL адрес отлаживаемого приложения. Для локальных серверов предпочитай 127.0.0.1, а не localhost.

var TARGET_URL = "http://127.0.0.1:3000";

if (page?.isClosed()) page = undefined;

await ensureWebBrowser();
context ??= await browser.newContext({
  viewport: { width: 1600, height: 900 },
});
page ??= await context.newPage();

await page.goto(TARGET_URL, { waitUntil: "domcontentloaded" });
console.log("Loaded:", await page.title());

Если context или page устарели, присвой context = page = undefined и перезапусти ячейку.

Контекст для мобильной версии сайта

Если TARGET_URL уже есть, используй его повторно; если нет, задай мобильный адрес напрямую.

var MOBILE_TARGET_URL = typeof TARGET_URL === "string"
  ? TARGET_URL
  : "http://127.0.0.1:3000";

if (mobilePage?.isClosed()) mobilePage = undefined;

await ensureWebBrowser();
mobileContext ??= await browser.newContext({
  viewport: { width: 390, height: 844 },
  isMobile: true,
  hasTouch: true,
});
mobilePage ??= await mobileContext.newPage();

await mobilePage.goto(MOBILE_TARGET_URL, { waitUntil: "domcontentloaded" });
console.log("Loaded mobile:", await mobilePage.title());

Если mobileContext или mobilePage устарели, присвой mobileContext = mobilePage = undefined и перезапусти ячейку.

Проход в родном окне для веба

var TARGET_URL = "http://127.0.0.1:3000";

await ensureWebBrowser();

await page?.close().catch(() => {});
await context?.close().catch(() => {});
page = undefined;
context = undefined;

browser ??= await chromium.launch({ headless: false });
context = await browser.newContext({ viewport: null });
page = await context.newPage();

await page.goto(TARGET_URL, { waitUntil: "domcontentloaded" });
console.log("Loaded native window:", await page.title());

Запуск или повторное использование сессии Electron

Задай в ELECTRON_ENTRY значение ., когда текущее рабочее пространство — это приложение Electron, а main в package.json указывает на нужный входной файл. Если нужно напрямую указать файл главного процесса, используй путь вроде ./main.js.

var ELECTRON_ENTRY = ".";

if (appWindow?.isClosed()) appWindow = undefined;

if (!appWindow && electronApp) {
  await electronApp.close().catch(() => {});
  electronApp = undefined;
}

electronApp ??= await electronLauncher.launch({
  args: [ELECTRON_ENTRY],
});

appWindow ??= await electronApp.firstWindow();

console.log("Loaded Electron window:", await appWindow.title());

Если js_repl запущен не из рабочего пространства приложения Electron, при запуске явно передай cwd.

Если процесс приложения выглядит устаревшим, присвой electronApp = appWindow = undefined и перезапусти ячейку.

Если у тебя уже есть сессия Electron, но нужен свежий процесс после изменений главного процесса, preload-скрипта или запуска, используй ячейку перезапуска из следующего раздела, а не эту.

Повторное использование сессий во время итераций

Сохраняй одну и ту же сессию живой, когда это возможно.

Перезагрузка рендерера в вебе:

await reloadWebContexts();

Перезагрузка только рендерера в Electron:

await appWindow.reload({ waitUntil: "domcontentloaded" });
console.log("Reloaded Electron window");

Перезапуск Electron после изменений главного процесса, preload-скрипта или запуска:

await electronApp.close().catch(() => {});
electronApp = undefined;
appWindow = undefined;

electronApp = await electronLauncher.launch({
  args: [ELECTRON_ENTRY],
});

appWindow = await electronApp.firstWindow();
console.log("Relaunched Electron window:", await appWindow.title());

Если для запуска нужен явный cwd, укажи тот же и здесь.

Подход по умолчанию:

• Делай каждую ячейку js_repl короткой и посвящённой одной серии взаимодействий.
• Используй уже существующие привязки верхнего уровня (browser, context, page, electronApp, appWindow), не объявляя их заново.
• Если нужна изоляция, создай новую страницу или новый контекст внутри того же браузера.
• В Electron используй electronApp.evaluate(...) только для проверки главного процесса или специально созданной диагностики.
• Ошибки во вспомогательных функциях исправляй на месте; не сбрасывай REPL, если ядро на самом деле не сломано.

Чек-листы

Цикл сессии

• Один раз выполни начальную настройку js_repl, затем сохраняй одни и те же дескрипторы Playwright живыми между итерациями.
• Запускай целевую среду выполнения из текущего рабочего пространства.
• Внеси изменение в код.
• Перезагрузи или перезапусти приложение способом, подходящим для этого изменения.
• Если исследование выявило дополнительный элемент управления, состояние или видимое утверждение, обнови общий перечень QA.
• Заново проведи функциональную проверку.
• Заново проведи визуальную проверку.
• Делай итоговые артефакты, только когда текущее состояние — именно то, которое ты оцениваешь.

Решение о перезагрузке

• Изменение только в рендерере: перезагрузи существующую страницу или окно Electron.
• Изменение главного процесса, preload-скрипта или запуска: перезапусти Electron.
• Появилась неуверенность, кому принадлежит процесс, или в коде запуска: перезапусти, а не гадай.

Функциональная проверка

• Для приёмки используй настоящие элементы управления пользователя: клавиатуру, мышь, клик, касание или эквивалентные API ввода Playwright.
• Проверь хотя бы один сквозной критический сценарий.
• Убедись в видимом результате этого сценария, а не только во внутреннем состоянии.
• Для приложений реального времени и насыщенных анимацией проверяй поведение при реальных интервалах взаимодействия.
• Проходи по общему перечню QA, а не выборочно проверяй что придётся.
• Перед приёмкой проверь каждый заметный элемент управления хотя бы один раз, а не только основной «счастливый путь».
• Для обратимых элементов управления и переключателей из перечня проверяй полный цикл: исходное состояние, изменённое состояние и возврат к исходному.
• Когда скриптовые проверки пройдены, проведи короткий исследовательский проход обычным вводом в течение 30–90 секунд, а не только по задуманному пути.
• Если исследовательский проход выявил новое состояние, элемент управления или утверждение, добавь его в общий перечень QA и проверь до приёмки.
• page.evaluate(...) и electronApp.evaluate(...) можно использовать, чтобы посмотреть или подготовить состояние, но как ввод для приёмки они не засчитываются.

Визуальная проверка

• Относись к визуальной проверке как к отдельной от функциональной.
• Используй тот же общий перечень QA, составленный перед тестированием и обновляемый по ходу проверки; не начинай визуальный охват с другого, неявного списка.
• Заново сформулируй видимые пользователю утверждения и проверь каждое явно; не считай, что успешная функциональная проверка доказывает визуальное утверждение.
• Видимое пользователю утверждение не считается принятым, пока его не осмотрели в том самом состоянии, в котором оно должно восприниматься.
• Осматривай исходный viewport до прокрутки.
• Убедись, что начальный вид явно подтверждает главные утверждения об интерфейсе; если основной обещанный элемент там не воспринимается чётко, считай это ошибкой.
• Осмотри все обязательные видимые области, а не только основную поверхность взаимодействия.
• Осмотри состояния и режимы, уже перечисленные в общем перечне QA, включая хотя бы одно значимое состояние после взаимодействия, если задача интерактивная.
• Если движение или переходы входят в замысел, осмотри хотя бы одно состояние в момент перехода, а не только устоявшиеся конечные состояния.
• Если подписи, наложения, аннотации, направляющие или выделения должны следовать за меняющимся содержимым, проверь эту связь после соответствующей смены состояния.
• Для динамических и зависящих от взаимодействия визуальных элементов смотри достаточно долго, чтобы оценить устойчивость, порядок слоёв и читаемость; не полагайся на один снимок экрана при приёмке.
• Для интерфейсов, которые после загрузки или взаимодействия могут стать плотнее, осматривай самое плотное реалистичное состояние, которого можно достичь при проверке, а не только пустое, загружающееся или свёрнутое.
• Если у продукта есть заданный минимальный поддерживаемый размер viewport или окна, проведи отдельный визуальный проход на нём; если нет, выбери меньший, но всё ещё реалистичный размер и явно осмотри его.
• Различай наличие и реализацию: если нужный элемент технически есть, но плохо воспринимается из-за слабого контраста, перекрытия, обрезки или нестабильности, считай это визуальным дефектом.
• Если какая-либо обязательная видимая область обрезана, перекрыта или вытолкнута за пределы viewport в оцениваемом состоянии, считай это ошибкой, даже если показатели прокрутки страницы выглядят приемлемо.
• Ищи обрезку, переполнение, искажения, перекос раскладки, неровные отступы, проблемы выравнивания, нечитаемый текст, слабый контраст, нарушенный порядок слоёв и неудачные состояния анимации.
• Оценивай не только правильность, но и эстетическое качество. Интерфейс должен выглядеть продуманным, цельным и приятным для своей задачи.
• Для приёмки предпочитай снимки viewport. Снимки всей страницы используй только как вторичные отладочные артефакты, а когда область нужно рассмотреть ближе, делай снимок именно этой области.
• Если из-за движения снимок неоднозначен, немного подожди, пока интерфейс устоится, и сделай тот снимок, который ты на самом деле оцениваешь.
• Перед приёмкой явно спроси себя: какую видимую часть этого интерфейса я ещё не осмотрел внимательно?
• Перед приёмкой явно спроси себя: какой видимый дефект больше всего опозорит этот результат, если пользователь присмотрится?

Приёмка

• Функциональный сценарий пройден с обычным пользовательским вводом.
• Охват явно сверен с общим перечнем QA: отметь, какие требования, реализованные функции, элементы управления, состояния и утверждения проверены, и назови намеренные исключения.
• Визуальная проверка охватила весь значимый интерфейс.
• Для каждого видимого пользователю утверждения есть соответствующая визуальная проверка и просмотренный снимок экрана из состояния и с размером viewport или окна, где это утверждение важно.
• Проверки на помещение в viewport пройдены для предполагаемого начального вида и для любого обязательного минимального поддерживаемого размера viewport или окна.
• Если продукт запускается в окне, размер, положение и начальная раскладка при запуске проверены до любого ручного изменения размера или перемещения.
• Интерфейс не просто работает: он визуально цельный и не слабый эстетически для своей задачи.
• Функциональная правильность, помещение в viewport и визуальное качество должны проходить проверку каждое само по себе; одно не подразумевает другое.
• Для интерактивных продуктов проведён короткий исследовательский проход, и в ответе упомянуто, что он охватывал.
• Если в какой-то момент снимки экрана и числовые проверки расходились, расхождение выяснено до приёмки; видимая обрезка на снимках — это сбой, который нужно устранить, а не то, что можно перечеркнуть метриками.
• Включи краткое отрицательное подтверждение: какие основные классы дефектов ты искал и не нашёл.
• Очистка выполнена, либо ты намеренно оставил сессию живой для дальнейшей работы.

Примеры снимков экрана

Если ты собираешься выводить снимок через codex.emitImage(...), по умолчанию используй пути с нормализацией до CSS-пикселей из следующего раздела. Это канонические примеры для снимков, которые будет разбирать модель или которые нужны для последующих действий по координатам. Необработанные снимки допускай только как исключение при отладке, где важна точность; примеры такого исключения приведены после раздела о нормализации.

Снимки для модели (по умолчанию)

Если ты выводишь снимок через codex.emitImage(...) для разбора моделью, перед выводом нормализуй его до CSS-пикселей для именно той области, которую снял. Так возвращаемые координаты совпадут с CSS-пикселями Playwright, если ответ позже понадобится для кликов; кроме того, это уменьшает размер изображения и расход токенов модели.

По умолчанию не выводи необработанные снимки родного окна. Пропускай нормализацию, только когда тебе явно нужна точность до пикселей устройства: при отладке артефактов Retina или DPI, при попиксельной проверке отрисовки или в другом случае, где необработанные пиксели важнее размера данных. Для локального осмотра, который не отправляется модели, необработанный снимок подходит.

Не считай, что page.screenshot({ scale: "css" }) достаточно в режиме родного окна (viewport: null). В Chromium на дисплеях Retina в macOS снимки окна с видимым интерфейсом могут по-прежнему приходить в размере пикселей устройства, даже если запрошен scale: "css". То же предупреждение относится к окнам Electron, запущенным через Playwright: Electron работает с noDefaultViewport, и appWindow.screenshot({ scale: "css" }) тоже может вернуть результат в пикселях устройства.

Используй разные пути нормализации для веб-страниц и окон Electron:

• Веб: предпочитай напрямую page.screenshot({ scale: "css" }). Если Chromium в режиме родного окна всё равно возвращает размер в пикселях устройства, измени размер внутри текущей страницы через canvas; отдельная временная страница не нужна.
• Electron: не используй appWindow.context().newPage() или electronApp.context().newPage() как временную страницу. Контексты Electron не поддерживают этот способ надёжно. Делай снимок в главном процессе через BrowserWindow.capturePage(...), меняй размер через nativeImage.resize(...) и выводи эти байты напрямую.

Общие вспомогательные функции и соглашения:

var emitJpeg = async function (bytes) {
  await codex.emitImage({
    bytes,
    mimeType: "image/jpeg",
    detail: "original",
  });
};

var emitWebJpeg = async function (surface, options = {}) {
  await emitJpeg(await surface.screenshot({
    type: "jpeg",
    quality: 85,
    scale: "css",
    ...options,
  }));
};

var clickCssPoint = async function ({ surface, x, y, clip }) {
  await surface.mouse.click(
    clip ? clip.x + x : x,
    clip ? clip.y + y : y
  );
};

var tapCssPoint = async function ({ page, x, y, clip }) {
  await page.touchscreen.tap(
    clip ? clip.x + x : x,
    clip ? clip.y + y : y
  );
};

• В качестве surface используй page или mobilePage для веба либо appWindow для Electron.
• Считай clip значениями в CSS-пикселях из getBoundingClientRect() в рендерере.
• Предпочитай JPEG с quality: 85, если не требуется несжатое качество.
• Для снимков целиком используй возвращённые { x, y } напрямую.
• Для снимков части экрана при клике прибавляй начало области (clip).

Нормализация CSS для веба

Предпочтительный путь для веба в контекстах с явным viewport, а часто и для веба вообще:

await emitWebJpeg(page);

Для мобильного веба путь тот же; подставь mobilePage вместо page:

await emitWebJpeg(mobilePage);

Если модель возвращает { x, y }, кликай по ним напрямую:

await clickCssPoint({ surface: page, x, y });

Путь клика для мобильного веба:

await tapCssPoint({ page: mobilePage, x, y });

Для снимков области (clip) и снимков элементов на этом обычном пути scale: "css" обычно работает напрямую. При клике прибавляй начало области.

• await emitWebJpeg(page, { clip })
• await emitWebJpeg(mobilePage, { clip })
• await clickCssPoint({ surface: page, clip, x, y })
• await tapCssPoint({ page: mobilePage, clip, x, y })
• await clickCssPoint({ surface: page, clip: box, x, y }) после const box = await locator.boundingBox()

Запасной вариант для веба в режиме родного окна, когда scale: "css" всё равно возвращает размер в пикселях устройства:

var emitWebScreenshotCssScaled = async function ({ page, clip, quality = 0.85 } = {}) {
  var NodeBuffer = (await import("node:buffer")).Buffer;
  const target = clip
    ? { width: clip.width, height: clip.height }
    : await page.evaluate(() => ({
        width: window.innerWidth,
        height: window.innerHeight,
      }));

  const screenshotBuffer = await page.screenshot({
    type: "png",
    ...(clip ? { clip } : {}),
  });

  const bytes = await page.evaluate(
    async ({ imageBase64, targetWidth, targetHeight, quality }) => {
      const image = new Image();
      image.src = `data:image/png;base64,${imageBase64}`;
      await image.decode();

      const canvas = document.createElement("canvas");
      canvas.width = targetWidth;
      canvas.height = targetHeight;

      const ctx = canvas.getContext("2d");
      ctx.imageSmoothingEnabled = true;
      ctx.drawImage(image, 0, 0, targetWidth, targetHeight);

      const blob = await new Promise((resolve) =>
        canvas.toBlob(resolve, "image/jpeg", quality)
      );

      return new Uint8Array(await blob.arrayBuffer());
    },
    {
      imageBase64: NodeBuffer.from(screenshotBuffer).toString("base64"),
      targetWidth: target.width,
      targetHeight: target.height,
      quality,
    }
  );

  await emitJpeg(bytes);
};

Для запасного снимка всего viewport считай возвращённые { x, y } прямыми CSS-координатами:

await emitWebScreenshotCssScaled({ page });
await clickCssPoint({ surface: page, x, y });

Для запасного снимка области прибавляй начало области:

await emitWebScreenshotCssScaled({ page, clip });
await clickCssPoint({ surface: page, clip, x, y });

Нормализация CSS для Electron

Для Electron нормализуй в главном процессе, а не открывай временную страницу Playwright. Вспомогательная функция ниже возвращает байты в масштабе CSS для всей области содержимого или для вырезанной области в CSS-пикселях. Считай clip CSS-пикселями области содержимого, например значениями из getBoundingClientRect() в рендерере.

var emitElectronScreenshotCssScaled = async function ({ electronApp, clip, quality = 85 } = {}) {
  const bytes = await electronApp.evaluate(async ({ BrowserWindow }, { clip, quality }) => {
    const win = BrowserWindow.getAllWindows()[0];
    const image = clip ? await win.capturePage(clip) : await win.capturePage();

    const target = clip
      ? { width: clip.width, height: clip.height }
      : (() => {
          const [width, height] = win.getContentSize();
          return { width, height };
        })();

    const resized = image.resize({
      width: target.width,
      height: target.height,
      quality: "best",
    });

    return resized.toJPEG(quality);
  }, { clip, quality });

  await emitJpeg(bytes);
};

Всё окно Electron:

await emitElectronScreenshotCssScaled({ electronApp });
await clickCssPoint({ surface: appWindow, x, y });

Вырезанная область Electron в CSS-пикселях из рендерера:

var clip = await appWindow.evaluate(() => {
  const rect = document.getElementById("board").getBoundingClientRect();
  return {
    x: Math.round(rect.x),
    y: Math.round(rect.y),
    width: Math.round(rect.width),
    height: Math.round(rect.height),
  };
});

await emitElectronScreenshotCssScaled({ electronApp, clip });
await clickCssPoint({ surface: appWindow, clip, x, y });

Примеры необработанных снимков (исключение)

Используй их только когда необработанные пиксели важнее совпадения CSS-координат: например, при отладке артефактов Retina или DPI, при попиксельной проверке отрисовки или в другом случае, где важна точность.

Необработанный вывод для настольного веба:

await codex.emitImage({
  bytes: await page.screenshot({ type: "jpeg", quality: 85 }),
  mimeType: "image/jpeg",
  detail: "original",
});

Необработанный вывод для Electron:

await codex.emitImage({
  bytes: await appWindow.screenshot({ type: "jpeg", quality: 85 }),
  mimeType: "image/jpeg",
  detail: "original",
});

Необработанный вывод для мобильного веба, когда мобильный веб-контекст уже запущен:

await codex.emitImage({
  bytes: await mobilePage.screenshot({ type: "jpeg", quality: 85 }),
  mimeType: "image/jpeg",
  detail: "original",
});

Проверки помещения в viewport (обязательны)

Не считай снимок приемлемым только потому, что виден главный виджет. Перед приёмкой явно проверь, что предполагаемый начальный вид соответствует требованию к продукту, используя и просмотр снимков, и числовые проверки.

• До приёмки определи, каким должен быть начальный вид. Для прокручиваемых страниц это то, что видно без прокрутки. Для приложений-оболочек, игр, редакторов, дашбордов и инструментов это вся интерактивная поверхность вместе с элементами управления и статусом, нужными для работы.
• Главным доказательством помещения считай снимки экрана. Числовые проверки их поддерживают, но не отменяют видимую обрезку.
• Приёмка не пройдена, если любая обязательная видимая область обрезана, перекрыта или вытолкнута за пределы viewport в предполагаемом начальном виде, даже если показатели прокрутки страницы выглядят приемлемо.
• Прокрутка допустима, если продукт рассчитан на прокрутку, а начальный вид всё равно передаёт основной смысл и показывает главный призыв к действию или нужный стартовый контекст.
• Для интерфейсов с фиксированной оболочкой прокрутка не годится как обходной путь, если она нужна, чтобы добраться до части основной интерактивной поверхности или важных элементов управления.
• Не полагайся только на показатели прокрутки документа. Оболочки с фиксированной высотой, внутренние панели и контейнеры со скрытым переполнением могут обрезать нужные элементы интерфейса, пока проверки прокрутки на уровне страницы выглядят чистыми.
• Проверяй границы областей, а не только границы документа. Убедись, что каждая обязательная видимая область помещается в viewport в стартовом состоянии.
• Для приложений Electron и настольных приложений проверяй и размер и положение запущенного окна, и начальную видимую раскладку рендерера — до любого ручного изменения размера или перемещения.
• Успешные проверки помещения доказывают только то, что предполагаемый начальный вид виден без нежелательной обрезки и прокрутки. Они не доказывают, что интерфейс визуально правилен или эстетически удачен.

Проверка для веба или рендерера:

console.log(await page.evaluate(() => ({
  innerWidth: window.innerWidth,
  innerHeight: window.innerHeight,
  clientWidth: document.documentElement.clientWidth,
  clientHeight: document.documentElement.clientHeight,
  scrollWidth: document.documentElement.scrollWidth,
  scrollHeight: document.documentElement.scrollHeight,
  canScrollX: document.documentElement.scrollWidth > document.documentElement.clientWidth,
  canScrollY: document.documentElement.scrollHeight > document.documentElement.clientHeight,
})));

Проверка для Electron:

console.log(await appWindow.evaluate(() => ({
  innerWidth: window.innerWidth,
  innerHeight: window.innerHeight,
  clientWidth: document.documentElement.clientWidth,
  clientHeight: document.documentElement.clientHeight,
  scrollWidth: document.documentElement.scrollWidth,
  scrollHeight: document.documentElement.scrollHeight,
  canScrollX: document.documentElement.scrollWidth > document.documentElement.clientWidth,
  canScrollY: document.documentElement.scrollHeight > document.documentElement.clientHeight,
})));

Дополни числовую проверку проверками getBoundingClientRect() для обязательных видимых областей в твоём конкретном интерфейсе, когда обрезка — реалистичный риск; одних показателей на уровне документа недостаточно для фиксированных оболочек.

Сервер разработки

Для локальной веб-отладки держи приложение запущенным в постоянной TTY-сессии. Не полагайся на однократные фоновые команды из недолговечной оболочки.

Используй обычную команду запуска проекта, например:

npm start

Перед page.goto(...) убедись, что выбранный порт прослушивается и приложение отвечает.

При отладке Electron запускай приложение из js_repl через _electron.launch(...), чтобы процессом владела та же сессия. Если рендерер Electron зависит от отдельного сервера разработки (например, Vite или Next), держи этот сервер запущенным в постоянной TTY-сессии, а затем перезапускай или перезагружай приложение Electron из js_repl.

Очистка

Выполняй очистку, только когда задача действительно закончена:

• Эта очистка ручная. Выход из Codex, закрытие терминала или потеря сессии js_repl не выполняют неявно electronApp.close(), context.close() или browser.close().
• Для Electron в частности исходи из того, что приложение может продолжать работать, если ты покинешь сессию, не выполнив ячейку очистки.

if (electronApp) {
  await electronApp.close().catch(() => {});
}

if (mobileContext) {
  await mobileContext.close().catch(() => {});
}

if (context) {
  await context.close().catch(() => {});
}

if (browser) {
  await browser.close().catch(() => {});
}

browser = undefined;
context = undefined;
page = undefined;
mobileContext = undefined;
mobilePage = undefined;
electronApp = undefined;
appWindow = undefined;

console.log("Playwright session closed");

Если ты собираешься выйти из Codex сразу после отладки, сначала выполни ячейку очистки и дождись записи "Playwright session closed" в журнале, а потом выходи.

Частые сбои

• Cannot find module 'playwright': выполни разовую настройку в текущем рабочем пространстве и проверь импорт, прежде чем использовать js_repl.
• Пакет Playwright установлен, но исполняемый файл браузера отсутствует: выполни npx playwright install chromium.
• page.goto: net::ERR_CONNECTION_REFUSED: убедись, что сервер разработки всё ещё работает в постоянной TTY-сессии, перепроверь порт и предпочитай http://127.0.0.1:<port>.
• electron.launch зависает, истекает по времени или сразу завершается: проверь локальную зависимость electron, подтверди цель в args и убедись, что любой сервер разработки рендерера уже запущен до старта.
• Identifier has already been declared: используй существующие привязки верхнего уровня, выбери новое имя или оберни код в { ... }. Используй js_repl_reset, только если ядро действительно зависло.
• browserContext.newPage: Protocol error (Target.createTarget): Not supported при работе с Electron: не используй appWindow.context().newPage() или electronApp.context().newPage() как временную страницу; применяй путь нормализации снимков, специфичный для Electron, из раздела о снимках для модели.
• js_repl истёк по времени или сброшен: заново выполни ячейку начальной настройки и пересоздай сессию более короткими и целевыми ячейками.
• Запуск браузера или сетевые операции сразу падают: убедись, что сессия была запущена с --sandbox danger-full-access, и при необходимости перезапусти её так.

Перевод: iiuniversitet. Оригинал: https://github.com/openai/skills/tree/main/skills/.curated/playwright-interactive, лицензия Apache-2.0. Изменения: перевод на русский язык.