refactor: internalize nextFrame() into fixture/helper methods (#11166)

## Summary Internalize `nextFrame()` calls into fixture/helper methods so spec authors don't need to remember to call it after common operations. `nextFrame()` waits for one `requestAnimationFrame` (~16ms) — an extra call is always safe, making this a low-risk refactor. ## Changes ### Phase 1: `SettingsHelper.setSetting()` `setSetting()` now calls `nextFrame()` internally. Removed 15 redundant calls across 7 files. ### Phase 2: `CommandHelper.executeCommand()` `executeCommand()` now calls `nextFrame()` internally. Removed 15 redundant calls across 7 files, including the now-redundant call in `AppModeHelper.toggleAppMode()`. ### Phase 3: `WorkflowHelper.loadGraphData()` New helper wraps `page.evaluate(loadGraphData)` + `nextFrame()`. Migrated `SubgraphHelper.serializeAndReload()` and `groupNode.spec.ts`. ### Phase 4: `NodeReference` cleanup Removed redundant `nextFrame()` from `copy()`, `convertToGroupNode()`, `resizeNode()`, `dragTextEncodeNode2()`, and `convertDefaultKSamplerToSubgraph()`. Removed 6 spec-level calls after `node.click('title')`. ### Phase 5: `KeyboardHelper.press()` and `delete()` New convenience methods that press a key and wait one frame. Converted 40 `canvas.press(key)` + `nextFrame()` pairs across 13 spec files. ### Phase 6: `ComfyPage.expectScreenshot()` New helper combines `nextFrame()` + `toHaveScreenshot()`. Converted 45 pairs across 12 spec files. ## Total impact - **~130 redundant `nextFrame()` calls eliminated** across ~35 spec/helper files - **3 new helper methods** added (`loadGraphData`, `press`/`delete`, `expectScreenshot`) - **2 existing methods** enhanced (`setSetting`, `executeCommand`) ## What was NOT changed - `performance.spec.ts` frame-counting loops (intentional) - `ComfyMouse.ts` / `CanvasHelper.ts` (already internalized) - `SubgraphHelper.packAllInteriorNodes()` (deliberate orchestration) - Builder helpers (already internalized) ┆Issue is synchronized with this [Notion page](https://www.notion.so/PR-11166-refactor-internalize-nextFrame-into-fixture-helper-methods-33f6d73d3650817bb5f6fb46e396085e) by [Unito](https://www.unito.io) --------- Co-authored-by: Amp <amp@ampcode.com>
2026-05-11 00:10:40 +00:00 · 2026-04-15 08:25:47 -07:00
parent 92ad6fc798
commit 52ccd9ed1a
47 changed files with 249 additions and 285 deletions
--- a/browser_tests/tests/builderReorder.spec.ts
+++ b/browser_tests/tests/builderReorder.spec.ts
@@ -157,7 +157,10 @@ test.describe('Builder input reordering', { tag: '@ui' }, () => {

  test('Reordering inputs in one app does not corrupt another app', async ({
    comfyPage
-  }) => {
+  }, testInfo) => {
+    // This test creates 2 apps, switches tabs 3 times, and enters builder 3
+    // times — the default 15s timeout is insufficient in CI.
+    testInfo.setTimeout(45_000)
    const { appMode } = comfyPage
    const app2Widgets = ['seed', 'steps']
    const app1Reordered = ['steps', 'cfg', 'seed']
--- a/browser_tests/tests/builderSaveFlow.spec.ts
+++ b/browser_tests/tests/builderSaveFlow.spec.ts
@@ -110,8 +110,7 @@ test.describe('Builder save flow', { tag: ['@ui'] }, () => {

    await expect(comfyPage.appMode.steps.toolbar).toBeVisible()

-    await comfyPage.page.keyboard.press('Escape')
-    await comfyPage.nextFrame()
+    await comfyPage.keyboard.press('Escape')

    await expect(comfyPage.appMode.steps.toolbar).toBeHidden()
  })
--- a/browser_tests/tests/canvasModeSelector.spec.ts
+++ b/browser_tests/tests/canvasModeSelector.spec.ts
@@ -29,7 +29,6 @@ test.describe('CanvasModeSelector', { tag: '@canvas' }, () => {
  test.beforeEach(async ({ comfyPage }) => {
    await comfyPage.settings.setSetting('Comfy.Graph.CanvasMenu', true)
    await comfyPage.command.executeCommand('Comfy.Canvas.Unlock')
-    await comfyPage.nextFrame()
  })

  test.describe('Trigger button', () => {
@@ -46,7 +45,6 @@ test.describe('CanvasModeSelector', { tag: '@canvas' }, () => {
        comfyPage
      }) => {
        await comfyPage.command.executeCommand(mode.activateCommand)
-        await comfyPage.nextFrame()
        const { trigger } = getLocators(comfyPage.page)
        const modeIcon = trigger.locator('i[aria-hidden="true"]').first()
        await expect(modeIcon).toHaveClass(mode.iconPattern)
@@ -103,7 +101,6 @@ test.describe('CanvasModeSelector', { tag: '@canvas' }, () => {
      }) => {
        if (!mode.isReadOnly) {
          await comfyPage.command.executeCommand('Comfy.Canvas.Lock')
-          await comfyPage.nextFrame()
        }
        const { trigger, menu, selectItem, handItem } = getLocators(
          comfyPage.page
@@ -156,7 +153,6 @@ test.describe('CanvasModeSelector', { tag: '@canvas' }, () => {
        comfyPage
      }) => {
        await comfyPage.command.executeCommand(mode.activateCommand)
-        await comfyPage.nextFrame()
        const { trigger, menu, selectItem, handItem } = getLocators(
          comfyPage.page
        )
@@ -208,7 +204,6 @@ test.describe('CanvasModeSelector', { tag: '@canvas' }, () => {
        comfyPage
      }) => {
        await comfyPage.command.executeCommand(mode.activateCommand)
-        await comfyPage.nextFrame()
        const { trigger, menu, selectItem, handItem } = getLocators(
          comfyPage.page
        )
@@ -229,8 +224,7 @@ test.describe('CanvasModeSelector', { tag: '@canvas' }, () => {
        await comfyPage.canvasOps.isReadOnly(),
        'Precondition: canvas starts unlocked'
      ).toBe(false)
-      await comfyPage.canvas.press('KeyH')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('KeyH')
      expect(await comfyPage.canvasOps.isReadOnly()).toBe(true)
      const { trigger } = getLocators(comfyPage.page)
      const modeIcon = trigger.locator('i[aria-hidden="true"]').first()
@@ -241,13 +235,11 @@ test.describe('CanvasModeSelector', { tag: '@canvas' }, () => {
      comfyPage
    }) => {
      await comfyPage.command.executeCommand('Comfy.Canvas.Lock')
-      await comfyPage.nextFrame()
      expect(
        await comfyPage.canvasOps.isReadOnly(),
        'Precondition: canvas starts locked'
      ).toBe(true)
-      await comfyPage.canvas.press('KeyV')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('KeyV')
      expect(await comfyPage.canvasOps.isReadOnly()).toBe(false)
      const { trigger } = getLocators(comfyPage.page)
      const modeIcon = trigger.locator('i[aria-hidden="true"]').first()
--- a/browser_tests/tests/changeTracker.spec.ts
+++ b/browser_tests/tests/changeTracker.spec.ts
@@ -223,8 +223,7 @@ test.describe('Change Tracker', { tag: '@workflow' }, () => {
      await beforeChange(comfyPage)
      await comfyPage.keyboard.bypass()
      await expect(node).toBeBypassed()
-      await comfyPage.page.keyboard.press('KeyP')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('KeyP')
      await expect(node).toBePinned()
      await afterChange(comfyPage)
    }
--- a/browser_tests/tests/cloud-asset-default.spec.ts
+++ b/browser_tests/tests/cloud-asset-default.spec.ts
@@ -74,18 +74,23 @@ test.describe('Asset-supported node default value', { tag: '@cloud' }, () => {
      return node!.id
    })

+    // Wait for the asset widget to mount AND its value to resolve.
+    // The widget type becomes 'asset' before the value is populated,
+    // so poll for both conditions together to avoid a race where the
+    // type check passes but the value is still the placeholder.
    await expect
      .poll(
-        async () => {
-          return await comfyPage.page.evaluate((id) => {
+        () =>
+          comfyPage.page.evaluate((id) => {
            const node = window.app!.graph.getNodeById(id)
            const widget = node?.widgets?.find(
              (w: { name: string }) => w.name === 'ckpt_name'
            )
-            return String(widget?.value ?? '')
-          }, nodeId)
-        },
-        { timeout: 10_000 }
+            if (widget?.type !== 'asset') return 'waiting:type'
+            const val = String(widget?.value ?? '')
+            return val === 'Select model' ? 'waiting:value' : val
+          }, nodeId),
+        { timeout: 15_000 }
      )
      .toBe(CLOUD_ASSETS[0].name)
  })
--- a/browser_tests/tests/colorPalette.spec.ts
+++ b/browser_tests/tests/colorPalette.spec.ts
@@ -157,18 +157,15 @@ test.describe('Color Palette', { tag: ['@screenshot', '@settings'] }, () => {

    await comfyPage.workflow.loadWorkflow('nodes/every_node_color')
    await comfyPage.settings.setSetting('Comfy.ColorPalette', 'obsidian_dark')
-    await comfyPage.nextFrame()
    await expect(comfyPage.canvas).toHaveScreenshot(
      'custom-color-palette-obsidian-dark-all-colors.png'
    )
    await comfyPage.settings.setSetting('Comfy.ColorPalette', 'light_red')
-    await comfyPage.nextFrame()
    await expect(comfyPage.canvas).toHaveScreenshot(
      'custom-color-palette-light-red.png'
    )

    await comfyPage.settings.setSetting('Comfy.ColorPalette', 'dark')
-    await comfyPage.nextFrame()
    await expect(comfyPage.canvas).toHaveScreenshot('default-color-palette.png')
  })

@@ -181,7 +178,6 @@ test.describe('Color Palette', { tag: ['@screenshot', '@settings'] }, () => {
    await expect(comfyPage.toast.toastErrors).toHaveCount(0)

    await comfyPage.settings.setSetting('Comfy.ColorPalette', 'obsidian_dark')
-    await comfyPage.nextFrame()
    await expect(comfyPage.canvas).toHaveScreenshot(
      'custom-color-palette-obsidian-dark.png'
    )
@@ -190,7 +186,6 @@ test.describe('Color Palette', { tag: ['@screenshot', '@settings'] }, () => {
      'Comfy.ColorPalette',
      'custom_obsidian_dark'
    )
-    await comfyPage.nextFrame()
    await expect(comfyPage.canvas).toHaveScreenshot(
      'custom-color-palette-obsidian-dark.png'
    )
@@ -212,15 +207,12 @@ test.describe(

      // Drag mouse to force canvas to redraw
      await comfyPage.page.mouse.move(0, 0)
-      await comfyPage.nextFrame()
-
-      await expect(comfyPage.canvas).toHaveScreenshot('node-opacity-0.5.png')
+      await comfyPage.expectScreenshot(comfyPage.canvas, 'node-opacity-0.5.png')

      await comfyPage.settings.setSetting('Comfy.Node.Opacity', 1.0)

      await comfyPage.page.mouse.move(8, 8)
-      await comfyPage.nextFrame()
-      await expect(comfyPage.canvas).toHaveScreenshot('node-opacity-1.png')
+      await comfyPage.expectScreenshot(comfyPage.canvas, 'node-opacity-1.png')
    })

    test('should persist color adjustments when changing themes', async ({
@@ -229,8 +221,8 @@ test.describe(
      await comfyPage.settings.setSetting('Comfy.Node.Opacity', 0.2)
      await comfyPage.settings.setSetting('Comfy.ColorPalette', 'arc')
      await comfyPage.page.mouse.move(0, 0)
-      await comfyPage.nextFrame()
-      await expect(comfyPage.canvas).toHaveScreenshot(
+      await comfyPage.expectScreenshot(
+        comfyPage.canvas,
        'node-opacity-0.2-arc-theme.png'
      )
    })
@@ -240,7 +232,6 @@ test.describe(
    }) => {
      await comfyPage.settings.setSetting('Comfy.Node.Opacity', 0.5)
      await comfyPage.settings.setSetting('Comfy.ColorPalette', 'light')
-      await comfyPage.nextFrame()
      await expect
        .poll(() =>
          comfyPage.page.evaluate(() => {
@@ -279,7 +270,6 @@ test.describe(
      comfyPage
    }) => {
      await comfyPage.settings.setSetting('Comfy.ColorPalette', 'light')
-      await comfyPage.nextFrame()
      await expect(comfyPage.canvas).toHaveScreenshot(
        'node-lightened-colors.png'
      )
--- a/browser_tests/tests/copyPaste.spec.ts
+++ b/browser_tests/tests/copyPaste.spec.ts
@@ -155,7 +155,6 @@ test.describe('Copy Paste', { tag: ['@screenshot', '@workflow'] }, () => {
      const loadImageNodes =
        await comfyPage.nodeOps.getNodeRefsByType('LoadImage')
      await loadImageNodes[0].click('title')
-      await comfyPage.nextFrame()

      const uploadPromise = comfyPage.page.waitForResponse(
        (resp) => resp.url().includes('/upload/') && resp.status() === 200,
--- a/browser_tests/tests/defaultKeybindings.spec.ts
+++ b/browser_tests/tests/defaultKeybindings.spec.ts
@@ -52,8 +52,7 @@ test.describe('Default Keybindings', { tag: '@keyboard' }, () => {
    test("'Alt+=' zooms in", async ({ comfyPage }) => {
      const initialScale = await comfyPage.canvasOps.getScale()

-      await comfyPage.canvas.press('Alt+Equal')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('Alt+Equal')

      await expect
        .poll(() => comfyPage.canvasOps.getScale())
@@ -63,8 +62,7 @@ test.describe('Default Keybindings', { tag: '@keyboard' }, () => {
    test("'Alt+-' zooms out", async ({ comfyPage }) => {
      const initialScale = await comfyPage.canvasOps.getScale()

-      await comfyPage.canvas.press('Alt+Minus')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('Alt+Minus')

      await expect
        .poll(() => comfyPage.canvasOps.getScale())
@@ -82,8 +80,7 @@ test.describe('Default Keybindings', { tag: '@keyboard' }, () => {
      await comfyPage.canvas.click({ position: { x: 400, y: 400 } })
      await comfyPage.nextFrame()

-      await comfyPage.canvas.press('Period')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('Period')

      await expect
        .poll(() => comfyPage.canvasOps.getScale())
@@ -93,8 +90,7 @@ test.describe('Default Keybindings', { tag: '@keyboard' }, () => {
    test("'h' locks canvas", async ({ comfyPage }) => {
      await expect.poll(() => comfyPage.canvasOps.isReadOnly()).toBe(false)

-      await comfyPage.canvas.press('KeyH')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('KeyH')

      await expect.poll(() => comfyPage.canvasOps.isReadOnly()).toBe(true)
    })
@@ -102,11 +98,9 @@ test.describe('Default Keybindings', { tag: '@keyboard' }, () => {
    test("'v' unlocks canvas", async ({ comfyPage }) => {
      // Lock first
      await comfyPage.command.executeCommand('Comfy.Canvas.Lock')
-      await comfyPage.nextFrame()
      await expect.poll(() => comfyPage.canvasOps.isReadOnly()).toBe(true)

-      await comfyPage.canvas.press('KeyV')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('KeyV')

      await expect.poll(() => comfyPage.canvasOps.isReadOnly()).toBe(false)
    })
@@ -121,16 +115,13 @@ test.describe('Default Keybindings', { tag: '@keyboard' }, () => {
      const node = nodes[0]

      await node.click('title')
-      await comfyPage.nextFrame()

      await expect.poll(() => node.isCollapsed()).toBe(false)

-      await comfyPage.canvas.press('Alt+KeyC')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('Alt+KeyC')
      await expect.poll(() => node.isCollapsed()).toBe(true)

-      await comfyPage.canvas.press('Alt+KeyC')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('Alt+KeyC')
      await expect.poll(() => node.isCollapsed()).toBe(false)
    })

@@ -140,7 +131,6 @@ test.describe('Default Keybindings', { tag: '@keyboard' }, () => {
      const node = nodes[0]

      await node.click('title')
-      await comfyPage.nextFrame()

      // Normal mode is ALWAYS (0)
      const getMode = () =>
@@ -150,13 +140,11 @@ test.describe('Default Keybindings', { tag: '@keyboard' }, () => {

      await expect.poll(() => getMode()).toBe(0)

-      await comfyPage.canvas.press('Control+KeyM')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('Control+KeyM')
      // NEVER (2) = muted
      await expect.poll(() => getMode()).toBe(2)

-      await comfyPage.canvas.press('Control+KeyM')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('Control+KeyM')
      await expect.poll(() => getMode()).toBe(0)
    })
  })
@@ -239,16 +227,14 @@ test.describe('Default Keybindings', { tag: '@keyboard' }, () => {
    test("'Ctrl+s' triggers save workflow", async ({ comfyPage }) => {
      // On a new unsaved workflow, Ctrl+s triggers Save As dialog.
      // The dialog appearing proves the keybinding was intercepted by the app.
-      await comfyPage.page.keyboard.press('Control+s')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('Control+s')

      // The Save As dialog should appear (p-dialog overlay)
      const dialogOverlay = comfyPage.page.locator('.p-dialog-mask')
      await expect(dialogOverlay).toBeVisible()

      // Dismiss the dialog
-      await comfyPage.page.keyboard.press('Escape')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('Escape')
    })

    test("'Ctrl+o' triggers open workflow", async ({ comfyPage }) => {
@@ -265,8 +251,7 @@ test.describe('Default Keybindings', { tag: '@keyboard' }, () => {
        }
      })

-      await comfyPage.page.keyboard.press('Control+o')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('Control+o')

      await expect
        .poll(() => comfyPage.page.evaluate(() => window.TestCommand))
@@ -288,11 +273,9 @@ test.describe('Default Keybindings', { tag: '@keyboard' }, () => {
      const initialCount = await comfyPage.nodeOps.getGraphNodesCount()

      // Select all nodes
-      await comfyPage.canvas.press('Control+a')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('Control+a')

-      await comfyPage.page.keyboard.press('Control+Shift+KeyE')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('Control+Shift+KeyE')

      // After conversion, node count should decrease
      // (multiple nodes replaced by single subgraph node)
--- a/browser_tests/tests/dialogs/settingsDialog.spec.ts
+++ b/browser_tests/tests/dialogs/settingsDialog.spec.ts
@@ -145,15 +145,27 @@ test.describe('Settings dialog', { tag: '@ui' }, () => {
      const settingRow = dialog.root.locator(`[data-setting-id="${settingId}"]`)
      await expect(settingRow).toBeVisible()

-      // Open the dropdown via its combobox role and verify it expanded.
-      // Retry because the PrimeVue Select may re-render during search
-      // filtering, causing the first click to land on a stale element.
+      // Wait for the search filter to fully settle — PrimeVue re-renders
+      // the entire settings list after typing, and the combobox element is
+      // replaced during re-render. Wait until the filtered list stabilises
+      // before interacting with the combobox.
+      const settingItems = dialog.root.locator('[data-setting-id]')
+      await expect
+        .poll(() => settingItems.count(), { timeout: 5000 })
+        .toBeLessThanOrEqual(5)
+
      const select = settingRow.getByRole('combobox')
+      await expect(select).toBeVisible()
+      await expect(select).toBeEnabled()
+
+      // Open the dropdown via its combobox role and verify it expanded.
+      // Retry because the PrimeVue Select may still re-render after the
+      // filter settles, causing the first click to land on a stale element.
      await expect(async () => {
        const expanded = await select.getAttribute('aria-expanded')
        if (expanded !== 'true') await select.click()
        await expect(select).toHaveAttribute('aria-expanded', 'true')
-      }).toPass({ timeout: 5000 })
+      }).toPass({ timeout: 10_000 })

      // Pick the option that is not the current value
      const targetValue = initialValue === 'Top' ? 'Disabled' : 'Top'
--- a/browser_tests/tests/graphCanvasMenu.spec.ts
+++ b/browser_tests/tests/graphCanvasMenu.spec.ts
@@ -24,8 +24,8 @@ test.describe('Graph Canvas Menu', { tag: ['@screenshot', '@canvas'] }, () => {
        TestIds.canvas.toggleLinkVisibilityButton
      )
      await button.click()
-      await comfyPage.nextFrame()
-      await expect(comfyPage.canvas).toHaveScreenshot(
+      await comfyPage.expectScreenshot(
+        comfyPage.canvas,
        'canvas-with-hidden-links.png'
      )
      const hiddenLinkRenderMode = await comfyPage.page.evaluate(() => {
@@ -36,8 +36,8 @@ test.describe('Graph Canvas Menu', { tag: ['@screenshot', '@canvas'] }, () => {
        .toBe(hiddenLinkRenderMode)

      await button.click()
-      await comfyPage.nextFrame()
-      await expect(comfyPage.canvas).toHaveScreenshot(
+      await comfyPage.expectScreenshot(
+        comfyPage.canvas,
        'canvas-with-visible-links.png'
      )
      await expect
--- a/browser_tests/tests/groupNode.spec.ts
+++ b/browser_tests/tests/groupNode.spec.ts
@@ -336,12 +336,9 @@ test.describe('Group Node', { tag: '@node' }, () => {
      )

      await test.step('Load workflow containing a group node pasted from a different workflow', async () => {
-        await comfyPage.page.evaluate(
-          (workflow) =>
-            window.app!.loadGraphData(workflow as ComfyWorkflowJSON),
-          currentGraphState
+        await comfyPage.workflow.loadGraphData(
+          currentGraphState as ComfyWorkflowJSON
        )
-        await comfyPage.nextFrame()
        await verifyNodeLoaded(comfyPage, 1)
      })
    })
--- a/browser_tests/tests/interaction.spec.ts
+++ b/browser_tests/tests/interaction.spec.ts
@@ -31,11 +31,9 @@ test.describe('Item Interaction', { tag: ['@screenshot', '@node'] }, () => {
  test('Can pin/unpin items with keyboard shortcut', async ({ comfyPage }) => {
    await comfyPage.workflow.loadWorkflow('groups/mixed_graph_items')
    await comfyPage.canvas.press('Control+a')
-    await comfyPage.canvas.press('KeyP')
-    await comfyPage.nextFrame()
+    await comfyPage.keyboard.press('KeyP')
    await expect(comfyPage.canvas).toHaveScreenshot('pinned-all.png')
-    await comfyPage.canvas.press('KeyP')
-    await comfyPage.nextFrame()
+    await comfyPage.keyboard.press('KeyP')
    await expect(comfyPage.canvas).toHaveScreenshot('unpinned-all.png')
  })
 })
@@ -76,13 +74,11 @@ test.describe('Node Interaction', () => {
        await comfyPage.canvas.click({
          position: DefaultGraphPositions.textEncodeNode1
        })
-        await comfyPage.nextFrame()
-        await expect(comfyPage.canvas).toHaveScreenshot('selected-node1.png')
+        await comfyPage.expectScreenshot(comfyPage.canvas, 'selected-node1.png')
        await comfyPage.canvas.click({
          position: DefaultGraphPositions.textEncodeNode2
        })
-        await comfyPage.nextFrame()
-        await expect(comfyPage.canvas).toHaveScreenshot('selected-node2.png')
+        await comfyPage.expectScreenshot(comfyPage.canvas, 'selected-node2.png')
      }
    )

@@ -174,8 +170,7 @@ test.describe('Node Interaction', () => {
    await comfyPage.nodeOps.dragTextEncodeNode2()
    // Move mouse away to avoid hover highlight on the node at the drop position.
    await comfyPage.canvasOps.moveMouseToEmptyArea()
-    await comfyPage.nextFrame()
-    await expect(comfyPage.canvas).toHaveScreenshot('dragged-node1.png', {
+    await comfyPage.expectScreenshot(comfyPage.canvas, 'dragged-node1.png', {
      maxDiffPixels: 50
    })
  })
@@ -185,7 +180,6 @@ test.describe('Node Interaction', () => {
      // Pin this suite to the legacy canvas path so Alt+drag exercises
      // LGraphCanvas, not the Vue node drag handler.
      await comfyPage.settings.setSetting('Comfy.VueNodes.Enabled', false)
-      await comfyPage.nextFrame()
    })

    test('Can duplicate a regular node via Alt+drag', async ({ comfyPage }) => {
@@ -285,7 +279,6 @@ test.describe('Node Interaction', () => {
    }) => {
      await comfyPage.settings.setSetting('Comfy.Node.AutoSnapLinkToSlot', true)
      await comfyPage.settings.setSetting('Comfy.Node.SnapHighlightsNode', true)
-      await comfyPage.nextFrame()

      await comfyMouse.move(DefaultGraphPositions.clipTextEncodeNode1InputSlot)
      await comfyMouse.drag(DefaultGraphPositions.clipTextEncodeNode2InputSlot)
@@ -359,8 +352,8 @@ test.describe('Node Interaction', () => {
        modifiers: ['Control', 'Alt'],
        position: loadCheckpointClipSlotPos
      })
-      await comfyPage.nextFrame()
-      await expect(comfyPage.canvas).toHaveScreenshot(
+      await comfyPage.expectScreenshot(
+        comfyPage.canvas,
        'batch-disconnect-links-disconnected.png'
      )
    }
@@ -410,8 +403,8 @@ test.describe('Node Interaction', () => {
      await expect.poll(() => targetNode.isCollapsed()).toBe(false)
      // Move mouse away to avoid hover highlight differences.
      await comfyPage.canvasOps.moveMouseToEmptyArea()
-      await comfyPage.nextFrame()
-      await expect(comfyPage.canvas).toHaveScreenshot(
+      await comfyPage.expectScreenshot(
+        comfyPage.canvas,
        'text-encode-toggled-back-open.png'
      )
    }
@@ -514,8 +507,7 @@ test.describe('Node Interaction', () => {
      await comfyPage.page.keyboard.up('Control')
      await comfyPage.nextFrame()
      // Confirm group title
-      await comfyPage.page.keyboard.press('Enter')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('Enter')
      await expect(comfyPage.canvas).toHaveScreenshot(
        'group-selected-nodes.png'
      )
@@ -1171,8 +1163,8 @@ test.describe('Canvas Navigation', { tag: '@screenshot' }, () => {
      await comfyPage.page.mouse.down({ button: 'middle' })
      await comfyPage.page.mouse.move(150, 150)
      await comfyPage.page.mouse.up({ button: 'middle' })
-      await comfyPage.nextFrame()
-      await expect(comfyPage.canvas).toHaveScreenshot(
+      await comfyPage.expectScreenshot(
+        comfyPage.canvas,
        'legacy-middle-drag-pan.png'
      )
    })
@@ -1180,14 +1172,14 @@ test.describe('Canvas Navigation', { tag: '@screenshot' }, () => {
    test('Mouse wheel should zoom in/out', async ({ comfyPage }) => {
      await comfyPage.page.mouse.move(400, 300)
      await comfyPage.page.mouse.wheel(0, -120)
-      await comfyPage.nextFrame()
-      await expect(comfyPage.canvas).toHaveScreenshot(
+      await comfyPage.expectScreenshot(
+        comfyPage.canvas,
        'legacy-wheel-zoom-in.png'
      )

      await comfyPage.page.mouse.wheel(0, 240)
-      await comfyPage.nextFrame()
-      await expect(comfyPage.canvas).toHaveScreenshot(
+      await comfyPage.expectScreenshot(
+        comfyPage.canvas,
        'legacy-wheel-zoom-out.png'
      )
    })
@@ -1247,8 +1239,8 @@ test.describe('Canvas Navigation', { tag: '@screenshot' }, () => {
      await comfyPage.page.mouse.down({ button: 'middle' })
      await comfyPage.page.mouse.move(150, 150)
      await comfyPage.page.mouse.up({ button: 'middle' })
-      await comfyPage.nextFrame()
-      await expect(comfyPage.canvas).toHaveScreenshot(
+      await comfyPage.expectScreenshot(
+        comfyPage.canvas,
        'standard-middle-drag-pan.png'
      )
    })
@@ -1258,16 +1250,16 @@ test.describe('Canvas Navigation', { tag: '@screenshot' }, () => {
      await comfyPage.page.keyboard.down('Control')
      await comfyPage.page.mouse.wheel(0, -120)
      await comfyPage.page.keyboard.up('Control')
-      await comfyPage.nextFrame()
-      await expect(comfyPage.canvas).toHaveScreenshot(
+      await comfyPage.expectScreenshot(
+        comfyPage.canvas,
        'standard-ctrl-wheel-zoom-in.png'
      )

      await comfyPage.page.keyboard.down('Control')
      await comfyPage.page.mouse.wheel(0, 240)
      await comfyPage.page.keyboard.up('Control')
-      await comfyPage.nextFrame()
-      await expect(comfyPage.canvas).toHaveScreenshot(
+      await comfyPage.expectScreenshot(
+        comfyPage.canvas,
        'standard-ctrl-wheel-zoom-out.png'
      )
    })
@@ -1359,33 +1351,31 @@ test.describe('Canvas Navigation', { tag: '@screenshot' }, () => {
    )

    await comfyPage.canvas.click()
-    await comfyPage.nextFrame()
-
-    await expect(comfyPage.canvas).toHaveScreenshot('standard-initial.png')
+    await comfyPage.expectScreenshot(comfyPage.canvas, 'standard-initial.png')

    await comfyPage.page.mouse.move(400, 300)

    await comfyPage.page.keyboard.down('Shift')
    await comfyPage.page.mouse.wheel(0, 120)
    await comfyPage.page.keyboard.up('Shift')
-    await comfyPage.nextFrame()
-    await expect(comfyPage.canvas).toHaveScreenshot(
+    await comfyPage.expectScreenshot(
+      comfyPage.canvas,
      'standard-shift-wheel-pan-right.png'
    )

    await comfyPage.page.keyboard.down('Shift')
    await comfyPage.page.mouse.wheel(0, -240)
    await comfyPage.page.keyboard.up('Shift')
-    await comfyPage.nextFrame()
-    await expect(comfyPage.canvas).toHaveScreenshot(
+    await comfyPage.expectScreenshot(
+      comfyPage.canvas,
      'standard-shift-wheel-pan-left.png'
    )

    await comfyPage.page.keyboard.down('Shift')
    await comfyPage.page.mouse.wheel(0, 120)
    await comfyPage.page.keyboard.up('Shift')
-    await comfyPage.nextFrame()
-    await expect(comfyPage.canvas).toHaveScreenshot(
+    await comfyPage.expectScreenshot(
+      comfyPage.canvas,
      'standard-shift-wheel-pan-center.png'
    )
  })
--- a/browser_tests/tests/load3d/load3d.spec.ts
+++ b/browser_tests/tests/load3d/load3d.spec.ts
@@ -112,9 +112,8 @@ test.describe('Load3D', () => {
      await expect.poll(() => modelFileWidget.getValue()).toContain('cube.obj')

      await load3d.waitForModelLoaded()
-      await comfyPage.nextFrame()
-
-      await expect(load3d.node).toHaveScreenshot(
+      await comfyPage.expectScreenshot(
+        load3d.node,
        'load3d-uploaded-cube-obj.png',
        { maxDiffPixelRatio: 0.1 }
      )
@@ -142,9 +141,8 @@ test.describe('Load3D', () => {
      await expect.poll(() => modelFileWidget.getValue()).toContain('cube.obj')

      await load3d.waitForModelLoaded()
-      await comfyPage.nextFrame()
-
-      await expect(load3d.node).toHaveScreenshot(
+      await comfyPage.expectScreenshot(
+        load3d.node,
        'load3d-dropped-cube-obj.png',
        { maxDiffPixelRatio: 0.1 }
      )
--- a/browser_tests/tests/minimap.spec.ts
+++ b/browser_tests/tests/minimap.spec.ts
@@ -143,8 +143,7 @@ test.describe('Minimap', { tag: '@canvas' }, () => {
        canvas.ds.offset[1] = -600
        canvas.setDirty(true, true)
      })
-      await comfyPage.nextFrame()
-      await expect(minimap).toHaveScreenshot('minimap-after-pan.png')
+      await comfyPage.expectScreenshot(minimap, 'minimap-after-pan.png')
    }
  )

--- a/browser_tests/tests/mobileBaseline.spec.ts
+++ b/browser_tests/tests/mobileBaseline.spec.ts
@@ -11,8 +11,10 @@ test.describe(
      await comfyPage.settings.setSetting('Comfy.ConfirmClear', false)
      await comfyPage.command.executeCommand('Comfy.ClearWorkflow')
      await expect.poll(() => comfyPage.nodeOps.getGraphNodesCount()).toBe(0)
-      await comfyPage.nextFrame()
-      await expect(comfyPage.canvas).toHaveScreenshot('mobile-empty-canvas.png')
+      await comfyPage.expectScreenshot(
+        comfyPage.canvas,
+        'mobile-empty-canvas.png'
+      )
    })

    test('@mobile default workflow', async ({ comfyPage }) => {
@@ -24,7 +26,6 @@ test.describe(

    test('@mobile graph canvas toolbar visible', async ({ comfyPage }) => {
      await comfyPage.settings.setSetting('Comfy.Graph.CanvasMenu', true)
-      await comfyPage.nextFrame()

      const minimapButton = comfyPage.page.getByTestId(
        TestIds.canvas.toggleMinimapButton
@@ -38,9 +39,8 @@ test.describe(

    test('@mobile settings dialog', async ({ comfyPage }) => {
      await comfyPage.settingDialog.open()
-      await comfyPage.nextFrame()
-
-      await expect(comfyPage.settingDialog.root).toHaveScreenshot(
+      await comfyPage.expectScreenshot(
+        comfyPage.settingDialog.root,
        'mobile-settings-dialog.png',
        {
          mask: [
--- a/browser_tests/tests/nodeContextMenuOverflow.spec.ts
+++ b/browser_tests/tests/nodeContextMenuOverflow.spec.ts
@@ -35,7 +35,6 @@ test.describe(
      await comfyPage.nextFrame()

      await ksamplerNodes[0].click('title')
-      await comfyPage.nextFrame()

      await expect(comfyPage.page.locator('.selection-toolbox')).toBeVisible()

--- a/browser_tests/tests/nodeGhostPlacement.spec.ts
+++ b/browser_tests/tests/nodeGhostPlacement.spec.ts
@@ -14,7 +14,6 @@ async function setVueMode(comfyPage: ComfyPage, enabled: boolean) {

 async function addGhostAtCenter(comfyPage: ComfyPage) {
  await comfyPage.command.executeCommand('Comfy.NewBlankWorkflow')
-  await comfyPage.nextFrame()

  const viewport = comfyPage.page.viewportSize()!
  const centerX = Math.round(viewport.width / 2)
@@ -53,7 +52,6 @@ for (const mode of ['litegraph', 'vue'] as const) {

    test('positions ghost node at cursor', async ({ comfyPage }) => {
      await comfyPage.command.executeCommand('Comfy.NewBlankWorkflow')
-      await comfyPage.nextFrame()

      const viewport = comfyPage.page.viewportSize()!
      const centerX = Math.round(viewport.width / 2)
@@ -110,8 +108,7 @@ for (const mode of ['litegraph', 'vue'] as const) {
      expect(before).not.toBeNull()
      expect(before!.ghost).toBe(true)

-      await comfyPage.page.keyboard.press('Escape')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('Escape')

      const after = await getNodeById(comfyPage, nodeId)
      expect(after).toBeNull()
@@ -124,8 +121,7 @@ for (const mode of ['litegraph', 'vue'] as const) {
      expect(before).not.toBeNull()
      expect(before!.ghost).toBe(true)

-      await comfyPage.page.keyboard.press('Delete')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('Delete')

      const after = await getNodeById(comfyPage, nodeId)
      expect(after).toBeNull()
@@ -138,8 +134,7 @@ for (const mode of ['litegraph', 'vue'] as const) {
      expect(before).not.toBeNull()
      expect(before!.ghost).toBe(true)

-      await comfyPage.page.keyboard.press('Backspace')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('Backspace')

      const after = await getNodeById(comfyPage, nodeId)
      expect(after).toBeNull()
--- a/browser_tests/tests/nodeSearchBox.spec.ts
+++ b/browser_tests/tests/nodeSearchBox.spec.ts
@@ -303,8 +303,8 @@ test.describe('Release context menu', { tag: '@node' }, () => {
        'CLIP | CLIP'
      )
      await comfyPage.page.mouse.move(10, 10)
-      await comfyPage.nextFrame()
-      await expect(comfyPage.canvas).toHaveScreenshot(
+      await comfyPage.expectScreenshot(
+        comfyPage.canvas,
        'link-release-context-menu.png'
      )
    }
--- a/browser_tests/tests/rightClickMenu.spec.ts
+++ b/browser_tests/tests/rightClickMenu.spec.ts
@@ -19,8 +19,10 @@ test.describe(
      await comfyPage.page.getByText('loaders').click()
      await comfyPage.page.getByText('Load VAE').click()
      await comfyPage.contextMenu.waitForHidden()
-      await comfyPage.nextFrame()
-      await expect(comfyPage.canvas).toHaveScreenshot('add-node-node-added.png')
+      await comfyPage.expectScreenshot(
+        comfyPage.canvas,
+        'add-node-node-added.png'
+      )
    })

    test('Can add group', async ({ comfyPage }) => {
@@ -28,8 +30,8 @@ test.describe(
      await expect(comfyPage.canvas).toHaveScreenshot('right-click-menu.png')
      await comfyPage.page.getByText('Add Group', { exact: true }).click()
      await comfyPage.contextMenu.waitForHidden()
-      await comfyPage.nextFrame()
-      await expect(comfyPage.canvas).toHaveScreenshot(
+      await comfyPage.expectScreenshot(
+        comfyPage.canvas,
        'add-group-group-added.png'
      )
    })
@@ -45,8 +47,8 @@ test.describe(
      await comfyPage.nodeOps.promptDialogInput.fill('GroupNode2CLIP')
      await comfyPage.page.keyboard.press('Enter')
      await comfyPage.nodeOps.promptDialogInput.waitFor({ state: 'hidden' })
-      await comfyPage.nextFrame()
-      await expect(comfyPage.canvas).toHaveScreenshot(
+      await comfyPage.expectScreenshot(
+        comfyPage.canvas,
        'right-click-node-group-node.png'
      )
    })
@@ -60,12 +62,11 @@ test.describe('Node Right Click Menu', { tag: ['@screenshot', '@ui'] }, () => {
      button: 'right'
    })
    await comfyPage.page.mouse.move(10, 10)
-    await comfyPage.nextFrame()
-    await expect(comfyPage.canvas).toHaveScreenshot('right-click-node.png')
+    await comfyPage.expectScreenshot(comfyPage.canvas, 'right-click-node.png')
    await comfyPage.page.getByText('Properties Panel').click()
    await comfyPage.contextMenu.waitForHidden()
-    await comfyPage.nextFrame()
-    await expect(comfyPage.canvas).toHaveScreenshot(
+    await comfyPage.expectScreenshot(
+      comfyPage.canvas,
      'right-click-node-properties-panel.png'
    )
  })
@@ -76,12 +77,11 @@ test.describe('Node Right Click Menu', { tag: ['@screenshot', '@ui'] }, () => {
      button: 'right'
    })
    await comfyPage.page.mouse.move(10, 10)
-    await comfyPage.nextFrame()
-    await expect(comfyPage.canvas).toHaveScreenshot('right-click-node.png')
+    await comfyPage.expectScreenshot(comfyPage.canvas, 'right-click-node.png')
    await comfyPage.page.getByText('Collapse').click()
    await comfyPage.contextMenu.waitForHidden()
-    await comfyPage.nextFrame()
-    await expect(comfyPage.canvas).toHaveScreenshot(
+    await comfyPage.expectScreenshot(
+      comfyPage.canvas,
      'right-click-node-collapsed.png'
    )
  })
@@ -104,8 +104,8 @@ test.describe('Node Right Click Menu', { tag: ['@screenshot', '@ui'] }, () => {
    await comfyPage.nextFrame()
    await comfyPage.page.getByText('Collapse').click()
    await comfyPage.contextMenu.waitForHidden()
-    await comfyPage.nextFrame()
-    await expect(comfyPage.canvas).toHaveScreenshot(
+    await comfyPage.expectScreenshot(
+      comfyPage.canvas,
      'right-click-node-collapsed-badge.png'
    )
  })
@@ -116,12 +116,11 @@ test.describe('Node Right Click Menu', { tag: ['@screenshot', '@ui'] }, () => {
      button: 'right'
    })
    await comfyPage.page.mouse.move(10, 10)
-    await comfyPage.nextFrame()
-    await expect(comfyPage.canvas).toHaveScreenshot('right-click-node.png')
+    await comfyPage.expectScreenshot(comfyPage.canvas, 'right-click-node.png')
    await comfyPage.page.getByText('Bypass').click()
    await comfyPage.contextMenu.waitForHidden()
-    await comfyPage.nextFrame()
-    await expect(comfyPage.canvas).toHaveScreenshot(
+    await comfyPage.expectScreenshot(
+      comfyPage.canvas,
      'right-click-node-bypassed.png'
    )
  })
@@ -133,8 +132,7 @@ test.describe('Node Right Click Menu', { tag: ['@screenshot', '@ui'] }, () => {
      button: 'right'
    })
    await comfyPage.page.mouse.move(10, 10)
-    await comfyPage.nextFrame()
-    await expect(comfyPage.canvas).toHaveScreenshot('right-click-node.png')
+    await comfyPage.expectScreenshot(comfyPage.canvas, 'right-click-node.png')
    await comfyPage.page.locator('.litemenu-entry:has-text("Pin")').click()
    await comfyPage.contextMenu.waitForHidden()
    await comfyPage.nextFrame()
@@ -149,8 +147,8 @@ test.describe('Node Right Click Menu', { tag: ['@screenshot', '@ui'] }, () => {
      button: 'right'
    })
    await comfyPage.page.mouse.move(10, 10)
-    await comfyPage.nextFrame()
-    await expect(comfyPage.canvas).toHaveScreenshot(
+    await comfyPage.expectScreenshot(
+      comfyPage.canvas,
      'right-click-pinned-node.png'
    )
    await comfyPage.page.locator('.litemenu-entry:has-text("Unpin")').click()
@@ -160,8 +158,8 @@ test.describe('Node Right Click Menu', { tag: ['@screenshot', '@ui'] }, () => {
      button: 'right'
    })
    await comfyPage.page.mouse.move(10, 10)
-    await comfyPage.nextFrame()
-    await expect(comfyPage.canvas).toHaveScreenshot(
+    await comfyPage.expectScreenshot(
+      comfyPage.canvas,
      'right-click-unpinned-node.png'
    )
  })
@@ -206,8 +204,10 @@ test.describe('Node Right Click Menu', { tag: ['@screenshot', '@ui'] }, () => {
    await comfyPage.page.locator('.litemenu-entry:has-text("Pin")').click()
    await comfyPage.page.keyboard.up('Control')
    await comfyPage.contextMenu.waitForHidden()
-    await comfyPage.nextFrame()
-    await expect(comfyPage.canvas).toHaveScreenshot('selected-nodes-pinned.png')
+    await comfyPage.expectScreenshot(
+      comfyPage.canvas,
+      'selected-nodes-pinned.png'
+    )
    await comfyPage.canvas.click({
      position: DefaultGraphPositions.emptyLatentWidgetClick,
      button: 'right'
@@ -216,8 +216,8 @@ test.describe('Node Right Click Menu', { tag: ['@screenshot', '@ui'] }, () => {
    await comfyPage.nextFrame()
    await comfyPage.page.locator('.litemenu-entry:has-text("Unpin")').click()
    await comfyPage.contextMenu.waitForHidden()
-    await comfyPage.nextFrame()
-    await expect(comfyPage.canvas).toHaveScreenshot(
+    await comfyPage.expectScreenshot(
+      comfyPage.canvas,
      'selected-nodes-unpinned.png'
    )
  })
--- a/browser_tests/tests/selectionRectangle.spec.ts
+++ b/browser_tests/tests/selectionRectangle.spec.ts
@@ -11,15 +11,13 @@ test.describe('@canvas Selection Rectangle', { tag: '@vue-nodes' }, () => {
    const totalCount = await comfyPage.vueNodes.getNodeCount()

    // Use canvas press for keyboard shortcuts (doesn't need click target)
-    await comfyPage.canvas.press('Control+a')
-    await comfyPage.nextFrame()
+    await comfyPage.keyboard.press('Control+a')

    await expect(comfyPage.vueNodes.selectedNodes).toHaveCount(totalCount)
  })

  test('Click empty space deselects all', async ({ comfyPage }) => {
-    await comfyPage.canvas.press('Control+a')
-    await comfyPage.nextFrame()
+    await comfyPage.keyboard.press('Control+a')
    await expect(comfyPage.vueNodes.selectedNodes).not.toHaveCount(0)

    // Deselect by Ctrl+clicking the already-selected node (reliable cross-env)
@@ -70,8 +68,7 @@ test.describe('@canvas Selection Rectangle', { tag: '@vue-nodes' }, () => {

    // Use Ctrl+A to select all, which is functionally equivalent to
    // drag-selecting the entire canvas and more reliable in CI
-    await comfyPage.canvas.press('Control+a')
-    await comfyPage.nextFrame()
+    await comfyPage.keyboard.press('Control+a')

    await expect
      .poll(() => comfyPage.vueNodes.getNodeCount())
--- a/browser_tests/tests/selectionToolbox.spec.ts
+++ b/browser_tests/tests/selectionToolbox.spec.ts
@@ -267,8 +267,7 @@ test.describe('Selection Toolbox', { tag: ['@screenshot', '@ui'] }, () => {
        .click()

      // Undo the colorization
-      await comfyPage.page.keyboard.press('Control+Z')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('Control+Z')

      // Node should be uncolored again
      const selectedNode = (
--- a/browser_tests/tests/selectionToolboxSubmenus.spec.ts
+++ b/browser_tests/tests/selectionToolboxSubmenus.spec.ts
@@ -43,7 +43,6 @@ test.describe(
      await comfyPage.nextFrame()

      await ksamplerNodes[0].click('title')
-      await comfyPage.nextFrame()

      await expect(comfyPage.page.locator('.selection-toolbox')).toBeVisible()

--- a/browser_tests/tests/sidebar/sidebarSplitterWidth.spec.ts
+++ b/browser_tests/tests/sidebar/sidebarSplitterWidth.spec.ts
@@ -39,7 +39,6 @@ test.describe('Sidebar splitter width independence', () => {
    location: 'left' | 'right'
  ) {
    await comfyPage.settings.setSetting('Comfy.Sidebar.Location', location)
-    await comfyPage.nextFrame()
    await dismissToasts(comfyPage)
    await comfyPage.menu.nodeLibraryTab.open()
  }
--- a/browser_tests/tests/subgraph/subgraphNavigation.spec.ts
+++ b/browser_tests/tests/subgraph/subgraphNavigation.spec.ts
@@ -49,8 +49,7 @@ test.describe('Subgraph Navigation', { tag: ['@slow', '@subgraph'] }, () => {
      await expect(breadcrumb).toBeVisible({ timeout: 20_000 })
      const initialBreadcrumbText = (await breadcrumb.textContent()) ?? ''

-      await comfyPage.page.keyboard.press('Escape')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('Escape')

      await comfyPage.canvas.dblclick({
        position: {
@@ -64,8 +63,7 @@ test.describe('Subgraph Navigation', { tag: ['@slow', '@subgraph'] }, () => {

      await comfyPage.page.keyboard.press('Control+a')
      await comfyPage.page.keyboard.type(UPDATED_SUBGRAPH_TITLE)
-      await comfyPage.page.keyboard.press('Enter')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('Enter')

      await subgraphNode.navigateIntoSubgraph()
      await expect(breadcrumb).toBeVisible()
@@ -145,8 +143,7 @@ test.describe('Subgraph Navigation', { tag: ['@slow', '@subgraph'] }, () => {

      await expect.poll(() => comfyPage.subgraph.isInSubgraph()).toBe(true)

-      await comfyPage.page.keyboard.press('Escape')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('Escape')
      await expect
        .poll(() => comfyPage.subgraph.isInSubgraph(), {
          message:
@@ -154,8 +151,7 @@ test.describe('Subgraph Navigation', { tag: ['@slow', '@subgraph'] }, () => {
        })
        .toBe(true)

-      await comfyPage.page.keyboard.press('Alt+q')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('Alt+q')
      await expect.poll(() => comfyPage.subgraph.isInSubgraph()).toBe(false)
    })

@@ -183,8 +179,7 @@ test.describe('Subgraph Navigation', { tag: ['@slow', '@subgraph'] }, () => {
        comfyPage.page.getByTestId(TestIds.dialogs.settings)
      ).toBeVisible()

-      await comfyPage.page.keyboard.press('Escape')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('Escape')

      await expect(
        comfyPage.page.getByTestId(TestIds.dialogs.settings)
@@ -192,8 +187,7 @@ test.describe('Subgraph Navigation', { tag: ['@slow', '@subgraph'] }, () => {

      await expect.poll(() => comfyPage.subgraph.isInSubgraph()).toBe(true)

-      await comfyPage.page.keyboard.press('Escape')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('Escape')
      await expect.poll(() => comfyPage.subgraph.isInSubgraph()).toBe(false)
    })
  })
@@ -296,8 +290,7 @@ test.describe('Subgraph Navigation', { tag: ['@slow', '@subgraph'] }, () => {

      await expect.poll(() => comfyPage.subgraph.isInSubgraph()).toBe(true)

-      await comfyPage.page.keyboard.press('Escape')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('Escape')

      await expect
        .poll(() =>
--- a/browser_tests/tests/subgraph/subgraphOperations.spec.ts
+++ b/browser_tests/tests/subgraph/subgraphOperations.spec.ts
@@ -38,13 +38,10 @@ test.describe('Subgraph Operations', { tag: ['@slow', '@subgraph'] }, () => {

      const nodeToClone = await comfyPage.nodeOps.getNodeRefById(String(nodeId))
      await nodeToClone.click('title')
-      await comfyPage.nextFrame()

-      await comfyPage.page.keyboard.press('ControlOrMeta+c')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('ControlOrMeta+c')

-      await comfyPage.page.keyboard.press('ControlOrMeta+v')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('ControlOrMeta+v')

      await expect
        .poll(() => comfyPage.subgraph.getNodeCount())
--- a/browser_tests/tests/subgraph/subgraphPromotionDom.spec.ts
+++ b/browser_tests/tests/subgraph/subgraphPromotionDom.spec.ts
@@ -88,8 +88,7 @@ test.describe('Subgraph Promotion DOM', { tag: ['@subgraph'] }, () => {

      await expect(subgraphTextarea).toHaveValue(TEST_WIDGET_CONTENT)

-      await comfyPage.page.keyboard.press('Escape')
-      await comfyPage.nextFrame()
+      await comfyPage.keyboard.press('Escape')

      const backToParentTextarea = comfyPage.page.locator(DOM_WIDGET_SELECTOR)
      await expect(backToParentTextarea).toBeVisible()
--- a/browser_tests/tests/subgraph/subgraphSearch.spec.ts
+++ b/browser_tests/tests/subgraph/subgraphSearch.spec.ts
@@ -15,8 +15,7 @@ async function exitSubgraphAndPublish(
  subgraphNode: Awaited<ReturnType<typeof createSubgraphAndNavigateInto>>,
  blueprintName: string
 ) {
-  await comfyPage.page.keyboard.press('Escape')
-  await comfyPage.nextFrame()
+  await comfyPage.keyboard.press('Escape')

  await subgraphNode.click('title')
  await comfyPage.command.executeCommand('Comfy.PublishSubgraph', {
--- a/browser_tests/tests/subgraph/subgraphSerialization.spec.ts
+++ b/browser_tests/tests/subgraph/subgraphSerialization.spec.ts
@@ -85,8 +85,7 @@ test.describe('Subgraph Serialization', { tag: ['@subgraph'] }, () => {

    await expect.poll(() => comfyPage.subgraph.isInSubgraph()).toBe(true)

-    await comfyPage.page.keyboard.press('Escape')
-    await comfyPage.nextFrame()
+    await comfyPage.keyboard.press('Escape')

    await expect.poll(() => comfyPage.subgraph.isInSubgraph()).toBe(false)
  })
--- a/browser_tests/tests/subgraph/subgraphSlots.spec.ts
+++ b/browser_tests/tests/subgraph/subgraphSlots.spec.ts
@@ -424,7 +424,6 @@ test.describe('Subgraph Slots', { tag: ['@slow', '@subgraph'] }, () => {
      await SubgraphHelper.expectWidgetBelowHeader(subgraphNode, seedWidget)

      await comfyPage.settings.setSetting('Comfy.VueNodes.Enabled', false)
-      await comfyPage.nextFrame()

      const subgraphNodeRef = await comfyPage.nodeOps.getNodeRefById('19')
      await subgraphNodeRef.navigateIntoSubgraph()
--- a/browser_tests/tests/viewport.spec.ts
+++ b/browser_tests/tests/viewport.spec.ts
@@ -34,9 +34,8 @@ test.describe('Viewport', { tag: ['@screenshot', '@smoke', '@canvas'] }, () => {
        { message: 'All nodes should be within the visible viewport' }
      )
      .toBe(true)
-    await comfyPage.nextFrame()
-
-    await expect(comfyPage.canvas).toHaveScreenshot(
+    await comfyPage.expectScreenshot(
+      comfyPage.canvas,
      'viewport-fits-when-saved-offscreen.png'
    )
  })
--- a/browser_tests/tests/vueNodes/groups/groups.spec.ts
+++ b/browser_tests/tests/vueNodes/groups/groups.spec.ts
@@ -121,8 +121,8 @@ test.describe('Vue Node Groups', { tag: ['@screenshot', '@vue-nodes'] }, () => {
    await comfyPage.page.getByText('Load Checkpoint').click()
    await comfyPage.page.getByText('KSampler').click({ modifiers: ['Control'] })
    await comfyPage.page.keyboard.press(CREATE_GROUP_HOTKEY)
-    await comfyPage.nextFrame()
-    await expect(comfyPage.canvas).toHaveScreenshot(
+    await comfyPage.expectScreenshot(
+      comfyPage.canvas,
      'vue-groups-create-group.png'
    )
  })
@@ -131,7 +131,6 @@ test.describe('Vue Node Groups', { tag: ['@screenshot', '@vue-nodes'] }, () => {
    await comfyPage.workflow.loadWorkflow('groups/oversized_group')
    await comfyPage.keyboard.selectAll()
    await comfyPage.command.executeCommand('Comfy.Graph.FitGroupToContents')
-    await comfyPage.nextFrame()
    await expect(comfyPage.canvas).toHaveScreenshot(
      'vue-groups-fit-to-contents.png'
    )
--- a/browser_tests/tests/vueNodes/nodeStates/bypass.spec.ts
+++ b/browser_tests/tests/vueNodes/nodeStates/bypass.spec.ts
@@ -24,8 +24,8 @@ test.describe('Vue Node Bypass', { tag: '@vue-nodes' }, () => {
        .filter({ hasText: 'Load Checkpoint' })
        .getByTestId('node-inner-wrapper')
      await expect(checkpointNode).toHaveClass(BYPASS_CLASS)
-      await comfyPage.nextFrame()
-      await expect(comfyPage.canvas).toHaveScreenshot(
+      await comfyPage.expectScreenshot(
+        comfyPage.canvas,
        'vue-node-bypassed-state.png'
      )

--- a/browser_tests/tests/vueNodes/nodeStates/mute.spec.ts
+++ b/browser_tests/tests/vueNodes/nodeStates/mute.spec.ts
@@ -5,17 +5,19 @@ import {

 const MUTE_HOTKEY = 'Control+m'
 const MUTE_OPACITY = '0.5'
+const SELECTED_CLASS = /outline-node-component-outline/

 test.describe('Vue Node Mute', { tag: '@vue-nodes' }, () => {
  test(
    'should allow toggling mute on a selected node with hotkey',
    { tag: '@screenshot' },
    async ({ comfyPage }) => {
-      await comfyPage.page.getByText('Load Checkpoint').click()
-      await comfyPage.page.keyboard.press(MUTE_HOTKEY)
-
      const checkpointNode =
        comfyPage.vueNodes.getNodeByTitle('Load Checkpoint')
+      await comfyPage.page.getByText('Load Checkpoint').click()
+      await expect(checkpointNode).toHaveClass(SELECTED_CLASS)
+
+      await comfyPage.page.keyboard.press(MUTE_HOTKEY)
      await expect(checkpointNode).toHaveCSS('opacity', MUTE_OPACITY)
      await expect(comfyPage.canvas).toHaveScreenshot(
        'vue-node-muted-state.png'
@@ -29,12 +31,14 @@ test.describe('Vue Node Mute', { tag: '@vue-nodes' }, () => {
  test('should allow toggling mute on multiple selected nodes with hotkey', async ({
    comfyPage
  }) => {
-    await comfyPage.page.getByText('Load Checkpoint').click()
-    await comfyPage.page.getByText('KSampler').click({ modifiers: ['Control'] })
-
    const checkpointNode = comfyPage.vueNodes.getNodeByTitle('Load Checkpoint')
    const ksamplerNode = comfyPage.vueNodes.getNodeByTitle('KSampler')

+    await comfyPage.page.getByText('Load Checkpoint').click()
+    await expect(checkpointNode).toHaveClass(SELECTED_CLASS)
+    await comfyPage.page.getByText('KSampler').click({ modifiers: ['Control'] })
+    await expect(ksamplerNode).toHaveClass(SELECTED_CLASS)
+
    await comfyPage.page.keyboard.press(MUTE_HOTKEY)
    await expect(checkpointNode).toHaveCSS('opacity', MUTE_OPACITY)
    await expect(ksamplerNode).toHaveCSS('opacity', MUTE_OPACITY)
--- a/browser_tests/tests/vueNodes/rerouteNodeSize.spec.ts
+++ b/browser_tests/tests/vueNodes/rerouteNodeSize.spec.ts
@@ -1,7 +1,4 @@
-import {
-  comfyExpect as expect,
-  comfyPageFixture as test
-} from '@e2e/fixtures/ComfyPage'
+import { comfyPageFixture as test } from '@e2e/fixtures/ComfyPage'

 test.describe('Vue Reroute Node Size', { tag: '@vue-nodes' }, () => {
  test.beforeEach(async ({ comfyPage }) => {
@@ -13,8 +10,8 @@ test.describe('Vue Reroute Node Size', { tag: '@vue-nodes' }, () => {
    'reroute node visual appearance',
    { tag: '@screenshot' },
    async ({ comfyPage }) => {
-      await comfyPage.nextFrame()
-      await expect(comfyPage.canvas).toHaveScreenshot(
+      await comfyPage.expectScreenshot(
+        comfyPage.canvas,
        'vue-reroute-node-compact.png'
      )
    }
--- a/browser_tests/tests/workflowPersistence.spec.ts
+++ b/browser_tests/tests/workflowPersistence.spec.ts
@@ -289,10 +289,8 @@ test.describe('Workflow Persistence', () => {
    const initialNodeCount = await comfyPage.nodeOps.getNodeCount()

    await comfyPage.settings.setSetting('Comfy.Locale', 'zh')
-    await comfyPage.nextFrame()

    await comfyPage.settings.setSetting('Comfy.Locale', 'en')
-    await comfyPage.nextFrame()

    await expect
      .poll(() => comfyPage.nodeOps.getNodeCount())
@@ -349,7 +347,6 @@ test.describe('Workflow Persistence', () => {

    // Create B: duplicate, add a node, then save (unmodified after save)
    await comfyPage.command.executeCommand('Comfy.DuplicateWorkflow')
-    await comfyPage.nextFrame()

    await comfyPage.page.evaluate(() => {
      window.app!.graph.add(window.LiteGraph!.createNode('Note', undefined, {}))
@@ -410,7 +407,6 @@ test.describe('Workflow Persistence', () => {

    // Create B: duplicate and save
    await comfyPage.command.executeCommand('Comfy.DuplicateWorkflow')
-    await comfyPage.nextFrame()
    await comfyPage.menu.topbar.saveWorkflow(nameB)

    // Add a Note node in B to mark it as modified
@@ -487,7 +483,6 @@ test.describe('Workflow Persistence', () => {

    // Create B as an unsaved workflow with a Note node
    await comfyPage.command.executeCommand('Comfy.NewBlankWorkflow')
-    await comfyPage.nextFrame()

    await comfyPage.page.evaluate(() => {
      window.app!.graph.add(window.LiteGraph!.createNode('Note', undefined, {}))