chrome.debugger

Описание

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

Разрешения

debugger

Для использования этого API необходимо указать разрешение "debugger" в манифесте вашего расширения.

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

Понятия и применение

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

Цели

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

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

Запрещенные домены

В целях безопасности API chrome.debugger не предоставляет доступ ко всем доменам протокола Chrome DevTools. Доступные домены: Accessibility , Audits , CacheStorage , Console , CSS , Database , Debugger , DOM , DOMDebugger , DOMSnapshot , Emulation , Fetch , IO , Input , Inspector , Log , Network , Overlay , Page , Performance , Profiler , Runtime , Storage , 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 }]
});

Auto-attach only attaches to frames the target is aware of, which is limited to frames which are immediate children of a frame associated with it. For example, with the frame hierarchy A -> B -> C (where all are cross-origin), calling Target.setAutoAttach for the target associated with A would result in the session also being attached to B. However, this is not recursive, so Target.setAutoAttach also needs to be called for B to attach the session to C.

Примеры

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

Типы

Debuggee

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

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

  • extensionId

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

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

  • tabId

    число необязательно

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

  • targetId

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

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

DebuggerSession

Chrome 125+

Идентификатор сессии отладчика. Необходимо указать один из параметров: tabId, extensionId или targetId. Дополнительно можно указать необязательный sessionId. Если sessionId указан для аргументов, отправляемых из onEvent , это означает, что событие поступает из дочерней сессии протокола внутри корневой сессии отладчика. Если sessionId указан при передаче в sendCommand , он указывает на дочернюю сессию протокола внутри корневой сессии отладчика.

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

  • extensionId

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

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

  • sessionId

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

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

  • tabId

    число необязательно

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

  • targetId

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

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

DetachReason

Chrome 44+

Причина разрыва соединения.

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

"target_closed"

"отменено_пользователем"

TargetInfo

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

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

  • прикрепил

    логический

    Возвращает true, если отладчик уже подключен.

  • extensionId

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

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

  • faviconUrl

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

    Целевой URL значка сайта.

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

    нить

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

  • tabId

    число необязательно

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

  • заголовок

    нить

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

  • Тип цели.

  • url

    нить

    Целевой URL.

TargetInfoType

Chrome 44+

Тип цели.

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

"страница"

"background_page"

«рабочий»

"другой"

Методы

attach()

chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
): Promise<void>

Подключает отладчик к указанному целевому объекту.

Параметры

  • цель

    Дебагги

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

  • requiredVersion

    нить

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

Возвраты

  • Обещание<пустота>

    Chrome 96+

    Промис разрешается после успешного или неудачного завершения операции прикрепления. Промис разрешается без значения. Если прикрепление не удается, промис будет отклонен.

detach()

chrome.debugger.detach(
  target: Debuggee,
): Promise<void>

Отключает отладчик от заданного целевого объекта.

Параметры

  • цель

    Дебагги

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

Возвраты

  • Обещание<пустота>

    Chrome 96+

    Решается после успешного или неудачного завершения операции отсоединения. Промис завершается без значения. Если отсоединение не удается, промис будет отклонен.

getTargets()

chrome.debugger.getTargets(): Promise<TargetInfo[]>

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

Возвраты

sendCommand()

chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
): Promise<object | undefined>

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

Параметры

  • цель

    DebuggerSession

    Укажите целевой объект отладки, которому вы хотите отправить команду.

  • метод

    нить

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

  • commandParams

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

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

Возвраты

  • Promise<object | undefined>

    Chrome 96+

    Тело ответа. Если при отправке сообщения произойдет ошибка, промис будет отклонен.

События

onDetach

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

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

Параметры

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

    функция

    Параметр callback выглядит следующим образом: 

    (source: Debuggee, reason: DetachReason) => void

onEvent

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

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

Параметры

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

    функция

    Параметр callback выглядит следующим образом: 

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

    • источник

      DebuggerSession

    • метод

      нить

    • параметры

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