chrome.debugger

תיאור

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

הרשאות

debugger

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

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

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

לאחר ההוספה, ה-API של chrome.debugger יאפשר לך לשלוח את פרוטוקול כלי הפיתוח ל-Chrome פקודות (CDP) ליעד נתון. אין הסבר מעמיק על CDP לקבלת מידע נוסף על CDP, אפשר לעיין מסמכי התיעוד הרשמיים של CDP.

יעדים

היעדים מייצגים משהו שמתבצע בו ניפוי באגים, למשל כרטיסייה, iframe או worker. כל יעד מזוהה באמצעות UUID ויש לו סוג (למשל iframe, shared_worker ועוד).

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

דומיינים מוגבלים

מטעמי אבטחה, ה-API של chrome.debugger לא מספק גישה לכל כלי הפיתוח ל-Chrome דומיינים של פרוטוקול. הדומיינים הזמינים הם: נגישות, ביקורות, CacheStorage, Console, CSS, מסד נתונים, כלי לניפוי באגים, DOM, DOMDebugger, DOMSnapshot, אמולציה, אחזור, IO, קלט, מפקח, יומן, רשת, שכבת על, דף, ביצועים, Profiler, זמן ריצה, אחסון, יעד, מעקב, 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 עם האפשרות 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

מאפיינים

  • extensionId

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

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

  • tabId

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

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

  • targetId

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

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

DebuggerSession

Chrome 125+

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

מאפיינים

  • extensionId

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

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

  • sessionId

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

    המזהה האטום של הפעילות של פרוטוקול Chrome DevTools. מזהה סשן צאצא בסשן הבסיסי שמזוהה לפי TabId, extensionId או targetId.

  • tabId

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

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

  • targetId

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

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

DetachReason

Chrome 44 ואילך

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

Enum

"target_closed"

"canceled_by_user"

TargetInfo

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

מאפיינים

  • מצורף

    בוליאני

    הערך הוא True אם הכלי לניפוי באגים כבר מצורף.

  • extensionId

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

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

  • faviconUrl

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

    כתובת ה-URL של סמל האתר בקמפיין.

  • id [מזהה]

    מחרוזת

    מזהה היעד.

  • tabId

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

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

  • title

    מחרוזת

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

  • סוג היעד.

  • כתובת אתר

    מחרוזת

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

TargetInfoType

Chrome 44 ואילך

סוג היעד.

Enum

"דף"

"background_page"

"worker"

"אחר"

שיטות

attach()

הבטחה 
chrome.debugger.attach(
  target: Debuggee,
  requiredVersion: string,
  callback?: function,
)

מצרף כלי לניפוי באגים ליעד הנתון.

פרמטרים

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

  • requiredVersion

    מחרוזת

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

  • קריאה חוזרת (callback)

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

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

    () => void

החזרות

  • הבטחה<Empty>

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

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

detach()

הבטחה 
chrome.debugger.detach(
  target: Debuggee,
  callback?: function,
)

מנתקים את הכלי לניפוי באגים מהיעד הנתון.

פרמטרים

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

  • קריאה חוזרת (callback)

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

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

    () => void

החזרות

  • הבטחה<Empty>

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

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

getTargets()

הבטחה 
chrome.debugger.getTargets(
  callback?: function,
)

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

פרמטרים

  • קריאה חוזרת (callback)

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

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

    (result: TargetInfo[]) => void

    • תוצאה

      TargetInfo[]

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

החזרות

  • Promise&lt;TargetInfo[]&gt;

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

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

sendCommand()

הבטחה 
chrome.debugger.sendCommand(
  target: DebuggerSession,
  method: string,
  commandParams?: object,
  callback?: function,
)

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

פרמטרים

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

  • method

    מחרוזת

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

  • commandParams

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

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

  • קריאה חוזרת (callback)

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

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

    (result?: object) => void

    • תוצאה

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

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

החזרות

  • Promise&lt;object | לא מוגדר>

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

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

אירועים

onDetach

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

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

פרמטרים

onEvent

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

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

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

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

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

    • method

      מחרוזת

    • פרמטרים

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