chrome.debugger

Описание

API chrome.debugger служит альтернативным транспортом для протокола удаленной отладки Chrome. Используйте chrome.debugger для подключения к одной или нескольким вкладкам для управления сетевым взаимодействием, отладки JavaScript, изменения DOM и CSS и многого другого. Используйте свойство tabId Debuggee для выбора вкладок с помощью sendCommand и маршрутизации событий по tabId из обратных вызовов onEvent .

Разрешения

debugger

Чтобы использовать этот API, вы должны объявить разрешение "debugger" в манифесте вашего расширения.

{
  "name": "My extension",
  ...
  "permissions": [
    "debugger",
  ],
  ...
}

Концепции и использование

После подключения API chrome.debugger позволяет отправлять команды протокола Chrome DevTools (CDP) заданной цели. Подробное объяснение CDP выходит за рамки данной документации — чтобы узнать больше о CDP, ознакомьтесь с официальной документацией CDP .

Цели

Цели представляют собой что-то, что отлаживается — это может быть вкладка, iframe или рабочий процесс. Каждая цель идентифицируется UUID и имеет связанный тип (например, iframe , shared_worker и т. д.).

Внутри цели может существовать несколько контекстов выполнения — например, iframe одного и того же процесса не получает уникальную цель, а вместо этого представляется как разные контексты, к которым можно получить доступ из одной цели.

Ограниченные домены

По соображениям безопасности API chrome.debugger не предоставляет доступ ко всем доменам протокола Chrome DevTools. Доступные домены: доступность , аудит , CacheStorage , консоль , CSS , база данных , отладчик , DOM , DOMDebugger , DOMSnapshot , эмуляция , выборка, ввод- вывод , ввод , инспектор , журнал , сеть , наложение , страница , производительность , профилировщик , среда выполнения , хранилище. , Target , Tracing , WebAudio и WebAuthn .

Работа с фреймами

Не существует однозначного сопоставления кадров с целями. В пределах одной вкладки несколько одних и тех же кадров процесса могут иметь одну и ту же цель, но использовать другой контекст выполнения . С другой стороны, новая цель может быть создана для iframe вне процесса.

Чтобы прикрепить ко всем рамам, нужно обрабатывать каждый тип рамок отдельно:

  • Прослушивайте событие Runtime.executionContextCreated , чтобы определить новые контексты выполнения, связанные с теми же кадрами процесса.

  • Следуйте инструкциям по прикреплению к связанным целям для выявления кадров, находящихся вне процесса.

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

Начиная с Chrome 125, API chrome.debugger поддерживает плоские сеансы. Это позволяет вам добавлять дополнительные цели в качестве дочерних в основной сеанс отладчика и отправлять им сообщения без необходимости повторного вызова chrome.debugger.attach . Вместо этого вы можете добавить свойство sessionId при вызове chrome.debugger.sendCommand , чтобы идентифицировать дочернюю цель, которой вы хотите отправить команду.

Чтобы автоматически присоединяться к дочерним кадрам вне процесса, сначала добавьте прослушиватель события Target.attachedToTarget :

chrome.debugger.onEvent.addListener((source, method, params) => {
  if (method === "Target.attachedToTarget") {
    // `source` identifies the parent session, but we need to construct a new
    // identifier for the child session
    const session = { ...source, sessionId: params.sessionId };

    // Call any needed CDP commands for the child session
    await chrome.debugger.sendCommand(session, "Runtime.enable");
  }
});

Затем включите автоматическое присоединение , отправив команду Target.setAutoAttach с параметром flatten , установленным в значение true :

await chrome.debugger.sendCommand({ tabId }, "Target.setAutoAttach", {
  autoAttach: true,
  waitForDebuggerOnStart: false,
  flatten: true,
  filter: [{ type: "iframe", exclude: false }]
});

Примеры

Чтобы попробовать этот API, установите пример API отладчика из репозитория chrome-extension-samples .

Типы

Debuggee

Идентификатор отладчика. Необходимо указать tabId, ExtensionId или TargetId.

Характеристики

  • идентификатор расширения

    строка необязательна

    Идентификатор расширения, которое вы собираетесь отлаживать. Присоединение к фоновой странице расширения возможно только при использовании переключателя командной строки --silent-debugger-extension-api .

  • идентификатор табуляции

    номер необязательно

    Идентификатор вкладки, которую вы собираетесь отлаживать.

  • идентификатор цели

    строка необязательна

    Непрозрачный идентификатор цели отладки.

DebuggerSession

Хром 125+

Идентификатор сеанса отладчика. Необходимо указать один из tabId, ExtensionId или TargetId. Кроме того, можно указать необязательный идентификатор сеанса. Если sessionId указан для аргументов, отправленных из onEvent , это означает, что событие поступает из сеанса дочернего протокола в сеансе корневого отлаживаемого объекта. Если sessionId указан при передаче sendCommand , он нацелен на сеанс дочернего протокола в сеансе корневого отлаживаемого объекта.

Характеристики

  • идентификатор расширения

    строка необязательна

    Идентификатор расширения, которое вы собираетесь отлаживать. Присоединение к фоновой странице расширения возможно только при использовании переключателя командной строки --silent-debugger-extension-api .

  • идентификатор сеанса

    строка необязательна

    Непрозрачный идентификатор сеанса протокола Chrome DevTools. Идентифицирует дочерний сеанс в корневом сеансе, указанном tabId, ExtensionId или TargetId.

  • идентификатор табуляции

    номер необязательно

    Идентификатор вкладки, которую вы собираетесь отлаживать.

  • идентификатор цели

    строка необязательна

    Непрозрачный идентификатор цели отладки.

DetachReason

Хром 44+

Причина прекращения соединения.

Перечисление

"target_closed"

"cancelled_by_user"

TargetInfo

Отладка целевой информации

Характеристики

  • прикрепил

    логическое значение

    True, если отладчик уже подключен.

  • идентификатор расширения

    строка необязательна

    Идентификатор расширения, определенный, если type = 'background_page'.

  • faviconUrl

    строка необязательна

    Целевой URL-адрес значка.

  • идентификатор

    нить

    Идентификатор цели.

  • идентификатор табуляции

    номер необязательно

    Идентификатор вкладки, определенный, если type == 'page'.

  • заголовок

    нить

    Заголовок целевой страницы.

  • Тип цели.

  • URL

    нить

    Целевой URL.

TargetInfoType

Хром 44+

Тип цели.

Перечисление

"страница"

"фоновая_страница"

"работник"

"другой"

Методы

attach()

Обещать
chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
  callback?: function,
)

Присоединяет отладчик к заданной цели.

Параметры

  • Цель отладки, к которой вы хотите подключиться.

  • требуемая версия

    нить

    Требуемая версия протокола отладки («0.1»). К отлаживаемому продукту можно подключиться только с соответствующей основной версией и большей или равной младшей версией. Список версий протокола можно получить здесь .

  • перезвонить

    функция необязательна

    Параметр callback выглядит так:

    () => void

Возврат

  • Обещание<void>

    Хром 96+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

detach()

Обещать
chrome.debugger.detach(
  target: Debuggee,
  callback?: function,
)

Отключает отладчик от заданной цели.

Параметры

  • Цель отладки, от которой вы хотите отсоединиться.

  • перезвонить

    функция необязательна

    Параметр callback выглядит так:

    () => void

Возврат

  • Обещание<void>

    Хром 96+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

getTargets()

Обещать
chrome.debugger.getTargets(
  callback?: function,
)

Возвращает список доступных целей отладки.

Параметры

  • перезвонить

    функция необязательна

    Параметр callback выглядит так:

    (result: TargetInfo[]) => void

    • результат

      Массив объектов TargetInfo, соответствующих доступным целям отладки.

Возврат

  • Обещание< TargetInfo []>

    Хром 96+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

sendCommand()

Обещать
chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
  callback?: function,
)

Отправляет данную команду в цель отладки.

Параметры

  • Цель отладки, которой вы хотите отправить команду.

  • метод

    нить

    Имя метода. Должен быть одним из методов, определенных протоколом удаленной отладки .

  • командаПарамс

    объект необязательный

    Объект JSON с параметрами запроса. Этот объект должен соответствовать схеме параметров удаленной отладки для данного метода.

  • перезвонить

    функция необязательна

    Параметр callback выглядит так:

    (result?: object) => void

    • результат

      объект необязательный

      JSON-объект с ответом. Структура ответа варьируется в зависимости от имени метода и определяется атрибутом return описания команды в протоколе удаленной отладки.

Возврат

  • Обещание<объект | не определено>

    Хром 96+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

События

onDetach

chrome.debugger.onDetach.addListener(
  callback: function,
)

Вызывается, когда браузер завершает сеанс отладки для вкладки. Это происходит, когда вкладка закрывается или для прикрепленной вкладки вызывается Chrome DevTools.

Параметры

onEvent

chrome.debugger.onEvent.addListener(
  callback: function,
)

Вызывается всякий раз, когда цель отладки выдает событие инструментирования.

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так:

    (source: DebuggerSession, method: string, params?: object) => void