browser.debugger

설명

chrome.debugger API는 Chrome의 원격 디버깅 프로토콜의 대체 전송 역할을 합니다. chrome.debugger를 사용하여 하나 이상의 탭에 연결하여 네트워크 상호작용을 계측하고, JavaScript를 디버그하고, DOM 및 CSS를 변경하는 등의 작업을 수행합니다. Debuggee 속성 tabId를 사용하여 sendCommand로 탭을 타겟팅하고 onEvent 콜백에서 tabId로 이벤트를 라우팅합니다.

권한

debugger

이 API를 사용하려면 확장 프로그램의 매니페스트에서 "debugger" 권한을 선언해야 합니다.

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

엔터프라이즈 정책 제한사항

엔터프라이즈 기기에서는 일부 정책이 연결 시 올 오어 낫싱(all-or-nothing) 모델을 사용하여 확장 프로그램이 디버거를 연결하지 못하도록 제한할 수 있습니다(browser.debugger.attach()).

• 호스트 제한: 엔터프라이즈 정책 ExtensionSettings에서 확장 프로그램에 대해 차단된 호스트 (runtime_blocked_hosts)를 구성하는 경우 browser.debugger.attach()는 모든 타겟에서 "Host access is restricted by policy." 오류와 함께 차단됩니다(개별 출처가 runtime_allowed_hosts에 있는 경우에도 마찬가지).
• 스크린샷 및 DLP 정책: 엔터프라이즈 정책 DisableScreenshots에서 스크린샷 캡처를 사용 중지하거나 데이터 손실 방지 (DLP) 규칙이 대상에 적용되는 경우 browser.debugger.attach()가 "Screenshot capture is restricted by policy." 오류와 함께 실패합니다.

개념 및 사용법

연결되면 browser.debugger API를 사용하여 지정된 타겟에 Chrome DevTools 프로토콜(CDP) 명령어를 전송할 수 있습니다. CDP에 대한 자세한 설명은 이 문서의 범위를 벗어납니다. CDP에 대해 자세히 알아보려면 공식 CDP 문서를 확인하세요.

대상

타겟은 디버깅 중인 항목을 나타내며, 여기에는 탭, iframe 또는 작업자가 포함될 수 있습니다. 각 타겟은 UUID로 식별되며 연결된 유형 (예: iframe, shared_worker 등)이 있습니다.

타겟 내에 여러 실행 컨텍스트가 있을 수 있습니다. 예를 들어 동일한 프로세스 iframe은 고유한 타겟을 가져오지 않고 단일 타겟에서 액세스할 수 있는 다른 컨텍스트로 표현됩니다.

제한된 도메인

보안상의 이유로 browser.debugger API는 모든 Chrome DevTools 프로토콜 도메인에 대한 액세스를 제공하지 않습니다. 사용 가능한 도메인은 Accessibility, Audits, CacheStorage, Console, CSS, Database, Debugger, DOM, DOMDebugger, DOMSnapshot, Emulation, Fetch, IO, Input, Inspector, Log, Network, Overlay, Page, Performance, Runtime, Storage, Target, Tracing, WebAudio, WebAuthn입니다.

프레임 작업

프레임과 타겟 간에 일대일 매핑이 없습니다. 단일 탭 내에서 여러 동일한 프로세스 프레임이 동일한 타겟을 공유하지만 다른 실행 컨텍스트를 사용할 수 있습니다. 반면, 프로세스 외부 iframe에 대해 새 타겟이 생성될 수 있습니다.

모든 프레임에 연결하려면 각 프레임 유형을 별도로 처리해야 합니다.

• Runtime.executionContextCreated 이벤트를 수신 대기하여 동일한 프로세스 프레임과 연결된 새 실행 컨텍스트를 식별합니다.

• 관련 타겟에 연결하는 단계에 따라 out-of-process 프레임을 식별합니다.

관련 대상에 연결

대상에 연결한 후에는 out-of-process 하위 프레임 또는 연결된 작업자를 비롯한 추가 관련 대상에 연결할 수 있습니다.

Chrome 125부터 browser.debugger API는 플랫 세션을 지원합니다. 이렇게 하면 기본 디버거 세션에 추가 대상을 하위 요소로 추가하고 browser.debugger.attach를 다시 호출하지 않고도 메시지를 보낼 수 있습니다. 대신 browser.debugger.sendCommand를 호출할 때 sessionId 속성을 추가하여 명령어를 전송할 하위 타겟을 식별할 수 있습니다.

프로세스 외부 하위 프레임에 자동으로 연결하려면 먼저 Target.attachedToTarget 이벤트의 리스너를 추가합니다.

browser.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 browser.debugger.sendCommand(session, "Runtime.enable");
  }
});

그런 다음 flatten 옵션을 true로 설정하여 Target.setAutoAttach 명령어를 전송하여 자동 연결을 사용 설정합니다.

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

자동 연결은 대상이 인식하는 프레임에만 연결되며, 이는 연결된 프레임의 직계 하위 요소인 프레임으로 제한됩니다. 예를 들어 프레임 계층 구조가 A -> B -> C (모두 교차 출처)인 경우 A와 연결된 타겟에 대해 Target.setAutoAttach를 호출하면 세션이 B에도 연결됩니다. 하지만 이는 재귀적이지 않으므로 B가 세션을 C에 연결하려면 Target.setAutoAttach도 호출해야 합니다.

예

이 API를 사용해 보려면 chrome-extension-samples 저장소에서 디버거 API 예를 설치하세요.

유형

Debuggee

디버그 수신자 식별자입니다. tabId, extensionId 또는 targetId 중 하나를 지정해야 합니다.

속성

• extensionId

  문자열 선택사항

  디버그하려는 확장 프로그램의 ID입니다. 확장 프로그램 백그라운드 페이지에 연결하는 것은 --silent-debugger-extension-api 명령줄 스위치를 사용하는 경우에만 가능합니다.

• tabId

  number 선택사항

  디버그하려는 탭의 ID입니다.

• targetId

  문자열 선택사항

  디버그 타겟의 불투명 ID입니다.

DebuggerSession

Chrome 125 이상 브라우저.*(Chrome 148부터)

디버거 세션 식별자입니다. tabId, extensionId 또는 targetId 중 하나를 지정해야 합니다. 또한 선택사항으로 sessionId를 제공할 수 있습니다. onEvent에서 전송된 인수에 sessionId가 지정된 경우 이벤트가 루트 디버그 대상 세션 내의 하위 프로토콜 세션에서 발생한 것입니다. sendCommand에 전달될 때 sessionId가 지정되면 루트 디버그 대상 세션 내의 하위 프로토콜 세션을 타겟팅합니다.

속성

• extensionId

  문자열 선택사항

  디버그하려는 확장 프로그램의 ID입니다. 확장 프로그램 백그라운드 페이지에 연결하는 것은 --silent-debugger-extension-api 명령줄 스위치를 사용하는 경우에만 가능합니다.

• sessionId

  문자열 선택사항

  Chrome DevTools 프로토콜 세션의 불투명 ID입니다. tabId, extensionId 또는 targetId로 식별되는 루트 세션 내의 하위 세션을 식별합니다.

• tabId

  number 선택사항

  디버그하려는 탭의 ID입니다.

• targetId

  문자열 선택사항

  디버그 타겟의 불투명 ID입니다.

DetachReason

Chrome 44 이상 브라우저.*(Chrome 148부터)

연결 종료 이유입니다.

열거형

"target_closed"

"canceled_by_user"

TargetInfo

디버그 타겟 정보

속성

• attached

  부울

  디버거가 이미 연결되어 있으면 true입니다.

• extensionId

  문자열 선택사항

  확장 프로그램 ID입니다. type = 'background_page'인 경우 정의됩니다.

• faviconUrl

  문자열 선택사항

  대상 파비콘 URL입니다.

• id

  문자열

  대상 ID입니다.

• tabId

  number 선택사항

  type == 'page'인 경우 정의되는 탭 ID입니다.

• 제목

  문자열

  타겟 페이지 제목입니다.

• 유형

  TargetInfoType

  타겟 유형입니다.

• URL

  문자열

  대상 URL입니다.

TargetInfoType

Chrome 44 이상 브라우저.*(Chrome 148부터)

타겟 유형입니다.

열거형

"page"

"background_page"

"worker"

"other"

메서드

attach()

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

지정된 타겟에 디버거를 연결합니다.

매개변수

• 대상

  디버그 대상

  연결하려는 디버깅 타겟입니다.

• requiredVersion

  문자열

  필수 디버깅 프로토콜 버전 ("0.1")입니다. 메이저 버전이 일치하고 마이너 버전이 크거나 같은 디버그 대상에만 연결할 수 있습니다. 프로토콜 버전 목록은 여기에서 확인할 수 있습니다.

반환 값

• 약속<void>

  Chrome 96 이상 브라우저.*(Chrome 148부터)

  연결 작업이 성공하거나 실패하면 해결됩니다. 프로미스는 값 없이 결정됩니다. 연결에 실패하면 프로미스가 거부됩니다.

detach()

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

지정된 타겟에서 디버거를 분리합니다.

매개변수

• 대상

  디버그 대상

  분리하려는 디버깅 대상입니다.

반환 값

• 약속<void>

  Chrome 96 이상 브라우저.*(Chrome 148부터)

  분리 작업이 성공하거나 실패하면 해결됩니다. 프로미스는 값 없이 결정됩니다. 분리가 실패하면 프로미스가 거부됩니다.

getTargets()

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

사용 가능한 디버그 타겟 목록을 반환합니다.

반환 값

• Promise<TargetInfo[]>

  Chrome 96 이상 브라우저.*(Chrome 148부터)

sendCommand()

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

지정된 명령어를 디버깅 타겟으로 전송합니다.

매개변수

• 대상

  DebuggerSession

  명령어를 전송할 디버깅 타겟입니다.

• method

  문자열

  메서드 이름입니다. 원격 디버깅 프로토콜에서 정의한 메서드 중 하나여야 합니다.

• commandParams

  객체 선택사항

  요청 매개변수가 있는 JSON 객체입니다. 이 객체는 지정된 메서드의 원격 디버깅 매개변수 스키마를 준수해야 합니다.

반환 값

• Promise<object | undefined>

  Chrome 96 이상 브라우저.*(Chrome 148부터)

  응답 본문입니다. 메시지를 게시하는 중에 오류가 발생하면 프로미스가 거부됩니다.

이벤트

onDetach

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

브라우저가 탭의 디버깅 세션을 종료할 때 실행됩니다. 이는 탭이 닫히거나 연결된 탭에 대해 Chrome DevTools가 호출될 때 발생합니다.

매개변수

• callback

  함수

  callback 매개변수는 다음과 같습니다.

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

  • source

    디버그 대상

  • reason

    DetachReason

onEvent

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

디버깅 대상이 계측 이벤트를 실행할 때마다 실행됩니다.

매개변수

• callback

  함수

  callback 매개변수는 다음과 같습니다.

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

  • source

    DebuggerSession

  • method

    문자열

  • params

    객체 선택사항