Adding a new Chrome DevTools feature

[MaxIhlenfeldt]

Logistics

• Date & Time: Wednesday 4th June at 10:00 CEST (local time)
• URL: https://meet.jit.si/WEH2025-DevTools
• Notes: https://hackmd.io/@rego/WEH2025-DevTools/edit
• Room: JS

Facilitator(s)

@MaxIhlenfeldt (Igalia)

Summary

In this live coding session we'll learn how to add a simple new feature to Chrome DevTools. To be specific, we'll:

1. Add a new Chrome Remote Debugging protocol request,
2. Implement the request in the backend (Blink in our case), and finally
3. Add a way to use the new request to the DevTools frontend.

Type

Onsite

Other comments

No response

[mrego]

We're proposing Wednesday 4th June at 10:00 CEST (local time) for this session.

If that's a problem, please let us know to try to find other slot in the scheduling.

[MaxIhlenfeldt]

That time works well, thanks!

[MaxIhlenfeldt]

Here are my notes for the session, containing all the links and the code:

A little bit of theory upfront

• https://chromedevtools.github.io/devtools-protocol/

• Contributing to Chrome DevTools Protocol

Implementing the backend

diff --git a/third_party/blink/public/devtools_protocol/browser_protocol.pdl b/third_party/blink/public/devtools_protocol/browser_protocol.pdl
index e4e10a8f0af2c..92154a5701c0f 100644
--- a/third_party/blink/public/devtools_protocol/browser_protocol.pdl
+++ b/third_party/blink/public/devtools_protocol/browser_protocol.pdl
@@ -3734,6 +3734,14 @@ domain DOM
       # The anchor element of the given anchor query.
       NodeId nodeId
 
+  # Adds a paragraph element to the DOM.
+  experimental command addParagraph
+    parameters
+      # The content of the paragraph element.
+      string content
+      # The ID of the parent. If omitted, the body element is used as the parent.
+      optional string parentId
+
   # Fired when `Element`'s attribute is modified.
   event attributeModified
     parameters

• normally we'd have to modify https://source.chromium.org/chromium/chromium/src/+/main:third_party/blink/renderer/core/inspector/inspector_protocol_config.json to specify which agent should handle the request
  • in this case the blink handler is configured so that it handles all requests in the DOM domain, so we don't need to change the config
  • see e.g. Emulation domain for an example where you'd need to explicitly add the request for handling

diff --git a/third_party/blink/renderer/core/inspector/inspector_dom_agent.h b/third_party/blink/renderer/core/inspector/inspector_dom_agent.h
index 2acd0252ff125..52d76abffde25 100644
--- a/third_party/blink/renderer/core/inspector/inspector_dom_agent.h
+++ b/third_party/blink/renderer/core/inspector/inspector_dom_agent.h
@@ -285,6 +285,9 @@ class CORE_EXPORT InspectorDOMAgent final
                                       std::optional<String> anchor_specifier,
                                       int* out_node_id) override;
 
+  protocol::Response addParagraph(const String& content,
+                                  std::optional<String> parent_id) override;
+
   bool Enabled() const;
   IncludeWhitespaceEnum IncludeWhitespace() const;
   void ReleaseDanglingNodes();

diff --git a/third_party/blink/renderer/core/inspector/inspector_dom_agent.cc b/third_party/blink/renderer/core/inspector/inspector_dom_agent.cc
index 3f696f230d154..9ebbdb3fecdb6 100644
--- a/third_party/blink/renderer/core/inspector/inspector_dom_agent.cc
+++ b/third_party/blink/renderer/core/inspector/inspector_dom_agent.cc
@@ -1948,6 +1948,28 @@ protocol::Response InspectorDOMAgent::getAnchorElement(
   return protocol::Response::Success();
 }
 
+protocol::Response InspectorDOMAgent::addParagraph(
+    const String& content,
+    std::optional<String> parent_id) {
+  if (!document_) {
+    return protocol::Response::InvalidRequest("No document_");
+  }
+  Node* node = document_->createTextNode(content);
+  auto* element = MakeGarbageCollected<Element>(html_names::kPTag, document_);
+  element->appendChild(node);
+  Element* parent;
+  if (parent_id) {
+    parent = document_->getElementById(AtomicString(*parent_id));
+    if (!parent) {
+      return protocol::Response::InvalidParams("Invalid parent ID");
+    }
+  } else {
+    parent = document_->body();
+  }
+  parent->appendChild(element);
+  return protocol::Response::Success();
+}
+
 // static
 const HeapVector<Member<Element>>
 InspectorDOMAgent::GetContainerQueryingDescendants(Element* container) {

• that's it already!

  • more work for e.g. persisting changes across reloads and navigations

• we can test our new protocol message in the protocol monitor (see here)

  • Enable protocol monitor via Settings > Experiments > Protocol Monitor
  • Set target to "Main" at (bottom) right of protocol monitor, then hide the sidebar again (button under red icon which is next to the "Filter" input) because sidebar doesn't have our new request yet
  • {"command": "DOM.addParagraph", "args": {"content": "hi WEH!"}}

Implementing the frontend

• https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/docs/devtools-protocol.md has instructions for frontend with adding new stuff to the protocol

• Chromium DevTools Contribution Guide

  • inspect DevTools using DevTools to see how the existing frontend works: undock DevTools to separate window, then Ctrl+Shift+I

• sync protocol to frontend:

  • third_party/devtools-frontend/src/scripts/deps/roll_deps.py --ref working-tree /home/igalia/chromium/src/ /home/igalia/chromium/src/third_party/devtools-frontend/src/
  • will probably need to patch CONCATENATE_PROTOCOL_SCRIPT in third_party/devtools-frontend/src/scripts/deps/generate_protocol_resources.py

diff --git a/scripts/deps/generate_protocol_resources.py b/scripts/deps/generate_protocol_resources.py
index 31975dd116..e1c968eb3b 100755
--- a/scripts/deps/generate_protocol_resources.py
+++ b/scripts/deps/generate_protocol_resources.py
@@ -65,8 +65,8 @@ GENERATE_SUPPORTED_CSS_SCRIPT = path.join(SCRIPTS_BUILD_PATH,
                                           'generate_supported_css.py')
 GENERATE_PROTOCOL_DEFINITIONS_SCRIPT = path.join(SCRIPTS_BUILD_PATH,
                                                  'code_generator_frontend.py')
-CONCATENATE_PROTOCOL_SCRIPT = path.join(ROOT_DIRECTORY, 'third_party',
-                                        'inspector_protocol',
+CONCATENATE_PROTOCOL_SCRIPT = path.join('/home/igalia/chromium/src',
+                                        'third_party', 'inspector_protocol',
                                         'concatenate_protocols.py')
 GENERATE_DEPRECATIONS_SCRIPT = path.join(SCRIPTS_BUILD_PATH,
                                          'generate_deprecations.py')

diff --git a/front_end/panels/elements/ElementsPanel.ts b/front_end/panels/elements/ElementsPanel.ts
index 37e6c86d7c..3db8b7dfb1 100644
--- a/front_end/panels/elements/ElementsPanel.ts
+++ b/front_end/panels/elements/ElementsPanel.ts
@@ -195,6 +195,7 @@ export class ElementsPanel extends UI.Panel.Panel implements UI.SearchableView.S
   private domTreeContainer: HTMLDivElement;
   private splitMode: SplitMode|null;
   private readonly accessibilityTreeView: AccessibilityTreeView|undefined;
+  private addParagraphToolbar: HTMLElement;
   private breadcrumbs: ElementsComponents.ElementsBreadcrumbs.ElementsBreadcrumbs;
   stylesWidget: StylesSidebarPane;
   private readonly computedStyleWidget: ComputedStyleWidget;
@@ -275,6 +276,32 @@ export class ElementsPanel extends UI.Panel.Panel implements UI.SearchableView.S
       this.accessibilityTreeView =
           new AccessibilityTreeView(this.domTreeButton, new TreeOutline.TreeOutline.TreeOutline<AXTreeNodeData>());
     }
+
+    this.addParagraphToolbar = crumbsContainer.createChild('devtools-toolbar');
+    this.addParagraphToolbar.id = 'add-paragraph-toolbar';
+    const addParagraphInput = new UI.Toolbar.ToolbarInput('Paragraph content', undefined, 1);
+    const addParagraphParentInput = new UI.Toolbar.ToolbarInput('Parent ID (optional)', undefined, 1);
+    this.addParagraphToolbar.appendToolbarItem(addParagraphInput);
+    this.addParagraphToolbar.appendToolbarItem(addParagraphParentInput);
+
+    const addParagraphButton = new Buttons.Button.Button();
+    const title = 'Add paragraph';
+    addParagraphButton.data = {
+      active: true,
+      variant: Buttons.Button.Variant.TOOLBAR,
+      iconName: 'send',
+      title,
+    };
+    addParagraphButton.classList.add('active');
+    addParagraphButton.addEventListener('click', _ => {
+      const command: any = {content: addParagraphInput.value()};
+      if (addParagraphParentInput.value() != '') {
+        command['parentId'] = addParagraphParentInput.value();
+      }
+      SDK.TargetManager.TargetManager.instance().primaryPageTarget()?.domAgent().invoke_addParagraph(command);
+    });
+    this.addParagraphToolbar.appendChild(addParagraphButton);
+
     this.breadcrumbs = new ElementsComponents.ElementsBreadcrumbs.ElementsBreadcrumbs();
     this.breadcrumbs.addEventListener('breadcrumbsnodeselected', event => {
       this.crumbNodeSelected(event);

diff --git a/front_end/panels/elements/elementsPanel.css b/front_end/panels/elements/elementsPanel.css
index 5a072303a6..45e93b5fc0 100644
--- a/front_end/panels/elements/elementsPanel.css
+++ b/front_end/panels/elements/elementsPanel.css
@@ -59,6 +59,9 @@
   width: 100%;
 }
 
+#add-paragraph-toolbar {
+  border-bottom: 1px solid var(--sys-color-divider);
+}
 devtools-adorner-settings-pane {
   margin-bottom: 10px;
   border-bottom: 1px solid var(--sys-color-divider);

Final step: testing!

third_party/blink/web_tests/inspector-protocol/dom/add-paragraph.js:

(async function(/** @type {import('test_runner').TestRunner} */ testRunner) {
  const {session, dp} = await testRunner.startHTML(
      '<div id="foo"><p id="bar">baz</p></div>',
      'Tests that DOM.addParagraph() works.');

  await dp.DOM.enable();

  async function logAll() {
    const paragraphs = await session.evaluate(() => {
      const paragraphs = document.getElementsByTagName('p');
      var res = '';
      for (const p of paragraphs) {
        res += `* id='${p.id}' innerHTML='${p.innerHTML}'\n`;
      }
      return res;
    });
    testRunner.log(`Paragraph elements:\n${paragraphs}`);
    const children = await session.evaluate(() => {
      const children = document.getElementById('foo').children;
      var res = '';
      for (const c of children) {
        res += `* id='${c.id}' innerHTML='${c.innerHTML}'\n`;
      }
      return res;
    });
    testRunner.log(`Children of div#foo:\n${children}`);
  }

  testRunner.log('Initial state:');
  await logAll();

  testRunner.log('Adding paragraph with unspecified parent.');
  await dp.DOM.addParagraph({content: 'test1'});

  testRunner.log('New state:');
  await logAll();

  testRunner.log('Adding paragraph to div#foo.');
  await dp.DOM.addParagraph({content: 'test2', parentId: 'foo'});

  testRunner.log('New state:');
  await logAll();

  testRunner.completeTest();
});

third_party/blink/web_tests/inspector-protocol/dom/add-paragraph-expected.txt:

Tests that DOM.addParagraph() works.
Initial state:
Paragraph elements:
* id='bar' innerHTML='baz'

Children of div#foo:
* id='bar' innerHTML='baz'

Adding paragraph with unspecified parent.
New state:
Paragraph elements:
* id='bar' innerHTML='baz'
* id='' innerHTML='test1'

Children of div#foo:
* id='bar' innerHTML='baz'

Adding paragraph to div#foo.
New state:
Paragraph elements:
* id='bar' innerHTML='baz'
* id='' innerHTML='test2'
* id='' innerHTML='test1'

Children of div#foo:
* id='bar' innerHTML='baz'
* id='' innerHTML='test2'

build blink_tests target and run via third_party/blink/tools/run_web_tests.py -t WaylandRelease inspector-protocol/dom/ add-paragraph.js

Appendix

real-world example CLs:

• https://crrev.com/c/6253279
• https://crrev.com/c/6275956

[mrego]

Are there any other notes for this session?

[MaxIhlenfeldt]

None that I'm aware of

[mrego]

Let's close this, if some notes appear, please reopen this and put a link here. Thanks!