blob: f26afe62ece9a2ccda1ab39f498eafde0124093b [file] [log] [blame] [view]
Danil Somsikovd884ae72025-02-12 07:56:131# Chromium DevTools UI Engineering
2
3## Objective and scope
4
5This document defines how to build Chromium DevTools UI. It aims at improving consistency, maintainability and extensibility of the current code
6
7**Consistency** here means to have one way to do one thing, in the context of this doc to have a single reusable component per repeated task.
8
9**Maintainability** is addressed here through the [separation of concerns](https://en.wikipedia.org/wiki/Separation_of_concerns) while avoiding unnecessary indirection.
10
11**Extensibility** requires the ease of understanding and imitation, i.e. being able to take an existing code, understand and use it as an example to solve another problem.
12
13Additionally, all the changes need to be applicable to the existing code **point-wise** instead of requiring extensive rewriting.
14
15## Reusable web components
16
17Common UI primitives need to be implemented as web components. Examples include buttons, checkboxs, or data grids. Web components should not be used solely for encapsulation, we should not have single-use web components.
18
19Not all reusable code should be a web component: in the Application panel we have several similar views showing key-value pairs in a datagrid with a preview sidebar. Making this a truly reusable component will lead to an unjustifiable complexity. Instead we should have extracted a base class or helpers implementing the common functionality.
20
21In implementation we should prefer wrapping existing code under ui/legacy over new implementation. The former is the most feature-rich (including less obvious aspects like a11y) and has stood the test of time.
22
23We should however strive to expose a HTML-native API: e.g. toolbar doesnt need an `items` setter if its child HTML elements could define its content. Even the data grid doesnt need to expose data grid nodes, when `<tr>` and `<td>`s are enough.
24
25## Model-View-Presenter architecture
26
27We should strictly separate business logic, from UI logic and presentation. This means that most of the UI code should be centered around a presenter (subclass of a `UI.Widget`) that gets a view function injected. All the logic that is not related to the DevTools UI (i.e. that would stay the same if we rewrite DevTools as a command-line tool), should belong to the model layer.
28
29The presenter code should make no assumptions about the details of model or view code. It should not care what race conditions CDP exposes or how many layers of `<div class=”wrapper”>` does the markup have. However, for simplicity, the injected view function should have a default implementation inlined with a presenter (see an example below).
30
31In tests, we use a simple stub as a view function, which allows us to test the presenter logic without any DOM manipulation. To test the view function itself we should use screenshot and e2e tests.
32
33## Declarative and orchestrated DOM updates
34
35We should no longer use imperative API to update DOM. Instead we rely on orchestrated rendering of lit-html templates. The view function described above should be a call to lit-html `render`. The view function should be called from `UI.Widget`s `performUpdate` method, which by default is scheduled using `requestAnimationFrame`.
36
37To embed another presenter (`UI.Widget`) in the lit-html template, use `<devtools-widget .widgetConfig=${widgetConfig(<class>, {foo: 1, bar: 2})}`
38
39This will instantiate a `Widget` class with the web component as its `element` and, optionally, will set the properties provided in the second parameter. The widget wont be re-instantiated on the subsequent template renders, but the properties would be updated. For this to work, the widget needs to accept `HTMLElement` as a sole constructor parameter and properties need to be public members or setters.
40
41## Examples
42
43```html
Alex Rudenko8d6d6c22025-02-27 15:36:4044<devtools-widget .widgetConfig=${widgetConfig(ElementsPanel)}>
Danil Somsikovd884ae72025-02-12 07:56:1345 <devtools-split-widget>
Alex Rudenko8d6d6c22025-02-27 15:36:4046 <devtools-widget slot="main" .widgetConfig=${widgetConfig(ElementsTree)}></devtools-widget>
Mathias Bynensae705ff2025-02-12 09:51:2347 <devtools-tab-pane slot="sidebar">
Alex Rudenko8d6d6c22025-02-27 15:36:4048 <devtools-widget .widgetConfig=${widgetConfig(StylesPane, {element: input.element})}></devtools-widget>
49 <devtools-widget .widgetConfig=${widgetConfig(ComputedPane, {element: input.element})}></devtools-widget>
Mathias Bynensae705ff2025-02-12 09:51:2350 ...
Danil Somsikovd884ae72025-02-12 07:56:1351 </devtools-tab-pane>
52 </devtools-split-widget>
53</devtools-widget>
54```
55
56```ts
57class StylesPane extends UI.Widget {
58 constructor(element, view = (input, output, target) => {
59 render(html`
Alex Rudenko8d6d6c22025-02-27 15:36:4060 <devtools-widget .widgetConfig=${widgetConfig(MetricsPane, {element: input.element})}>
Mathias Bynensae705ff2025-02-12 09:51:2361 </devtools-widget>
Danil Somsikovd884ae72025-02-12 07:56:1362 <devtools-toolbar>
Mathias Bynensae705ff2025-02-12 09:51:2363 <devtools-filter-input @change=${input.onFilter}></devtools-filter-input>
64 <devtools-checkbox @change=${input.onShowAll}>Show All</devtools-checkbox>
65 <devtools-checkbox @change=${input.onGroup}>Group</devtools-checkbox>
Danil Somsikovd884ae72025-02-12 07:56:1366 </devtools-toolbar>
67 <devtools-tree-outline>
68 ${input.properties.map(p => html`<li>
69 <dt>${p.key}</dt><dd>${renderValue(p.value)}</dd>
70 <ol>${p.subproperties.map(...)}
71 </li>`)}
72 </devtools-tree-outline>`
73 }
74}
75```
76
77[https://source.chromium.org/chromium/chromium/src/+/main:third\_party/devtools-frontend/src/front\_end/panels/protocol\_monitor/ProtocolMonitor.ts;l=197](https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/panels/protocol_monitor/ProtocolMonitor.ts;l=197)
78
79[https://source.chromium.org/chromium/chromium/src/+/main:third\_party/devtools-frontend/src/front\_end/panels/developer\_resources/DeveloperResourcesListView.ts;l=86](https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/panels/developer_resources/DeveloperResourcesListView.ts;l=86)
80
81[https://source.chromium.org/chromium/chromium/src/+/main:third\_party/devtools-frontend/src/front\_end/panels/timeline/TimelineSelectorStatsView.ts;l=113](https://source.chromium.org/chromium/chromium/src/+/main:third_party/devtools-frontend/src/front_end/panels/timeline/TimelineSelectorStatsView.ts;l=113)
Alex Rudenkoc6499cc2025-02-17 09:08:2582
83
84### Unit tests
85
Alex Rudenkoe5c358e2025-02-17 11:31:5286When testing presenters, rely on observable effects such as view updates or model calls.
87
88#### View stubbing
Alex Rudenkoc6499cc2025-02-17 09:08:2589
90```ts
Alex Rudenko6f29fce2025-03-05 16:15:5191// ✅ recommended: stub the view function using createViewFunctionStub.
92import {createViewFunctionStub} from './ViewFunctionHelpers.js';
93const view = createViewFunctionStub(Presenter);
Alex Rudenkoc6499cc2025-02-17 09:08:2594const presenter = new Presenter(view);
95
96// ✅ recommended: expect a view stub call in response to presenter behavior.
Alex Rudenkoc6499cc2025-02-17 09:08:2597present.show();
Alex Rudenko6f29fce2025-03-05 16:15:5198const input = await view.nextInput;
Alex Rudenkoc6499cc2025-02-17 09:08:2599
100// ✅ recommended: expect a view stub call in response to an event from the view.
Alex Rudenko6f29fce2025-03-05 16:15:51101input.onEvent();
102assert.deepStrictEqual(await view.nextInput, {});
Alex Rudenkoc6499cc2025-02-17 09:08:25103
104// ❌ not recommended: Widget.updateComplete only reports a current view update
105// operation status and might create flakiness depending on doSomething() implementation.
106presenter.doSomething();
107await presenter.updateComplete;
108assert.deepStrictEqual(view.lastCall.args[0], {});
109
110// ❌ not recommended: awaiting for the present logic to finish might
111// not account for async or throttled view updates.
112await presenter.doSomething();
Alex Rudenkoe5c358e2025-02-17 11:31:52113// ❌ not recommended: it is easy for such assertions to
114// rely on the data not caused by the action being tested.
115sinon.assert.calledWith(view, sinon.match({ data: 'smth' }));
116```
117
118#### Model stubbing
119
120```ts
121// ✅ recommended: stub models that the presenter relies on.
122// Note there are many good ways to stub/mock models with sinon
123// depending on the use case and existing model code structure.
124const cssModel = sinon.createStubInstance(SDK.CSSModel.CSSModel);
125
126const presenter = new Presenter();
127// ✅ recommended: expect model calls as the result of invoking
Alex Rudenko6f29fce2025-03-05 16:15:51128// presenter's logic.
Alex Rudenkoe5c358e2025-02-17 11:31:52129const modelCall = expectCall(cssModel.headersForSourceURL, {
130 fakeFn: () => {
131 return false,
132 },
133});
134// ✅ recommended: expect view calls to result in output based
135// on the mocked model.
Alex Rudenko6f29fce2025-03-05 16:15:51136const viewCall = view.nextInput;
Alex Rudenkoe5c358e2025-02-17 11:31:52137
138presenter.doSomething();
139
140// ✅ recommended: assert arguments provided to model calls.
141const [url] = await modelCall;
142assert.strictEqual(url, '...');
143
Alex Rudenko6f29fce2025-03-05 16:15:51144assert.deepStrictEqual((await viewCall).headersForSourceURL, [{...}]);
Alex Rudenkoe5c358e2025-02-17 11:31:52145
146// ❌ not recommended: mocking CDP responses to make the models behave in a certain way
Alex Rudenko6f29fce2025-03-05 16:15:51147// while testing a presenter is fragile.
Alex Rudenkoe5c358e2025-02-17 11:31:52148setMockConnectionResponseHandler('CSS.getHeaders', () => ({}));
149const presenter = new Presenter();
150presenter.doSomething();
Alex Rudenkoc6499cc2025-02-17 09:08:25151```