chrome.debugger

תיאור

ה-API של chrome.debugger משמש ככלי תחבורה חלופי לפרוטוקול לניפוי באגים מרחוק של Chrome. אפשר להשתמש ב-chrome.debugger כדי לצרף כרטיסייה אחת או יותר כדי לבדוק את האינטראקציה עם הרשת, לנפות באגים ב-JavaScript, לשנות את DOM ו-CSS ועוד. משתמשים במאפיין tabId של Debuggee כדי לטרגט כרטיסיות באמצעות sendCommand ולנתב אירועים לפי tabId מקרי קריאה חוזרת (callbacks) של onEvent.

הרשאות

debugger

כדי להשתמש ב-API הזה, צריך להצהיר על ההרשאה "debugger" במניפסט של התוסף.

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

מושגים ושימוש

לאחר הקישור, ממשק ה-API chrome.debugger מאפשר לשלוח פקודות של פרוטוקול כלי הפיתוח של Chrome (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 כדי לזהות הקשרי ביצוע חדשים שמשויכים לאותו מסגרת תהליך.

  • פועלים לפי השלבים לצירוף ליעדים קשורים כדי לזהות מסגרות מחוץ לתהליך.

אחרי שמתחברים ליעד, כדאי להתחבר ליעדים קשורים נוספים, כולל מסגרות צאצא מחוץ לתהליך או עובדים משויכים.

החל מגרסה 125 של Chrome, ממשק ה-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 עם הערך true באפשרות flatten:

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

ההצמדה האוטומטית מתבצעת רק למסגרות שהיעד מודע אליהן, והיא מוגבלת למסגרות שהן צאצאים מיידיים של מסגרת שמשויכת אליו. לדוגמה, בהיררכיית המסגרות A -> B -> C (שבה כולן מקורן במקור שונה), קריאה ל-Target.setAutoAttach עבור היעד שמשויך ל-A תגרום לשיוך הסשן גם ל-B. עם זאת, הפעולה הזו לא רציפה, ולכן צריך גם להפעיל את Target.setAutoAttach כדי ש-B יצמיד את הסשן ל-C.

דוגמאות

כדי לנסות את ה-API הזה, מתקינים את הדוגמה ל-API של מנתח הבאגים מהמאגר chrome-extension-samples.

סוגים

Debuggee

מזהה הקוד לניפוי באגים. צריך לציין את tabId, ‏ extensionId או targetId

מאפיינים

  • extensionId

    מחרוזת אופציונלי

    המזהה של התוסף שרוצים לנפות בו באגים. אפשר לצרף את התג לדף הרקע של התוסף רק כשמשתמשים במתג שורת הפקודה --silent-debugger-extension-api.

  • tabId

    מספר אופציונלי

    המזהה של הכרטיסייה שרוצים לנפות באגים בה.

  • targetId

    מחרוזת אופציונלי

    המזהה האטום של יעד ניפוי הבאגים.

DebuggerSession

גרסה 125 ואילך של Chrome

מזהה הסשן של מנתח הבאגים. צריך לציין אחד מהפרמטרים הבאים: tabId, ‏ extensionId או targetId. בנוסף, אפשר לספק מזהה סשן אופציונלי. אם צוין sessionId לארגומנטים שנשלחים מ-onEvent, המשמעות היא שהאירוע מגיע מסשן של פרוטוקול צאצא בתוך סשן ניפוי הבאגים ברמה הבסיסית. אם מציינים את sessionId כשהוא מועבר אל sendCommand, הוא מטרגט סשן פרוטוקול צאצא בסשן של ה-debuggee ברמה הבסיסית.

מאפיינים

  • extensionId

    מחרוזת אופציונלי

    המזהה של התוסף שרוצים לנפות בו באגים. אפשר לצרף את התג לדף הרקע של התוסף רק כשמשתמשים במקש הקיצור --silent-debugger-extension-api בשורת הפקודה.

  • sessionId

    מחרוזת אופציונלי

    המזהה האטום של הסשן בפרוטוקול של כלי הפיתוח ל-Chrome. מזהה סשן צאצא בתוך סשן הבקרה שמזוהה באמצעות tabId, ‏ extensionId או targetId.

  • tabId

    מספר אופציונלי

    המזהה של הכרטיסייה שרוצים לנפות באגים בה.

  • targetId

    מחרוזת אופציונלי

    המזהה האטום של יעד ניפוי הבאגים.

DetachReason

גרסה 44 ואילך של Chrome

הסיבה לסיום החיבור.

Enum

"target_closed"

"canceled_by_user"

TargetInfo

מידע על יעד ניפוי הבאגים

מאפיינים

  • מצורף

    בוליאני

    הערך TRUE אם כבר מחובר מנתח באגים.

  • extensionId

    מחרוזת אופציונלי

    מזהה התוסף, שמוגדר אם type = 'background_page'.

  • faviconUrl

    מחרוזת אופציונלי

    כתובת ה-URL של סמל האתר של היעד.

  • id [מזהה]

    מחרוזת

    מזהה היעד.

  • tabId

    מספר אופציונלי

    מזהה הכרטיסייה, שמוגדר אם type == 'page'.

  • title

    מחרוזת

    כותרת דף היעד.

  • סוג היעד.

  • כתובת אתר

    מחרוזת

    כתובת ה-URL של היעד.

TargetInfoType

Chrome מגרסה 44 ואילך

סוג היעד.

Enum

"page"

"background_page"

"worker"

"other"

Methods

attach()

Promise 
chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
  callback?: function,
)

הצמדת מנתח הבאגים ליעד הנתון.

פרמטרים

  • יעד

    Debuggee

    היעד לניפוי באגים שאליו רוצים לצרף את הקוד.

  • requiredVersion

    מחרוזת

    גרסת הפרוטוקול הנדרשת לניפוי באגים ('0.1'). אפשר לצרף את הקוד לבדיקה רק אם הגרסה הראשית תואמת לגרסה הראשית של הקוד לבדיקה, והגרסה המשנית תואמת או גדולה יותר. כאן אפשר למצוא רשימה של גרסאות הפרוטוקול.

  • callback

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • Promise<void>

    גרסה 96 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

detach()

Promise 
chrome.debugger.detach(
  target: Debuggee,
  callback?: function,
)

ניתוק מנתח הבאגים מהיעד הנתון.

פרמטרים

  • יעד

    Debuggee

    יעד ניפוי הבאגים שממנו רוצים לנתק.

  • callback

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • Promise<void>

    גרסה 96 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

getTargets()

Promise 
chrome.debugger.getTargets(
  callback?: function,
)

הפונקציה מחזירה את רשימת היעדים הזמינים לניפוי באגים.

פרמטרים

  • callback

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (result: TargetInfo[]) => void

    • תוצאה

      TargetInfo[]

      מערך של אובייקטים מסוג TargetInfo שתואמים ליעדים הזמינים לניפוי באגים.

החזרות

  • Promise<TargetInfo[]>

    גרסה 96 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

sendCommand()

Promise 
chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
  callback?: function,
)

שליחת הפקודה שצוינה ליעד לניפוי הבאגים.

פרמטרים

  • היעד לניפוי באגים שאליו רוצים לשלוח את הפקודה.

  • method

    מחרוזת

    שם השיטה. צריכה להיות אחת מהשיטות שמוגדרות בפרוטוקול לניפוי באגים מרחוק.

  • commandParams

    אובייקט אופציונלי

    אובייקט JSON עם פרמטרים של בקשה. האובייקט הזה חייב להתאים לסכימה של הפרמטרים לניפוי באגים מרחוק בשיטה נתונה.

  • callback

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (result?: object) => void

    • תוצאה

      אובייקט אופציונלי

      אובייקט JSON עם התגובה. המבנה של התגובה משתנה בהתאם לשם השיטה, והוא מוגדר לפי המאפיין 'returns' (החזרים) של תיאור הפקודה בפרוטוקול ניפוי הבאגים מרחוק.

החזרות

  • Promise<object | undefined>

    גרסה 96 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

אירועים

onDetach

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

האירוע מופעל כשהדפדפן מסיים את סשן ניפוי הבאגים של הכרטיסייה. זה קורה כשסוגרים את הכרטיסייה או כשמפעילים את Chrome DevTools בכרטיסייה המצורפת.

פרמטרים

onEvent

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

האירוע הזה מופעל בכל פעם שמופעל אירוע של מכשיר למדידת ביצועים לצורך ניפוי באגים ביעדים.

פרמטרים

  • callback

    פונקציה

    הפרמטר callback נראה כך: 

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

    • method

      מחרוזת

    • params

      אובייקט אופציונלי