Как построить самопроверяющегося браузерного агента на Claude Code и MegaIndex Browser API

Чего не хватает обычному процессу разработки с Claude Code

Обновлен сценарий авторизации.
Исправлена работа с селекторами.
Добавлены повторные попытки.
Все тесты пройдены.

• тесты запускались только на подготовленном HTML;
• реальный сайт перенаправил браузер на страницу входа;
• сценарий открылся с другим профилем;
• пользовательский прокси не был применен;
• селектор нашел элемент в DOM, но элемент оказался скрытым;
• экстрактор вернул неполные записи;
• после ошибки браузерная сессия осталась открытой;
• тест изменили так, чтобы он принимал неправильное поведение.

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

Сначала опишите браузерный контракт

• начальный URL;
• используемый браузерный профиль;
• требования к прокси;
• признаки успешной загрузки страницы;
• последовательность действий;
• структуру результата;
• минимальное количество записей;
• обязательные поля;
• правила закрытия сессии;
• артефакты, которые нужно сохранить.

Сценарий: извлечение товаров из авторизованной сессии

Входные данные:
- целевой URL;
- необязательный ID браузерного профиля;
- необязательный пользовательский прокси;
- ожидаемое имя учетной записи.

Успешный результат:
- соединение с MegaIndex BrowserAPI установлено;
- целевая страница открылась без перенаправления на форму входа;
- на странице отображается ожидаемое имя учетной записи;
- найдено не менее пяти карточек товаров;
- у каждого товара есть название, URL, цена и идентификатор;
- сохранены JSON-результат, скриншот и HTML;
- браузерная сессия закрыта независимо от результата.

Ошибка:
- открылась страница входа;
- обнаружена страница проверки;
- имя учетной записи не совпадает;
- найдено меньше пяти товаров;
- отсутствует обязательное поле;
- браузерная сессия не закрыта.

Не объединяйте выполнение и проверку

src/
├── browser/
│   ├── connect-browser.js
│   ├── create-session.js
│   └── close-session.js
├── workflows/
│   └── collect-products.js
├── validation/
│   └── validate-products.js
└── artifacts/
    └── save-run-artifacts.js

scripts/
└── verify-product-workflow.mjs

• форму входа;
• страницу с отказом в доступе;
• региональное перенаправление;
• пустой список результатов;
• страницу проверки;
• частично загруженный интерфейс.

Подключение проверки к MegaIndex BrowserAPI

npm install --save-dev playwright-core

import fs from "node:fs/promises";
import process from "node:process";
import { chromium } from "playwright-core";

const browserEndpoint =
  process.env.MEGAINDEX_BROWSER_WS_ENDPOINT;

const targetUrl =
  process.env.BROWSER_TEST_URL;

const expectedAccount =
  process.env.BROWSER_EXPECTED_ACCOUNT;

const artifactDirectory =
  process.env.BROWSER_ARTIFACT_DIRECTORY ?? "artifacts";

const minimumProducts = Number.parseInt(
  process.env.BROWSER_MINIMUM_PRODUCTS ?? "5",
  10,
);

if (!browserEndpoint) {
  throw new Error(
    "MEGAINDEX_BROWSER_WS_ENDPOINT is required",
  );
}

if (!targetUrl) {
  throw new Error(
    "BROWSER_TEST_URL is required",
  );
}

if (!expectedAccount) {
  throw new Error(
    "BROWSER_EXPECTED_ACCOUNT is required",
  );
}

if (
  !Number.isInteger(minimumProducts) ||
  minimumProducts < 1
) {
  throw new Error(
    "BROWSER_MINIMUM_PRODUCTS must be a positive integer",
  );
}

await fs.mkdir(artifactDirectory, {
  recursive: true,
});

const resultPath =
  `${artifactDirectory}/browser-result.json`;

const screenshotPath =
  `${artifactDirectory}/browser-page.png`;

const pageHtmlPath =
  `${artifactDirectory}/browser-page.html`;

let browser;
let page;

const startedAt = new Date().toISOString();

try {
  browser = await chromium.connectOverCDP(
    browserEndpoint,
  );

  const context =
    browser.contexts()[0] ??
    await browser.newContext();

  page =
    context.pages()[0] ??
    await context.newPage();

  const response = await page.goto(
    targetUrl,
    {
      waitUntil: "domcontentloaded",
      timeout: 60000,
    },
  );

  if (!response) {
    throw new Error(
      "Navigation returned no HTTP response",
    );
  }

  if (!response.ok()) {
    throw new Error(
      `Navigation failed with HTTP status ${response.status()}`,
    );
  }

  await page
    .locator("[data-account-name]")
    .waitFor({
      state: "visible",
      timeout: 30000,
    });

  const accountName = (
    await page
      .locator("[data-account-name]")
      .first()
      .textContent()
  )?.trim() ?? "";

  if (accountName !== expectedAccount) {
    throw new Error(
      `Unexpected account. Expected "${expectedAccount}", received "${accountName}"`,
    );
  }

  const loginFormVisible = await page
    .locator(
      "form[action*='login'], input[type='password']",
    )
    .first()
    .isVisible()
    .catch(() => false);

  if (loginFormVisible) {
    throw new Error(
      "The browser was redirected to a login page",
    );
  }

  const challengeVisible = await page
    .locator(
      "[data-captcha], iframe[src*='captcha'], iframe[src*='challenge']",
    )
    .first()
    .isVisible()
    .catch(() => false);

  if (challengeVisible) {
    throw new Error(
      "A challenge page was detected instead of the target content",
    );
  }

  const products = await page
    .locator("[data-product]")
    .evaluateAll((elements) =>
      elements.map((element) => ({
        title:
          element
            .querySelector("[data-title]")
            ?.textContent
            ?.trim() ?? "",
        price:
          element
            .querySelector("[data-price]")
            ?.textContent
            ?.trim() ?? "",
        url:
          element
            .querySelector("a")
            ?.href ?? "",
        id:
          element.getAttribute(
            "data-product-id",
          ) ?? "",
      })),
    );

  if (products.length < minimumProducts) {
    throw new Error(
      `Expected at least ${minimumProducts} products, received ${products.length}`,
    );
  }

  const invalidProduct = products.find(
    (product) =>
      !product.title ||
      !product.price ||
      !product.url ||
      !product.id,
  );

  if (invalidProduct) {
    throw new Error(
      `Invalid product record: ${JSON.stringify(invalidProduct)}`,
    );
  }

  await page.screenshot({
    path: screenshotPath,
    fullPage: true,
  });

  await fs.writeFile(
    pageHtmlPath,
    await page.content(),
    "utf8",
  );

  const result = {
    passed: true,
    startedAt,
    finishedAt: new Date().toISOString(),
    requestedUrl: targetUrl,
    finalUrl: page.url(),
    title: await page.title(),
    httpStatus: response.status(),
    accountName,
    productCount: products.length,
    products,
    artifacts: {
      screenshotPath,
      pageHtmlPath,
    },
  };

  await fs.writeFile(
    resultPath,
    `${JSON.stringify(result, null, 2)}\n`,
    "utf8",
  );

  console.log(
    JSON.stringify(result),
  );
} catch (error) {
  if (page) {
    await page
      .screenshot({
        path: screenshotPath,
        fullPage: true,
      })
      .catch(() => undefined);

    await fs
      .writeFile(
        pageHtmlPath,
        await page.content(),
        "utf8",
      )
      .catch(() => undefined);
  }

  const result = {
    passed: false,
    startedAt,
    finishedAt: new Date().toISOString(),
    error:
      error instanceof Error
        ? error.message
        : String(error),
    finalUrl: page?.url() ?? null,
    artifacts: {
      screenshotPath,
      pageHtmlPath,
    },
  };

  await fs.writeFile(
    resultPath,
    `${JSON.stringify(result, null, 2)}\n`,
    "utf8",
  );

  console.error(
    JSON.stringify(result),
  );

  process.exitCode = 1;
} finally {
  await browser
    ?.close()
    .catch(() => undefined);
}

• HTTP-статус ответа;
• открытую учетную запись;
• отсутствие формы входа;
• отсутствие страницы проверки;
• минимальное количество товаров;
• наличие обязательных полей;
• сохранение скриншота и HTML;
• закрытие браузера в блоке finally.

Сохраняйте артефакты каждого запуска

Selector timeout after 30000 ms

• конечный URL;
• заголовок страницы;
• скриншот;
• HTML;
• сетевые ошибки;
• состояние авторизации;
• полученные записи.

Разделяйте ошибки по типам

• открыта другая учетная запись;
• селектор указывает на неправильный элемент;
• загружена страница проверки;
• результат не соответствует схеме;
• повторное действие может создать дубликат.

Создайте отдельный skill для браузерной проверки

.claude/skills/verify-browser-workflow/SKILL.md

---
name: verify-browser-workflow
description: Использовать после изменений в подключении к MegaIndex BrowserAPI, навигации Playwright или Puppeteer, браузерных профилях, прокси, сессиях, селекторах, извлечении данных, повторных попытках и браузерных тестах.
---

# Проверка браузерного сценария

1. Изучи текущий git diff.
2. Определи, какие браузерные сценарии затронуты.
3. Проверь изменения в управлении сессией, выборе профиля, приоритете прокси и закрытии браузера.
4. Запусти модульные тесты, линтер и проверку типов.
5. Запусти затронутый сценарий через MegaIndex BrowserAPI.
6. Изучи JSON-результат, скриншот и сохраненный HTML.
7. Подтверди:
   - открыта ожидаемая страница;
   - состояние авторизации корректно;
   - страница входа, проверки или ошибки не принята за целевой контент;
   - записи соответствуют контракту результата;
   - браузерная сессия закрыта;
   - тесты не были удалены, пропущены или ослаблены.
8. Укажи выполненные команды, коды завершения, созданные артефакты, изменения тестов и итоговый результат.

Запретите завершение работы при неудачной проверке

.claude/hooks/verify-browser-before-stop.sh

#!/usr/bin/env bash

set -uo pipefail

FAILED=0

run_check() {
  local name="$1"
  shift

  echo "Running ${name}..."

  if "$@"; then
    echo "${name}: passed"
  else
    echo "${name}: failed" >&2
    FAILED=1
  fi
}

run_check \
  "unit tests" \
  npm test

run_check \
  "lint" \
  npm run lint

run_check \
  "type checking" \
  npm run typecheck

run_check \
  "MegaIndex BrowserAPI verification" \
  npm run verify:browser

if [[ "$FAILED" -ne 0 ]]; then
  echo "Browser acceptance checks failed. Inspect the artifacts and continue working." >&2
  exit 2
fi

echo "All browser acceptance checks passed."
exit 0

.claude/settings.json

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/verify-browser-before-stop.sh",
            "timeout": 600
          }
        ]
      }
    ]
  }
}

Не перегружайте CLAUDE.md

# Правила проекта MegaIndex BrowserAPI

- Используй существующий модуль подключения к BrowserAPI.
- Получай параметры подключения только из переменных окружения.
- Не выводи и не сохраняй WebSocket-адреса, cookies, токены и пароли прокси.
- Явно определяй, какой модуль отвечает за закрытие браузерной сессии.
- Закрывай удаленную сессию после успешного выполнения и после ошибки.
- Пользовательский прокси имеет приоритет над прокси браузерного профиля.
- Не повторяй действия, которые могут создать дублирующий внешний эффект.
- Не заменяй ожидание событий фиксированными задержками.
- Не принимай страницы входа, проверки и ошибки за целевой контент.
- Не удаляй, не пропускай и не ослабляй тесты ради успешного результата.
- Изменение браузерного кода считается завершенным только после удаленной проверки.

Проведите финальную проверку в новой сессии

Проведи независимую проверку текущего diff как специалист по браузерной автоматизации.

Не изменяй файлы.

Проверь:

1. Управление подключением к MegaIndex BrowserAPI.
2. Закрытие браузера после успешного выполнения и ошибки.
3. Приоритет браузерного профиля и пользовательского прокси.
4. Проверку состояния авторизации.
5. Ограничения повторных попыток.
6. Действия, которые нельзя безопасно повторять.
7. Обнаружение страниц входа, проверки и ошибки.
8. Валидацию извлеченных данных.
9. Изменения тестов, ослабляющие существующие гарантии.
10. Возможную утечку учетных данных.
11. Доказывают ли сохраненные артефакты выполнение браузерного контракта.

Верни только конкретные замечания с путями к файлам и объяснением причин.

• авторизацией;
• платежами;
• изменением учетной записи;
• повторным использованием сессий;
• маршрутизацией прокси;
• массовым извлечением данных;
• работой с несколькими сайтами.

Запуск проверки в CI

set -euo pipefail

npm test
npm run lint
npm run typecheck
npm run verify:browser

claude -p \
  --permission-mode plan \
  --output-format json \
  --max-turns 5 \
  "Проверь текущий diff на наличие регрессий в BrowserAPI. Проверь управление сессиями, закрытие браузера, приоритет профиля и прокси, состояние авторизации, повторные попытки, валидацию извлеченных данных, ослабление тестов, утечки секретов и созданные артефакты." \
  > artifacts/claude-browser-review.json

Рекомендуемая структура проекта

project/
├── CLAUDE.md
├── .claude/
│   ├── settings.json
│   ├── hooks/
│   │   └── verify-browser-before-stop.sh
│   └── skills/
│       └── verify-browser-workflow/
│           ├── SKILL.md
│           └── reference.md
├── scripts/
│   └── verify-product-workflow.mjs
├── src/
│   ├── browser/
│   ├── workflows/
│   ├── validation/
│   └── artifacts/
├── tests/
├── artifacts/
└── package.json

• CLAUDE.md — постоянные правила проекта;
• skills — инструкции для повторяемых задач;
• hooks — обязательные проверки перед завершением работы;
• scripts — реальные сценарии проверки через MegaIndex BrowserAPI;
• artifacts — JSON, скриншоты, HTML и другие данные запуска;
• tests — локальные тесты и проверки браузерных контрактов.

Промпт для настройки самопроверяющегося процесса

Изучи этот репозиторий и создай самопроверяющийся процесс для автоматизации на базе MegaIndex BrowserAPI.

Не раскрывай учетные данные.

1. Найди существующий код, связанный с:
   - подключением к BrowserAPI;
   - управлением браузерной сессией;
   - профилями;
   - прокси;
   - извлечением данных;
   - закрытием ресурсов.

2. Определи браузерный контракт для основного сценария:
   - входные данные;
   - ожидаемое состояние авторизации;
   - ожидаемое состояние страницы;
   - минимальный результат;
   - обязательные поля;
   - условия ошибки;
   - требования к закрытию сессии;
   - сохраняемые артефакты.

3. Создай verification-скрипт, который:
   - получает endpoint BrowserAPI из переменной окружения;
   - подключается по CDP;
   - запускает основной сценарий;
   - отклоняет страницы входа, проверки и ошибки;
   - проверяет извлеченные данные;
   - сохраняет JSON, скриншот и HTML;
   - закрывает браузер после успешного выполнения и после ошибки;
   - возвращает ненулевой код, если контракт не выполнен.

4. Создай skill Claude Code для изменений, затрагивающих:
   - подключения к BrowserAPI;
   - сессии;
   - профили;
   - прокси;
   - навигацию;
   - селекторы;
   - извлечение данных;
   - повторные попытки;
   - браузерные тесты.

5. Создай Stop hook, который запускает:
   - модульные тесты;
   - линтер;
   - проверку типов;
   - проверку BrowserAPI.

   Если хотя бы одна обязательная проверка завершилась ошибкой, hook должен вернуть код 2.

6. Проверь текущий diff и подтверди:
   - тесты не удалены, не пропущены и не ослаблены;
   - учетные данные не могут попасть в логи;
   - браузер закрывается при любом результате;
   - повторные попытки не повторяют действия с внешними побочными эффектами.

Верни:
- браузерный контракт;
- список измененных файлов;
- выполненные команды;
- созданные артефакты;
- результат проверки;
- нерешенные риски.

Результат

Определить условия приемки
↓
Передать реализацию Claude
↓
Запустить сценарий через MegaIndex BrowserAPI
↓
Сохранить JSON, скриншот, HTML и результаты тестов
↓
Передать найденные ошибки обратно Claude
↓
Не разрешать завершение до успешной проверки
↓
Проверить итоговый diff в новой сессии