[QA] Cover core visual settings and document the visual-test contract

[YangSiJun528]

Summary

After #30 defines the supported ownership and restoration behavior for IntelliJ's native editor visuals, expand the deterministic Driver suite to cover the minimum set of Bracket Pair Guides settings that produce meaningfully different editor output.

Keep this coverage intentionally small and feature-oriented. Each capture should isolate one user-visible rendering responsibility, while ordinary tests cover state-machine branches that do not require visual inspection.

This is follow-up work for #33 and must also leave a maintained reference for future changes to the Driver harness, baselines, GitHub Actions producer, and trusted reporter.

Dependency

• Depends on [Enhancement] Detect and manage overlapping IntelliJ editor guides #30.
• Do not implement or partially duplicate [Enhancement] Detect and manage overlapping IntelliJ editor guides #30 in this issue.
• Preserve the Repeated vertical lines #27 repeated-line reproduction as a visual contract for [Enhancement] Detect and manage overlapping IntelliJ editor guides #30's final behavior.
• Record the final native-visual baselines only after [Enhancement] Detect and manage overlapping IntelliJ editor guides #30's settings model and restoration behavior are stable.

Minimum visual scenarios

Use fixed Darcula fixtures, caret positions, viewport geometry, font, scale, and platform-specific baseline keys. Within each comparison group, change only the setting named by the scenario.

Rendering components

• horizontal-only: show the horizontal active-guide segments without the vertical segment, pair border, or pair background.
• vertical-only: show the vertical active-guide segment without horizontal segments, pair border, or pair background.
• pair-border-only: show the active-pair border without guide segments or pair background.
• pair-background-only: show the active-pair background without guide segments or pair border.
• all-components: show horizontal and vertical guides, pair border, and pair background together.
• bracket-colorization-off: keep a visible guide while restoring bracket tokens to the IntelliJ syntax colors.

Settings application and native visuals

Start the native-integration fixture with matched-brace highlighting, Current scope, and regular indent guides enabled.

• plugin-disabled: begin from a decorated editor, disable Bracket Pair Guides through production applySettings(...), and verify that plugin rendering disappears.
• native-visuals-unmanaged: leave the IntelliJ visual settings unchanged and show their visible coexistence with the plugin guide.
• native-highlight-suppressed: apply [Enhancement] Detect and manage overlapping IntelliJ editor guides #30's default native-highlight mode while keeping regular IntelliJ indent guides enabled.
• native-indent-hidden: additionally hide regular IntelliJ indent guides so that only the plugin guide remains in the code area.

Re-enabling the plugin must reproduce the existing all-components baseline. Disabling the integration gate or plugin must restore the original native values and reproduce the existing unmanaged native state. These restoration checks should reuse existing baselines instead of adding duplicate gallery images.

Colors

• default-palette: render several nesting levels with the built-in palette.
• custom-palette: apply clearly distinct bracket, guide, border, and background colors through production applySettings(...) and verify the live editor update.

Harness rules

• Keep the coverage in the existing visualTest source set; do not create another module.
• Start the IDE once and run all scenarios sequentially in the same Driver session.
• Reset plugin preferences, native settings, caret, selection, folding, and viewport state before each scenario.
• Apply committed plugin preferences through the same production applySettings(...) path used by the Settings UI.
• Use the test-only bridge only for primitive/String transport, deterministic IDE setup, and observable state queries.
• Open fixtures directly and wait for project readiness, analysis completion, applied settings, and stable screenshots with bounded Driver polling.
• Do not use fixed sleeps or timing-only delays.
• Continue capturing the remaining scenarios after a baseline mismatch and report the collected failures at the end.
• Keep exact committed-baseline equality as the pass/fail oracle, without thresholds or numerical pixel-delta reporting.
• Verify that each new visual assertion fails when the corresponding production rendering behavior is removed or disabled.

Pull-request reporting

• Publish the current captures in collapsed, feature-grouped galleries.
• Show current captures only for successful scenarios.
• On failure, show the baseline and current capture together for the affected scenario; a numerical delta table is not required.
• Remove changed-pixel, maximum-channel-delta, mean-delta, and Metrics JSON output from the normal pull-request report.
• Retain bounded diagnostics and commit-pinned image URLs.
• Keep pull-request code read-only and preserve the trusted workflow_run reporting boundary.
• Revalidate the pull request, label, current head SHA, and official Stack position before publishing.
• Never check out or execute pull-request code in the write-privileged reporter.

Documentation

Add docs/reference_visual_testing.md as the maintained visual-test contract. It should document:

• which user-visible changes belong in Driver screenshot coverage;
• the rule against Cartesian products and visually duplicate scenarios;
• scenario naming and grouping;
• the pinned IDE, Java, theme, font, scale, frame, fixture, caret, and operating-system baseline keys;
• the one-IDE-session harness model and per-scenario reset requirements;
• the production applySettings(...) boundary and permitted test-only bridge responsibilities;
• observable waits and screenshot stabilization requirements;
• baseline recording, review, overwrite, and CI immutability rules;
• the untrusted producer/trusted reporter security boundary;
• label, manual dispatch, concurrency, and top-of-Stack behavior;
• artifact validation, image publication, diagnostics, and sticky-comment behavior;
• how to add, replace, or remove a visual scenario without weakening an existing contract.

Update .agents/skills/driver-ui-tests/SKILL.md with the short operational workflow and link it to the reference document. Keep detailed architecture and policy in the reference rather than duplicating it in the skill.

Out of scope

• Implementing [Enhancement] Detect and manage overlapping IntelliJ editor guides #30.
• Exhaustive combinations of every persisted preference.
• Screenshots that are visually equivalent to an existing scenario.
• Settings-page, notification-balloon, Classic UI, Remote Development, split-editor, or third-party-plugin coverage.
• Additional IDE products or language-specific product lanes.
• Automatic baseline recording or acceptance in CI.
• Previous-run or threshold-based visual comparison.

Acceptance criteria

• ./gradlew visualTest exercises all minimum scenarios in one IDE session.
• Horizontal guide, vertical guide, pair border, and pair background rendering are each covered independently and together.
• Bracket colorization can be disabled without removing the active guide.
• The plugin-disabled transition removes existing plugin visuals rather than only testing a fresh disabled startup.
• With the relevant IntelliJ visuals initially enabled, [Enhancement] Detect and manage overlapping IntelliJ editor guides #30's unmanaged, default suppression, indent-hidden, and restoration outcomes are covered.
• Re-enabling the plugin reproduces the previously captured enabled state.
• Default and custom palettes produce reviewed, visibly distinct captures.
• Baseline mismatches fail the task but do not prevent later scenario captures from being produced.
• The pull-request comment presents grouped images without numerical pixel-delta metrics.
• CI never creates, overwrites, or accepts a baseline.
• The visual-test reference and operational skill describe the current harness and workflow behavior accurately.
• Ordinary tests continue to cover non-visual [Enhancement] Detect and manage overlapping IntelliJ editor guides #30 ownership, restoration, external-override, and notification state transitions.

Implementation

• Tracking issue: [Tracking] Add deterministic Driver visual regression testing #33
• Depends on: [Enhancement] Detect and manage overlapping IntelliJ editor guides #30
• Pull request: TBD
• Official GitHub Stack: TBD

---

This issue was written by Codex.