chrome-devtools-frontend 1.0.1652307 → 1.0.1656291

package/.agents/skills/fixing-skipped-tests/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: fixing-skipped-tests
+description: Use this skill when unskipping a test that was previously skipped.
+---
+# Fixing Skipped Tests
+
+This skill outlines the workflow for fixing skipped tests in the DevTools codebase, typically given a Chromium bug link (e.g., `crbug.com/1234567`).
+
+## Workflow
+
+1. **Extract the Bug ID**
+   - The input is typically a bug link like `crbug.com/<bugid>`. Extract the `<bugid>` from the link.
+
+2. **Create a Branch**
+   - Create a new branch named `fixed-<bugid>`.
+   - Ensure you use the instructions from the `devtools-version-control` skill to create and switch branches appropriately.
+
+3. **Search for the Skipped Tests**
+   - Search the codebase for the `<bugid>` to find skipped tests.
+   - You should look for occurrences like `it.skip('[crbug.com/<bugid>] ...', ...)` or skipped describes that mention the bug ID.
+
+4. **Iterative Fix Process**
+   - **Step 1:** Change `it.skip` or `describe.skip` to `it.only` or `describe.only` for *one* of the tests associated with the bug, so that only that specific test runs.
+   - **Step 2:** Re-run the tests (e.g., `npm run test -- <path_to_test_file>`) using the guidelines from the `devtools-verification` skill. If you are dealing with flaky tests, you can use the `--repeat=x` flag (e.g. `npm run test -- <path_to_test_file> --repeat=20`) to run the test multiple times to reproduce the flakiness.
+   - **Step 3:** Analyze the test failure and make the necessary fixes to the code or the test itself.
+   - **Step 4:** Re-run the test to ensure the fix is correct. Remove `.only`.
+   - **Step 5:** Remove the `[crbug.com/<bugid>]` prefix from the test name string if it is present.
+   - **Step 6:** Remove any comments directly above the test that explain the reason why the test was skipped (e.g., `// TODO(crbug...): Flaky`).
+   - **Step 7:** Apply the fix to the remaining tests, un-skipping them one by one or in batches, and verifying until all are passing.
+
+5. **Verify Full Build**
+   - Before finishing, run the full verification process (TypeScript checks, linters, full test run) as required by the repository best practices.

package/.agents/skills/migrate-chromium-test/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: devtools-migrate-chromium-test
+description: Use when migrating chromium `third_party/blink/web_tests/http/tests/devtools/` tests to modern unit tests in `third_party/devtools-frontend/src/front_end/`.
+---
+
+# Migrating Legacy DevTools Tests
+
+The skill should be used from within a Chromium check out. The agent should make a devtools CL for the changes in `third_party/devtools-frontend`.
+
+## Workflow
+
+1.  **Identify the Test to Move**:
+
+- Locate the legacy test file (usually `.js`) and its expectation file (`-expected.txt`) in `third_party/blink/web_tests/http/tests/devtools/`.
+- Example: `unit/datagrid-editable-longtext.js`
+
+2.  **Identify the Target Location**:
+
+- Find the file being tested in `third_party/devtools-frontend/src/front_end/`.
+- Place the new test file next to the file being tested, following the naming convention `[FileName].test.ts`.
+- Example: If testing `ui/legacy/components/data_grid/DataGrid.ts`, the test should be `ui/legacy/components/data_grid/DataGrid.test.ts`.
+
+3.  **Convert the Test Content**:
+
+- Rewrite the test from the legacy `TestRunner` style to the modern Mocha/Chai style used in DevTools.
+- Use `describeWithEnvironment` or `describe` as appropriate.
+- Replace `TestRunner.addResult` and expectation comparisons with standard assertions (`assert.strictEqual`, `assert.isTrue`, etc.).
+- If the test requires rendering, use `renderElementIntoDOM` to attach elements to a test container.
+- If testing legacy components that require internal tokens or have private methods, try to use public APIs or events instead. If impossible, consider using structural typing workarounds or updating the component to be more testable.
+- If tests require a repetitive setup extract it into a test helper function at the top of the file.
+
+4.  **Update BUILD.gn**:
+
+- Add the new test file to the `sources` list of the `devtools_ui_module("unittests")` or `devtools_foundation_module("foundation_unittests")` target in the corresponding `BUILD.gn` file.
+
+5.  **Verify the Changes**:
+
+- Build the unittests target: `autoninja -C out/Default <target_path>:unittests`
+- Run the test using the DevTools test runner: `npm run test -- <relative_path_to_test>`
+- Ensure the test passes.
+
+6.  **Clean Up**:
+
+- Delete the original legacy test file and its expectation file from `third_party/blink/web_tests/...`.
+- _(Optional)_ If instructed by the user, you may leave the files or handle them differently.
+
+## Example Conversion
+
+### Legacy Test (`datagrid-editable-longtext.js`)
+
+```javascript
+import { TestRunner } from 'test_runner';
+import * as DataGrid from 'devtools/ui/legacy/components/data_grid/data_grid.js';
+
+(async function () {
+  TestRunner.addResult('This tests long text in datagrid.');
+  // ... setup grid ...
+  TestRunner.addResult('Original lengths');
+  // ... dump results ...
+  TestRunner.completeTest();
+})();
+```
+
+### Converted Test (`DataGrid.test.ts`)
+
+```typescript
+import * as DataGrid from './data_grid.js';
+import { renderElementIntoDOM } from '../../../../testing/DOMHelpers.js';
+import { describeWithEnvironment } from '../../../../testing/EnvironmentHelpers.js';
+
+describeWithEnvironment('DataGrid', () => {
+  it('tests long text in datagrid', () => {
+    // ... setup grid ...
+    // Use assertions instead of printing results
+    assert.strictEqual(keyElement.textContent.length, 1500);
+  });
+});
+```
+
+## Tips & Troubleshooting
+
+- **TypeScript Type Mismatches**: Legacy tests often use plain strings for properties that now require specific branded types like `LocalizedString`. You can often bypass this in tests by casting the object array `as DataGrid.DataGrid.ColumnDescriptor[]` or similar, or by using `i18n.i18n.lockedString` if appropriate.
+- **Accessing Private Methods**: Legacy tests frequently called private methods (e.g., `dataGrid.update()`). In TypeScript unit tests, you should avoid this. Look for public alternatives (e.g., `updateInstantly()`) or trigger the behavior by dispatching standard DOM events (e.g., `element.dispatchEvent(new Event('scroll'))` instead of calling `onScroll()`).
+- **Recursive Expansion Limits**: Methods like `TreeElement.expandRecursively()` have a default depth limit (e.g., 3) to prevent infinite loops. If your test requires expanding deeper trees, remember to pass a higher max depth argument: `expandRecursively(10)`.
+- **Mocking Objects**: When testing UI components that display objects (like `RemoteObject`), look for existing mock helpers in related test files (e.g., `createDeepRemoteObjectMock` in `ObjectPropertiesSection.test.ts`) instead of trying to create real SDK objects or complex mocks from scratch. Other helpers live inside `front_end/testing`.
+- **Ignoring Environment Failures**: In some environments, `npm run test` may exit with code 1 due to memory leaks (e.g., `WebFrame LEAKED`) or infrastructure issues (e.g., `gpkg` or `Corp Airlock` logs), even if the tests themselves passed. Always check the end of the test log for `TOTAL: X SUCCESS` to confirm if the test logic was successful.
+- **Rendering issue**: If you encounter an issue where checking values never gives correct information it may be due to async rendering. To resolve that you may trying using `raf()` from `front_end/testing/DOMHelpers.ts` to wait for the next rendering cycle.
+
+## Creating a DevTools CL from a Chromium Checkout
+
+To create a DevTools Change List (CL) from a Chromium checkout, you'll be working within the devtools-frontend repository, which is located inside your Chromium source tree. The depot_tools package (which includes git cl) must be in your PATH.
+
+Here's the typical workflow:
+
+1.  **Navigate to the DevTools Frontend Directory**:
+    The DevTools frontend code resides in `third_party/devtools-frontend/src/` within your Chromium checkout (`chromium/src`).
+
+```bash
+cd path/to/chromium/src/third_party/devtools-frontend/src/
+```
+
+2.  **Create a New Branch**:
+    It's best practice to create a new branch for your changes:
+
+```bash
+git new-branch my-devtools-feature
+```
+
+(Or use `git checkout -b my-devtools-feature`)
+
+3.  **Make Your Code Changes**:
+    Edit the files as needed for your feature or bug fix.
+
+4.  **Commit Changes Locally**:
+    Stage and commit your changes using standard Git commands:
+
+```bash
+git add .
+git commit -m "My DevTools feature description"
+```
+
+_See the Chromium guide on commit messages for best practices on formatting descriptions, including the use of tags like Bug:. _
+
+5.  **Upload the CL for Review**:
+    Use `git cl upload` to send your changes to the Chromium Gerrit code review system:
+
+```bash
+git cl upload
+```
+
+This command will create a CL on `https://chromium-review.googlesource.com`. Follow the prompts to add a description, reviewers, etc. You can also add reviewers and trigger builds through the Gerrit web UI.
+
+6.  **Code Review Process**:
+    Your CL will be reviewed by DevTools owners. You may need to address feedback by amending your commit and uploading new patch sets using `git cl upload` again. Once approved, you can land the change via the Commit Queue (CQ).
+
+### Working on Changes Across DevTools and Chromium Core
+
+- DevTools frontend (`third_party/devtools-frontend/src/`) and the main Chromium codebase (`chromium/src`) are distinct Git repositories.
+- If your work involves changes in both areas, you generally need to create separate CLs: one within the devtools-frontend repo and one within the main `chromium/src` repo.
+- The "Juggling the git submodules" section of the DevTools documentation provides guidance on managing these cross-repository changes.
+
+## After finishing the migration
+
+Identify any helping tips that you discovered during the migration and add them to this skill.

package/.agents/skills/ui-eng-vision-local-lit-renderer/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: ui-eng-vision-local-lit-renderer
+description: Migrates legacy imperative DOM construction to local declarative Lit-html templates rendered inside existing containers.
+allowed-tools: code_search open_urls
+---
+
+# Subskill: Local Lit-HTML Renderer (Pass 2)
+
+This subskill converts consolidated imperative DOM construction helper methods
+into reactive, declarative Lit-html templates, rendering them locally inside the
+existing element containers.
+
+--------------------------------------------------------------------------------
+
+## 1. Declarative Technology Migration
+
+1.  **Conserve Abstraction Topology**:
+
+    *   Maintain the existing class hierarchy, helper class boundaries, and
+        logical groups.
+    *   Do not aggressively "flatten" classes or collapse helper abstractions
+        into the main view just to coerce a single master template. Pass 2
+        should only change the *implementation details* of rendering (imperative
+        -> declarative) within existing compartments, not the public API or
+        responsibilities of objects.
+
+2.  **Determine Render Lifecycle per Layer**:
+
+    *   **For UI.Widget classes**: Define or update `performUpdate()` to execute
+        the main lit `render` call, and use `this.requestUpdate()` to queue
+        updates.
+    *   **For Delegate/Helper classes**: Identify the custom update hook (e.g.,
+        `update()` or `scheduleUpdate()`) and invoke `render()` directly inside
+        that method. **Do not** introduce Widget lifecycle methods
+        (`performUpdate`) on classes that do not inherit them.
+
+3.  **Import Modern Templating**:
+
+    *   Import the `Lit` rendering system inside the view module:
+
+        ```typescript
+        import {html, render, nothing} from '../../ui/lit/lit.js';
+        ```
+
+4.  **Modern Component Mapping**:
+
+    *   Refer to [ui_engineering.md](../../../docs/ui_engineering.md) for
+        specific migration examples.
+    *   If unsure, also consult the [automatic migration code](../../../scripts/eslint_rules/lib/no-imperative-dom-api.ts)
+
+5.  **Local Modular Renders**:
+
+    *   If the class contains multiple separate legacy container fields (e.g.,
+        fields generated by `appendField` or `createChild` on a parent layout),
+        prefer **local modular renders** (rendering templates individually into
+        each container) to preserve the legacy layout framework. Do not force a
+        monolithic template if doing so violates the existing topology.
+
+6.  **Resolve TypeScript Type Friction**:
+
+    *   Legacy DevTools elements may be typed as `Element`. Lit's `render()`
+        function expects `HTMLElement | DocumentFragment`.
+    *   When rendering into legacy containers, cast the container using `as
+        HTMLElement` or update its class property type definition from `Element`
+        to `HTMLElement` to satisfy the TypeScript compiler.
+    *   Example: `render(this.template(), this.containerField as HTMLElement);`
+
+7.  **Delegate to Unmigrated Rendering Engines**:
+
+    *   Do not attempt to rewrite complex historical subsystems (like Linkifiers
+        or specialized UI utilities) to be "pure Lit" during this pass.
+    *   Capitalize on Lit's ability to interpolate standard `HTMLElement` or `Element` instances directly. Treat unmigrated utilities as "black boxes" that generate DOM, and embed their output in standard template expressions: `html`<div>${this.legacyElement}</div>``.
+
+8.  **Handle Asynchronous DOM Updates**:
+
+    *   For asynchronous callback-driven updates (e.g., elements updated in a
+        `.then()` callback), render the parent container or a placeholder
+        template first. Once the data is retrieved, execute a local `render()`
+        inside the callback targeting the specific sub-container.
+
+9.  **Template Factorization Strategies**:
+
+    *   **Prefer `nothing`**: Use Lit's `nothing` sentinel instead of empty
+        strings `''` or empty templates for conditional rendering.
+    *   **Parameterized Fragment Factories**: For repeated UI patterns or
+        intermediate layout branches, extract them into parameterized helper
+        functions inside the class scope returning `LitTemplate`. This avoids
+        monoliths, preserves readability, and reuses template cache strategies.
+
+10. **Visual Parity and Accessibility**:
+
+    *   **Zero-Tolerance Regression**: Screenshot tests are the ground truth for this phase. Any visual diff (above 0%) in the generated screenshots is unacceptable and must be resolved before proceeding.
+    *   **Strict Tag/Class Parity**: Do not change tag types (e.g., `span` to
+        `div`) or drop class names during template translation, as CSS may
+        depend on them.
+    *   **Explicit Component Variants**: Modern Custom Element (e.g.
+        `<devtools-button>`) defaults may not match legacy appearance.
+        Explicitly bind `.data=${{variant: Buttons.Button.Variant.OUTLINED}}`
+        (or appropriate variant) rather than relying on defaults.
+    *   **Accessibility Preservation**: Convert custom accessibility
+        instrumentation (like `ARIAUtils.markAsAlert()`) to native ARIA
+        attributes in the template (e.g., `role="alert"`, `aria-live="polite"`).
+
+11. **Render Templates Syntax & Code Movement**:
+
+    *   Surround the expressions containing lit template literals with `//
+        clang-format off` and `// clang-format on` to prevent clang-format from
+        corrupting template indentation.
+    *   **Minimize Code Movement**: Avoid moving existing code to a different location in the file. Put the function signature around the existing code to minimize the diff.
+    *   The Gerrit Code Review UI cannot identify moved blocks of unchanged code.
+    *   If blocks of code need to be reordered, create a "prefactoring" change that first extracts the code that needs to be reordered into a named helper functions and pause the migration, waiting user confirmation.
+
+12. **Wait for confirmation**:
+
+    *   Wait for an explicit confirmation from the user before proceeding to the
+        next step.

package/.agents/skills/ui-eng-vision-logic-consolidator/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: ui-eng-vision-logic-consolidator
+description: Consolidates manual DOM creation, updates, and constructors into private helper methods and structured state interfaces.
+allowed-tools: code_search open_urls
+---
+
+# Subskill: Logic Consolidator (Pass 1)
+
+This subskill extracts manual layout building, attribute modifications, and
+rendering loops out of the constructor and scattered event handlers,
+consolidating them into private helper methods with explicit data contracts.
+
+--------------------------------------------------------------------------------
+
+## 1. Logic Consolidation Rules
+
+1.  **Identify UI updates Creation**:
+
+    *   Scan the class constructor and search for manual DOM operations (e.g.,
+        `element.createChild('div')`, `document.createElement`,
+        `element.appendChild`).
+    *   Also look for any UI updates which call lit-html `render`.
+
+2.  **Isolate Update and Draw Operations**:
+
+    *   Group the imperative creation/update lines into dedicated private helper
+        methods (e.g., `#updateSummaryBar(...)` or `#createEditorToolbar(...)`).
+    *   Group event-handling updates (e.g., state variables like `pageSize`,
+        modified during buttons clicks) into centralized functions like
+        `onPageSizeChanged`.
+
+3.  **Define the State Interface**:
+
+    *   Identify the class state and ensure it is captured in the private member
+        variables, e.g.
+
+        ```typescript
+        #entries: Entry[];
+        #canGoBack: boolean;
+        #canGoForward: boolean;
+        #staleWarningVisible: boolean;
+        ```
+
+    *   Replace direct mutations of UI with updates to these member variables,
+        followed by a call to the public `performUpdate()` method that is
+        calling previously extracted update helpers. Use this specific
+        identifier.
+
+    *   If there's only one or two update helpers, consider inlining them into the
+        `performUpdate`.
+
+4.  **Extract/Consolidate Rendering Operations**:
+
+    *   If Logic First (imperative DOM remains), make sure all updates to the UI
+        go through the performUpdate method
+    *   If Lit First (Lit template already exists), make sure there's a single
+        master call to Lit render inside performUpdate. The master template
+        might include calls to the helper functions e.g.
+
+        ```typescript
+        render(html`
+          <div class="specific-view">
+            <span>View Title</span>
+            ${this.renderOverviewSection()}
+          </div>
+        `, this.contentElement);
+        ```
+
+5.  **Minimize Diffs (Safety Rule)**:
+
+    *   Avoid moving existing code to a different location in the file. Put the
+        function signature around the existing code to minimize the diff.
+    *   The Gerrit Code Review UI cannot identify moved blocks of unchanged
+        code.
+    *   If blocks of code need to be reordered, create a "prefactoring" change
+        that first extracts the code that needs to be reordered into named
+        helper functions and pause the migration, waiting for user confirmation.
+
+6.  **Wait for confirmation**:
+
+    *   Wait for an explicit confirmation from the user before proceeding to the
+        next step.

package/.agents/skills/ui-eng-vision-orchestrator/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: ui-eng-vision-orchestrator
+description: High-level orchestrator for managing multi-pass migration of Chrome DevTools legacy components to the modern UI engineering vision (UI.Widget & Lit-html).
+allowed-tools: code_search open_urls search_changelists data_analysis import_skill close_skill
+---
+
+# UI Engineering Vision Orchestrator: Meta-Skill Instructions
+
+This meta-skill acts as the central coordinator for modernizing legacy Chrome
+DevTools views into declarative `UI.Widget` components based on lit-html,
+managing a multi-pass sequential CL pipeline to ensure each code modification is
+small, testable, and highly reviewable.
+
+Refer to [ui_engineering.md](../../../docs/ui_engineering.md) for general principles.
+
+--------------------------------------------------------------------------------
+
+## 1. Migration Philosophy & Plan-Validate-Execute Pattern
+
+1.  **The Plan-Validate-Execute Principle**: For each target file, the
+    orchestrator must first generate a structured `migration_plan.md` listing
+    the exact transformations, file targets, and subskills allocated for each
+    pass.
+2.  **User Acceptance Gate**: The orchestrator must halt execution and present
+    the migration plan to the user. No code modification, subskill loading, or
+    CL staging can occur until the user explicitly accepts the plan.
+3.  **No Assumptions on Inheritance**: Do not assume the class hierarchy in a
+    file matches older patterns or generic examples. Always perform a structure
+    analysis of the active file first and adapt the plan to the actual, current
+    code.
+4.  **Hybrid Files**: Files may contain multiple classes in different states of
+    modernization (e.g., one partially migrated class and one fully legacy
+    class). Propose modifications only for classes with actual violations.
+5.  **Coupling Analysis**: Always check the integration files (e.g., sidebar
+    files, parent panel files) where the target class is instantiated to see if
+    there are any direct `.element` or `.contentElement` couplings. If found,
+    include the decoupling of these references in the plan.
+6.  **Neighboring Component Reference**: Inspect neighboring modernized files of
+    the same archetype (e.g., `DOMStorageItemsView.ts` or
+    `KeyValueStorageItemsView.ts` for storage-like components) to find proven
+    patterns for toolbar and data-grid configurations.
+7.  **The Narrow Bridge Principle**: Keep code modifications tightly scoped to a
+    single responsibility per CL. Do not combine technology migrations (e.g.,
+    converting imperative DOM to Lit-html) with base class refactoring in the
+    same diff.
+8.  **Never Break Compilation**: Run a compiler build and execute the DevTools
+    test suite between every pass.
+9.  **Establish Comprehensive Guardrails First**: Ensure both **logic tests**
+    (verifying presenter interactions and state updates) and **screenshot tests**
+    (verifying layout/styling) exist before rewriting code. If coverage is
+    missing, scaffold it first.
+
+--------------------------------------------------------------------------------
+
+## 2. Multi-Pass Execution Lifecycle
+
+### Plan Generation (Gated)
+
+*   **Actions**:
+    1.  Scan the target file to determine size, complexity, legacy elements
+        (e.g., `ReportView`, `ToolbarButton`, `DataGrid`, `TreeOutline`), and
+        actual class inheritance. Deconstruct the file mentally (or in the plan)
+        into **Business Logic** (state, event handlers) and **Rendering Logic**
+        (DOM creation, CSS classes). Reference code elements by **Name** (not
+        line numbers) to ensure the plan remains valid as the codebase evolves.
+        Check if the class dependencies have been migrated to the ui eng vision or not.
+    2.  Check the files depending on this file, to understand how the code in
+        this file is being used.
+    3.  **Dynamic Ordering Decision**: Determine whether to run
+        Logic Consolidation first or Local lit-html rendering first:
+        *   **Option A (Logic First)**: Choose this if the component has a
+            complex, nested state model or highly coupled event-handlers.
+            Consolidating the state variables and defining the `ViewInput`
+            interface first provides a clean data contract, making the
+            subsequent template conversion highly deterministic.
+        *   **Option B (Technology First)**: Choose this if the component has a
+            relatively simple state flow but massive, deeply nested imperative
+            DOM construction. Converting the layout to declarative Lit templates
+            first (using temporary inline or local state) makes it much easier
+            to isolate and group the remaining state updates afterward.
+    4.  Generate a `migration_plan.md` reflecting this ordering and outlining
+        the target steps.
+    5.  Halt execution and print the formatted plan in Markdown to the chat.
+        Wait for user approval.
+
+### Baseline & Safety Scaffolding
+
+*   **Trigger Condition**: User explicitly says "I accept the plan" or
+    equivalent.
+*   **Subskill to Import**: `ui-eng-vision-test-scaffolder`
+*   **Actions**:
+    1.  Verify existing test coverage. Propose and add missing **logic tests**
+        for interactions and **screenshot tests** for visual validation to avoid regressions.
+    2. Pay extra attention not to skip this step.
+
+### Logic Consolidation
+
+*   **Trigger Condition**: Baseline tests green (or respective previous pass
+    staged).
+*   **Subskill to Import**: `ui-eng-vision-logic-consolidator`
+*   **Actions**:
+    1.  Extract manual elements, constructor DOM configurations, and imperative
+        updates into private update helper methods with structured
+        state-passing.
+
+### Local Lit-HTML Rendering (Technology Migration)
+
+*   **Trigger Condition**: Previous pass staged.
+*   **Subskill to Import**: `ui-eng-vision-local-lit-renderer`
+*   **Actions**:
+    1.  Migrate imperative elements to declarative templates (using component
+        mapping rules defined inside the subskill) and render them locally
+        within the existing view.
+
+### Widget Promotion (Architectural Bridge)
+
+*   **Trigger Condition**: Both local template rendering and logic consolidation
+    staged.
+*   **Subskill to Import**: `ui-eng-vision-widget-promoter`
+*   **Actions**:
+    1.  Promote view classes to modern `UI.Widget` classes, hook up
+        `performUpdate()` delegates, export the default view layout, and clean
+        up legacy wrappers.

package/.agents/skills/ui-eng-vision-test-scaffolder/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: ui-eng-vision-test-scaffolder
+description: Scaffolds unit tests and screenshot tests to establish visual and functional rendering baselines for views before refactoring.
+allowed-tools: code_search open_urls
+---
+
+# Subskill: Test Scaffolder
+
+This subskill establishes the safety net of existing and new visual/functional
+tests before any codebase modifications occur, ensuring that no rendering or
+logical regressions are introduced during modernization.
+
+--------------------------------------------------------------------------------
+
+## 1. Test Verification Lifecycle
+
+1.  **Verify Existing Tests**:
+
+    *   Inspect the corresponding unit test file (e.g., `IndexedDBViews.test.ts`
+        for `IndexedDBViews.ts`) under the target folder or `test/unittests/`.
+    *   Check for **logic tests** (verifying presenter interactions and view function callbacks).
+    *   Check for screenshot or interaction tests (under `test/interactions/` or
+        `test/goldens/`) matching the visual component to verify layout and styling.
+
+2.  **Detect Sub-component Testing Gaps (Hybrid Files)**:
+
+    *   Identify if the existing test suite only covers one class of a hybrid
+        file while missing another class being migrated (e.g., tests exist for
+        `IDBDatabaseView` but are scarce/missing for `IDBDataView`).
+
+3.  **Scaffold Missing Tests**:
+
+    *   If **logic tests** are missing, draft tests verifying that callbacks trigger the expected state updates or model interactions.
+    *   If **rendering/screenshot tests** are missing or inadequate for the legacy class being
+        migrated, draft a basic Mocha/Chai rendering test.
+    *   Verify that the component compiles and mounts successfully inside a
+        synthetic DOM helper or unit-test container.
+    *   **Screenshot Tests**: Create screenshot tests to establish visual baselines before refactoring. Follow the pattern seen in `CategorizedBreakpointsSidebarPane.test.ts`:
+        *   First run the test having `renderElementIntoDOM` with `{includeCommonStyles: true}` to ensure styles are applied.
+        *   The first run will generate the screenshot.
+        *   Now try removing `{includeCommonStyles: true}` to see if class is
+            adding the styles itself. If the test pass, keep the version without
+            `{includeCommonStyles: true}`. Otherwise, bring it back.
+        *   Screenshot tests are unittests that render either the full widget (if not migrated to the MVP architecture) or its view function (if already in MVP shape).
+        *   When testing view-separated components, prefer testing the View function (e.g., `DEFAULT_VIEW`) directly by passing mock state and callbacks.
+        *   Use `assertScreenshot` to capture and verify the visual output.
+        *   Example structure:
+
+            ```typescript
+            it('renders the view', async () => {
+              const target = document.createElement('div');
+              renderElementIntoDOM(target, {includeCommonStyles: true});
+              MyComponent.DEFAULT_VIEW(mockViewInput, undefined, target);
+              await assertScreenshot('my_component/base.png');
+            });
+            ```
+
+4.  **Wait for confirmation**:
+
+    *   Wait for an explicit confirmation from the user before proceeding to the next step.
+
+--------------------------------------------------------------------------------
+
+## 2. Environment Detection & Test Execution Guide
+
+Always detect the execution environment first to run tests successfully:
+
+### Scenario A: Google-Internal Cog/Cider Workspaces (PRIMARY PATH for Google Workspaces)
+
+*   **Detection**: Triggered if the workspace path starts with `/google/cog/` or
+    `/google/src/`.
+*   **Why it is required**: Raw commands like `npm run test` or `autoninja` fail
+    because they lack Google cloudtop/virtualization wrapper configurations.
+*   **Resolution Steps**:
+
+    1.  Do not run `npm run test` or standard `autoninja` directly.
+    2.  Leverage the Google-specific Cider testing script to compile and run
+        tests in the cloud workspace:
+
+        ```bash
+        python3 internal/infra/scripts/cider/init_workspace.py test /google/cog/cloud/username/workspace_name --test_filter=front_end/panels/application/IndexedDBViews.test.ts
+        ```
+
+### Scenario B: Standard Chromium Environment (Fallback)
+
+*   **Detection**: Triggered if in an open-source or local standard Chromium
+    checkout without Cog paths.
+*   **Troubleshooting vpython3 / depot_tools errors**:
+
+    *   **Symptom**: Command fails with `vpython3: command not found` or
+        `python3_bin_reldir.txt not found`.
+    *   **Resolution Steps**:
+
+        1.  Export `depot_tools` path:
+
+            ```bash
+            export PATH=$PATH:/path/to/depot_tools
+            ```
+
+        2.  Initialize the depot_tools binaries by running update/gclient help
+            once from the checkout root:
+
+            ```bash
+            update_depot_tools
+            ```
+
+        3.  Execute the tests:
+
+            ```bash
+            npm run test -- front_end/panels/application/IndexedDBViews.test.ts
+            ```
+
+### Scenario C: ESLint TS Module Resolution Failure (ERR_UNKNOWN_FILE_EXTENSION)
+
+*   **Symptom**: Running lint checks fails with: `TypeError
+    [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for
+    scripts/eslint_rules/...`
+*   **Resolution Steps**:
+
+    1.  Compile the custom eslint rules and build assets first so that Node can
+        parse the rules:
+
+        ```bash
+        npm run build
+        ```