Capture, crop, and replace the marketplace PNG screenshots referenced in
README.md. Uses the e2e testing framework for UI navigation and screenshots,
and PowerShell for cropping.
-
Authenticated named profiles. The kusto-auth and sql-auth profiles
must be prepared and authenticated. Verify with:
vscode-ext-test profile open kusto-auth
vscode-ext-test profile open sql-auth
-
Window resize steps available. The e2e framework must support:
When I resize the Dev Host to <W> by <H>When I resize the window to <W> by <H> (alias)When I move the Dev Host to <X>, <Y>When I move the Dev Host to <X> <Y> (no-comma variant)
-
Windows PowerShell (powershell.exe) available for cropping via
System.Drawing. Do NOT use pwsh (PowerShell Core) — it does not
include System.Drawing by default.
-
Windows display scaling set to 100%. Higher DPI scaling (125%, 150%)
causes the screenshot pixel dimensions to differ from the window
dimensions, making crop coordinates unpredictable. Set display scaling
to 100% before starting a capture run.
-
Know the monitor layout. Before writing feature files, detect the
available monitors so you can position the Dev Host window on the right
screen with the right dimensions. Run:
Add-Type -AssemblyName System.Windows.Forms
[System.Windows.Forms.Screen]::AllScreens | ForEach-Object {
$b = $_.Bounds
[PSCustomObject]@{
Device = $_.DeviceName
Primary = $_.Primary
Width = $b.Width
Height = $b.Height
X = $b.X
Y = $b.Y
Orientation = if ($b.Width -ge $b.Height) { 'Landscape' } else { 'Portrait' }
}
} | Format-Table -AutoSize
Use this to decide:
- Which monitor to place the window on (
I move the Dev Host to X, Y)
- Max window size — don't exceed the monitor's resolution
- Portrait monitors are ideal for tall screenshots (markdown, full
query+results+chart combos) since they support heights up to 2560px
- Landscape monitors are better for wide screenshots (settings,
connection manager)
- The primary monitor at (0, 0) is the safest default
-
Consistent VS Code theme. All screenshots must use the same theme.
Ensure the profiles are configured with the target theme (Dark Modern
or whichever theme the existing screenshots use). Set the theme
explicitly if needed:
When I execute command "workbench.action.selectTheme"
-
Before overwriting, back up the original screenshot — but only if
the backup does not already exist:
if (-not (Test-Path "media\marketplace\<filename>.old.png")) {
Rename-Item "media\marketplace\<filename>.png" "<filename>.old.png"
}
The .old.png file preserves the original file that was on disk
when the replacement session started. It must only be created once.
If .old.png already exists, skip the rename — otherwise you would
replace the original with one of your own intermediate attempts.
On subsequent crop adjustments, only <filename>.png changes;
.old.png always points back to the pre-session original so you can
compare against it or revert cleanly.
The take-screenshot.ps1 script follows this rule: it only renames
the current .png to .old.png when no .old.png exists yet.
-
Write the cropped image to media/marketplace/<filename>.png (the crop
step in Phase 3 can write directly to this path, or copy here now).
-
For screenshots that need no cropping (full window captures), copy
the raw screenshot directly:
Copy-Item "path\to\raw.png" "media\marketplace\<filename>.png" -Force
-
View the new image with view_image to verify it looks correct.
-
Crop coordinates are resolution-dependent. The raw screenshot captures
the entire desktop area. Crop coordinates depend on window position and
DPI scaling. Always use When I move the Dev Host to 0, 0 before
screenshots to anchor the window position to the top-left corner.
-
Wait times matter. UI elements like autocomplete dropdowns, query
results tables, and chart renders need explicit waits. Use
I wait N seconds generously — under-waiting produces incomplete
screenshots. Prefer I wait for "<selector>" in the webview over
blind waits when possible.
-
Theme consistency. All screenshots must use the same VS Code theme.
Before starting a capture run, verify the theme is correct in the
profile. Do not mix light and dark themes across screenshots.
-
Tooltip screenshots are timing-sensitive. Screenshots showing
tooltips (e.g., prettify, share, add-to-favorites) require
hovering an element and capturing before the tooltip fades. Use the
Windows UI Automation click step to hover, then immediately take the
screenshot. May need multiple attempts.
-
Hard-tier screenshots need special handling:
vscode-custom-agent: Needs a live Copilot model conversation.
Open the profile manually, type an @mention, then use
--attach-devhost mode to screenshot.multi-account: Needs the Cached Values viewer with multiple
authenticated accounts. Pre-populate in the profile.python-sections: Needs Python installed with pandas/numpy.
Run the code manually first, then screenshot.html-dashboard: Needs a pre-built HTML section in a .kqlx
file. Create the file, open it, then screenshot.
-
Batch by profile. Run all default screenshots together, then
kusto-auth, then sql-auth. This avoids repeated profile switching
overhead and keeps auth tokens fresh within a batch.
-
DPI / display scaling. Windows display scaling (125%, 150%, 200%)
causes pixel dimensions to differ from logical dimensions. At 150%
DPI, a 1280x800 window produces a ~1920x1200 screenshot. Set display
scaling to 100% before capturing, or adjust crop coordinates to match
the actual pixel dimensions reported by view_image.
-
Feature files are disposable. Create unique test-ids per screenshot
batch (e.g., readme-ss-20260420). Don't reuse old test-ids. The
runs/ directory is gitignored but accumulates stale data.
-
Window resize step syntax:
When I resize the Dev Host to 1280 by 800 — resize windowWhen I resize the window to 1280 by 800 — alias, works the sameWhen I move the Dev Host to 0, 0 — move window (supports negative coords)When I move the Dev Host to 0 0 — no-comma variant also works
-
Verify the screenshot before cropping. Always view_image the raw
screenshot first. If the UI state is wrong (wrong panel open, results
not loaded, wrong theme), fix the feature file and re-run. Do not
waste time cropping a bad screenshot.
-
PowerShell version matters. Use powershell.exe (Windows
PowerShell 5.1) for the System.Drawing crop commands. PowerShell
Core (pwsh) does not include System.Drawing by default and will
throw unless System.Drawing.Common is installed.
-
README image path variants. Some README references use
./media/marketplace/ while others use media/marketplace/. Both
resolve to the same file. The filename field in the manifest is
just the basename (e.g., kusto-query-editor.png). The replacement
phase always targets media/marketplace/<filename>.
-
Use default profile to avoid leaking secrets. Screenshots that
show connection dropdowns, cluster names, or database names MUST use
the default profile (no auth, no saved connections). Real cluster
URLs and database names are secrets — never include them in
marketplace screenshots. Only use kusto-auth or sql-auth when the
screenshot genuinely requires authenticated data (e.g., query results).
-
Opening dropdowns: use __testOpenDropdown. The webview exposes
window.__testOpenDropdown(testId) which finds a kw-dropdown by
data-testid, calls _openMenu(), and neutralizes all dismiss
handlers so the menu stays open for screenshots. Without this, the
dropdown closes before the screenshot is taken. Example:
When I evaluate "__testOpenDropdown('cluster-dropdown')" in the webview
-
Highlighting a specific dropdown item. After opening a dropdown
with __testOpenDropdown, set _focusedIndex to highlight a specific
entry (0-indexed). Call requestUpdate() to re-render:
When I evaluate "const dd = __testFind('cluster-dropdown'); dd._focusedIndex = 1; dd.requestUpdate(); 'done'" in the webview
-
Clear placeholder text and save before screenshots. A fresh editor
shows ghost placeholder text ("Enter your KQL query here...") and has
a green unsaved-changes border. To get a clean grey border with no
placeholder, type a space then save:
And I type " "
And I press "Ctrl+S"
And I wait 2 seconds
-
Always focus the active editor group. After kusto.openQueryEditor,
run workbench.action.focusActiveEditorGroup before any I evaluate
steps. Without this, the evaluate may run in the wrong webview
(e.g., Copilot Chat panel instead of the custom editor):
And I execute command "workbench.action.focusActiveEditorGroup"
And I wait 2 seconds
-
Crop must include section borders. When cropping to a section area,
ensure the crop region starts a few pixels above and to the left of
the section content to include both the top border line and the left
border (with the : drag handle). Missing borders look unfinished.
-
Available data-testid values for dropdowns:
cluster-dropdown — the Kusto cluster picker in query sections- More will be added as needed; check
kw-query-section.ts and
kw-sql-section.ts for current values.
