This checklist comes from recurring reviewer feedback on landed DevTools CLs. Use it for self-review before upload and for reviewing other people's CLs.
1. Gather context
- Automated Review Agent (diff already in prompt): Do not run shell
commands. Use
read_fileto inspect enclosing classes/functions/tests andsearch_filesto verify callers or conventions across the repository. - Local CLI / Interactive session (no diff in prompt):
- Local change:
git diff origin/main...HEAD(orgit show HEADfor a single-commit branch). To learn about the branch and upload workflow, see thedevtools-version-controlskill. - Gerrit CL: strip the leading
)]}'line from each response to get JSON:- Diff:
git cl diff(for the current branch), or fetch the patch set. - Inline comments:
curl -s https://chromium-review.googlesource.com/changes/devtools%2Fdevtools-frontend~<CL_NUMBER>/comments | tail -n +2 - Messages:
.../changes/devtools%2Fdevtools-frontend~<CL_NUMBER>/messages
- Diff:
- Read the CL description first. Then check that the diff does what the description says, and nothing else.
- Local change:
2. Consult the specialized skills and rules
Load the skill or .agents/rules/ files that match what the diff touches, and apply their rules:
| If the diff touches… | Load skill or rules |
|---|---|
Any import statement, or a new cross-module dependency |
devtools-imports |
UI.Widget, lit-html views, components, CSS |
ui-widgets |
| Reviewing UI and widgets (`front_end/(panels | ui)/**/*.{ts,css}`) |
| Migration of legacy imperative DOM to widgets or Lit | ui-eng-vision-orchestrator (and its sub-skills) |
| New or changed tests: choosing unit, API, or E2E | devtools-testing-guidance |
Reviewing tests (*.test.ts, test/**, front_end/testing/**) |
.agents/rules/tests/*.md |
Tests that use describeWithEnvironment or describeWithMockConnection, or foundation modules |
foundation-test-migration |
Ported Chromium web tests (web_tests/http/tests/devtools) |
migrate-chromium-test |
Flaky or disabled tests, or it.skip / it.skipOnPlatforms |
fix-tests |
| Rendering user-controlled strings (URLs, names, console text) | devtools-unicode-escaping |
front_end/models/*, BUILD.gn, devtools_grd_files.gni, entrypoints |
devtools-model-management |
| Reviewing foundation, models, and build configs (`front_end/(core | models |
Merging modules or consolidating BUILD.gn |
merging-devtools-module |
Settings registrations and descriptors |
devtools-setting-migration |
Stack traces, source maps, DebuggerWorkspaceBinding |
devtools-source-maps |
| Building, running tests, or lint | devtools-verification |
3. Boundaries vs. Interiors
- Enforce module boundaries strictly: Prioritize boundary invariants—module
entrypoints (
foo.ts,foo-meta.ts), GNvisibilityand dependency edges, strictcore -> models -> ui -> panelslayering,SettingDescriptorplacement in the lowest layer where used, public widget/component APIs (DEFAULT_VIEWinput/output contracts), CDP protocol contracts, and test validity. - Avoid uncodified interior style nits: Do not flag subjective stylistic
preferences inside module interiors unless backed by a lint rule or an
explicit rule under
.agents/rules/.
4. Shared False-Positive Guards
Check these guards before reporting any finding (including general review findings):
- Lit
@SomeEvent=${handler}bindings on<devtools-widget>(or a widget'selement):- Do not flag
@SomeEvent=${handler}as "never fires" or "lowercased by the HTML parser" when the child widget class is built withCommon.ObjectWrapper.eventMixin(...)on top ofUI.Widget.Widget/UI.Widget.VBox/UI.Widget.HBox:eventMixin.dispatchEventToListeners(front_end/core/common/Object.ts) also callsthis.dispatchDOMEvent(new CustomEvent(eventType, {detail: eventData[0]})), andWidget.dispatchDOMEventdispatches it onwidget.element(which is the<devtools-widget>host element when instantiated withwidget()).- Lit preserves the exact case of
@,., and?binding names by reading the original template strings (attrNames[]infront_end/third_party/lit/lib/lit.js), not the lowercased attribute names from the HTML parser. So@PaintProfilerRequestedregistersaddEventListener('PaintProfilerRequested', ...), andevent.detailcarries the first payload argument.
- Do flag it when:
- The event source extends
Common.ObjectWrapper.ObjectWrapperdirectly or holds one by composition instead ofeventMixinonUI.Widget(it has nodispatchDOMEvent, so no DOMCustomEventis fired). - The listener is attached on an ancestor element above the widget's
host element (
new CustomEvent(...)inObject.tsdoes not setbubbles: true). - The
@SomeEventhandler reads(event as any).datainstead of(event as CustomEvent<T>).detail.
- The event source extends
- Do not flag
- Multi-line
htmltemplate whitespace (front_end/ui/lit/strip-whitespace.ts):- Do not flag newlines and indentation spaces between expressions and
inline elements in multi-line
htmltemplates fromui/lit/lit.js. DevTools' customhtmltag strips\n\s*outside<...>tags at runtime.
- Do not flag newlines and indentation spaces between expressions and
inline elements in multi-line
- Generated
.css.jsimports in<style>${styles}</style>:- Do not flag interpolating
*.css.jsdefault imports into<style>in Lit templates. Generated.css.jsfiles export plain CSS strings, notCSSStyleSheetobjects.
- Do not flag interpolating
5. Test correctness (the most common review feedback)
- Tautological tests: A test must exercise real production code. If a
mock does the thing the test asserts (for example, a mocked
DOM.undothat callsremoveSection()directly, followed by an assertion that the section was removed), the test checks the mock and nothing else. Mock the boundary instead (for example, have the CDP stub emitCSSModel.Events.StyleSheetChanged) and let production code react to it. - Vacuous tests: Look for local promises or data that are never connected
to DevTools logic, or stubs (like
initialize) that skip the code path under test. These tests pass because nothing happens. - Assertions that check the setup: For example,
assert.isNull(pane.node())right afterpane.setNodeForTest(null). Each assertion should verify the behavior that the test name describes. - Test lives where it belongs: A test in
Foo.test.tsshould exerciseFoo. Move logic-only tests to the model's test file (for example,CSSMatchedStyles.test.ts). Otherwise, render the UI and assert on the DOM. - Test covers the scenario it claims: For example, an "iframe event
listeners" test must select a node inside the iframe. It is not enough
that it passes on
<body>of the main frame. - Right suite: Ask whether an E2E test could be a unit test, or whether the
E2E coverage is intentional for a user story. See
devtools-testing-guidance. - E2E selectors match real UI: Labels and
aria-labels must match the actual strings, for example "Show user agent shadow DOM" and not "User agent shadow DOM". Check that the setting being toggled actually affects the scenario. - Fail fast: Throw or assert when a required value is missing. Don't let the test time out later.
- Pre-migration tests for legacy widgets: When reviewing tests added ahead of
replacing a legacy widget (
TreeOutline,DataGrid,ListControl,ListWidget), check that DOM/tree inspection is encapsulated in local test helpers (dumpTree(),findTreeItem(),activateRow()) rather than repeated across everyit()block, and ask forassertScreenshot(...)golden tests so visual regressions are caught independently of the legacy widget implementation.
6. Test hygiene and cleanup
- Pair every
beforeEachsingleton creation with a cleanup inafterEach(for example,CSSWorkspaceBinding.removeInstance()orWorkspaceImpl.removeInstance()) so that state does not leak between tests. - Restore fake timers in
try { … } finally { clock.restore(); }, or use the sandbox or cleanup that the test runner provides. Keep the scope of fake timers small. - Don't stub the same method twice without calling
restore()first. Sinon throwsAttempted to wrap … which is already wrappedwhen the object is the same instance. - Remove guards that were copied from helpers for no reason (for example,
if (!stub.called) …in a test that stubs the method only once).
7. Code clarity
- Don't take detours to reach a value. If a module is imported, call
TextUtils.TextRange.TextRange.fromObject(...)directly instead of going throughrule.style.range.constructor. - Look for dead code, leftover debug code, commented-out blocks, and unrelated formatting churn.
- Check that the change stays in scope. Flag unrelated refactors that should be split into a separate CL.
- Check for lifecycle issues: event listeners and observers that are added without being removed, and async work that continues after a widget is detached.
8. CL hygiene
- The description explains why, including external dependencies (for example, "V8 will stop emitting X; this must land first").
- Include a
Bug:orFixed:trailer, orBug: None. Keep lines under 72 characters. - For migrations and stacked series, list the legacy tests or files covered,
and number the series (for example,
(13/16)). - UI Eng Vision migration completeness &
Fixed:vsBug:: FlagFixed: <id>on UI Eng Vision migration CLs when core violations remain in the target file: legacyUI.TreeOutlineorextends UI.TreeOutline.TreeElementsubclasses,UI.ListControl,UI.ListWidget,UI.InplaceEditor, non-MVP constructors (missingelement?: HTMLElementor injectableview = DEFAULT_VIEW), missingstatic override readonly INJECTfor Universe dependencies, custom#renderView()helpers bypassingoverride performUpdate()+this.requestUpdate(), constructor-bound model/setting listeners instead of non-destructivewasShown()/willHide()subscriptions, synchronousthis.performUpdate()calls in presenter methods, or TypeScriptprivatefields not required bylegacy_test_runner/blink/web_tests. Note explicitly that a clean@devtools/no-imperative-dom-apilint pass does not prove completeness because ESLint missesTreeElementsubclasses andUI.ListControl. Intermediate CLs in a multi-CL migration must useBug: <id>, reservingFixed: <id>for the final CL. - Component contract preservation: Flag feature or panel migrations that
widen
front_end/ui/legacy/component contracts (such as exporting internal classes or turning*ForTest()or*ForTesting()methods onTreeoutline.tsinto public APIs). - Disabled tests reference a bug.
- Presubmit, lint, and format pass. See
devtools-verification.
9. Writing review comments
- Be specific: cite file and line, explain the concrete failure mode (such as a leak, a hang, or "passes vacuously"), and suggest a fix. Include a code snippet when it helps.
- Separate blocking issues from nits and questions (for example, "Should we move this to a unit test?").
- When a reviewer's concern is not an actual bug, reply with the rationale. Don't make a silent change.