@lullabot/playwright-testing 0.1.0

package/src/interaction-states.test.ts

@@ -0,0 +1,48 @@
+import {describe, expect, it, vi} from 'vitest'
+import {applyInteractionStates, validateInteractionStates} from './interaction-states'
+
+describe('validateInteractionStates', () => {
+  it('rejects states that real input cannot hold simultaneously', () => {
+    const locator = {} as never
+    expect(() => validateInteractionStates([
+      {locator, states: ['hover']},
+      {locator, states: ['hover']},
+    ])).toThrow('at most one')
+    expect(() => validateInteractionStates([
+      {locator, states: ['focus', 'focus']},
+    ])).toThrow('cannot repeat')
+  })
+})
+
+describe('applyInteractionStates', () => {
+  it('applies hover before focus and cleans both states up', async () => {
+    const hover = vi.fn().mockResolvedValue(undefined)
+    const focus = vi.fn().mockResolvedValue(undefined)
+    const blur = vi.fn().mockResolvedValue(undefined)
+    const clearHover = vi.fn().mockResolvedValue(undefined)
+
+    const cleanup = await applyInteractionStates([
+      {locator: {hover, focus: vi.fn(), blur: vi.fn()} as never, states: ['hover']},
+      {locator: {hover: vi.fn(), focus, blur} as never, states: ['focus']},
+    ], {clearHover})
+
+    expect(hover.mock.invocationCallOrder[0]).toBeLessThan(focus.mock.invocationCallOrder[0])
+    await cleanup()
+    await cleanup()
+    expect(blur).toHaveBeenCalledOnce()
+    expect(clearHover).toHaveBeenCalledOnce()
+  })
+
+  it('cleans already-applied state when a later interaction fails', async () => {
+    const clearHover = vi.fn().mockResolvedValue(undefined)
+    const blur = vi.fn().mockResolvedValue(undefined)
+    const failure = new Error('focus failed')
+
+    await expect(applyInteractionStates([
+      {locator: {hover: vi.fn().mockResolvedValue(undefined)} as never, states: ['hover']},
+      {locator: {focus: vi.fn().mockRejectedValue(failure), blur} as never, states: ['focus']},
+    ], {clearHover})).rejects.toBe(failure)
+    expect(blur).toHaveBeenCalledOnce()
+    expect(clearHover).toHaveBeenCalledOnce()
+  })
+})

package/src/interaction-states.ts

@@ -0,0 +1,94 @@
+import type {Locator} from '@playwright/test'
+
+/** Real browser interaction states supported consistently by Playwright. */
+export type InteractionState = 'hover' | 'focus'
+
+/** A locator and the real browser interaction states to apply to it. */
+export interface ScreenshotInteractionState {
+  locator: Locator
+  states: InteractionState[]
+}
+
+export interface InteractionStateCleanupOptions {
+  /** Move the pointer away from the hovered locator during cleanup. */
+  clearHover?: () => Promise<void>
+}
+
+/** Validate that the requested states are possible with real browser input. */
+export function validateInteractionStates(
+  interactionStates: ScreenshotInteractionState[],
+): void {
+  const hoverTargets = interactionStates.filter(({states}) => states.includes('hover'))
+  const focusTargets = interactionStates.filter(({states}) => states.includes('focus'))
+
+  if (hoverTargets.length > 1) {
+    throw new Error('interactionStates can hover at most one locator at a time.')
+  }
+  if (focusTargets.length > 1) {
+    throw new Error('interactionStates can focus at most one locator at a time.')
+  }
+  for (const {states} of interactionStates) {
+    if (new Set(states).size !== states.length) {
+      throw new Error('interactionStates cannot repeat a state for the same locator.')
+    }
+  }
+}
+
+/**
+ * Apply real hover and focus, returning an idempotent cleanup function.
+ *
+ * Hover is applied before focus so focusing cannot disturb the pointer. If an
+ * interaction fails, any state already applied is cleaned before the original
+ * error is rethrown.
+ */
+export async function applyInteractionStates(
+  interactionStates: ScreenshotInteractionState[],
+  cleanupOptions: InteractionStateCleanupOptions = {},
+): Promise<() => Promise<void>> {
+  validateInteractionStates(interactionStates)
+
+  const hoverTarget = interactionStates.find(({states}) => states.includes('hover'))?.locator
+  const focusTarget = interactionStates.find(({states}) => states.includes('focus'))?.locator
+  let hoverApplied = false
+  let focusApplied = false
+  let cleaned = false
+
+  const cleanup = async () => {
+    if (cleaned) {
+      return
+    }
+    cleaned = true
+    try {
+      if (focusApplied) {
+        await focusTarget?.blur()
+      }
+    } finally {
+      if (hoverApplied) {
+        await cleanupOptions.clearHover?.()
+      }
+    }
+  }
+
+  try {
+    if (hoverTarget) {
+      // Mark the state first: Playwright can move the pointer and then fail
+      // while waiting for actionability, and that partial effect still needs
+      // cleanup.
+      hoverApplied = true
+      await hoverTarget.hover()
+    }
+    if (focusTarget) {
+      focusApplied = true
+      await focusTarget.focus()
+    }
+    return cleanup
+  } catch (error) {
+    try {
+      await cleanup()
+    } catch {
+      // Preserve the interaction failure. Cleanup is best effort on this path;
+      // callers cannot act on a cleanup error if applying the state failed.
+    }
+    throw error
+  }
+}

package/src/mock/index.ts

@@ -0,0 +1 @@
+export { YoutubeMock } from './youtube.js'

package/src/mock/youtube.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect, vi } from 'vitest'
+import { YoutubeMock } from './youtube'
+
+describe('YoutubeMock', () => {
+  it('registers a route handler for youtube.com', async () => {
+    const mockPage = {
+      route: vi.fn(),
+    }
+
+    const mock = new YoutubeMock()
+    await mock.mock(mockPage as any)
+
+    expect(mockPage.route).toHaveBeenCalledOnce()
+    const [pattern] = mockPage.route.mock.calls[0]
+    expect(pattern).toBeInstanceOf(RegExp)
+    expect(pattern.test('https://www.youtube.com/embed/abc123')).toBe(true)
+    expect(pattern.test('https://www.notyoutube.com')).toBe(false)
+  })
+
+  it('fulfills with HTML mock content', async () => {
+    const mockFulfill = vi.fn()
+    const mockPage = {
+      route: vi.fn(),
+    }
+
+    const mock = new YoutubeMock()
+    await mock.mock(mockPage as any)
+
+    // Call the route handler
+    const handler = mockPage.route.mock.calls[0][1]
+    await handler({ fulfill: mockFulfill })
+
+    expect(mockFulfill).toHaveBeenCalledOnce()
+    const fulfillArg = mockFulfill.mock.calls[0][0]
+    expect(fulfillArg.contentType).toBe('text/html')
+    expect(fulfillArg.body).toContain('Youtube Video Mock')
+  })
+})

package/src/mock/youtube.ts

@@ -0,0 +1,39 @@
+import type {Page} from '@playwright/test';
+import type {Mockable} from "../visualdiff.js";
+
+export class YoutubeMock implements Mockable {
+
+  public async mock(page: Page): Promise<void> {
+    await page.route(/www\.youtube\.com/i, async route => {
+      await route.fulfill({
+        contentType: 'text/html',
+        body: `
+<html>
+<head>
+    <title>Youtube Video Mock</title>
+    <style>
+        body {
+          color: white;
+          background-color: darkred;
+        }
+        div {
+          position: absolute;
+          top: 50%;
+          left: 50%;
+          margin: 0;
+          transform: translate(-50%, -50%);
+          font-size: xxx-large;
+          text-align: center;
+        }
+    </style>
+</head>
+<body>
+    <div>Youtube Video Mock</div>
+</body>
+</html>
+`,
+      });
+    });
+  }
+
+}

package/src/pseudo-state.test.ts

@@ -0,0 +1,83 @@
+import {describe, expect, it, vi} from 'vitest'
+import {forcePseudoState} from './pseudo-state'
+
+function fakePage(nodeId = 2) {
+  const session = {
+    send: vi.fn(async (method: string) => {
+      if (method === 'DOM.getDocument') {
+        return {root: {nodeId: 1}}
+      }
+      if (method === 'DOM.querySelector') {
+        return {nodeId}
+      }
+      return {}
+    }),
+    detach: vi.fn().mockResolvedValue(undefined),
+  }
+  const context = {
+    newCDPSession: vi.fn().mockResolvedValue(session),
+  }
+  const page = {
+    context: vi.fn(() => context),
+  }
+
+  return {context, page, session}
+}
+
+describe('forcePseudoState', () => {
+  it('forces pseudo-classes on the first selector match and clears them', async () => {
+    const {context, page, session} = fakePage()
+
+    const cleanup = await forcePseudoState(page as any, '.menu-trigger', ['hover', 'focus-visible'])
+
+    expect(context.newCDPSession).toHaveBeenCalledWith(page)
+    expect(session.send).toHaveBeenNthCalledWith(1, 'DOM.enable')
+    expect(session.send).toHaveBeenNthCalledWith(2, 'CSS.enable')
+    expect(session.send).toHaveBeenNthCalledWith(3, 'DOM.getDocument')
+    expect(session.send).toHaveBeenNthCalledWith(4, 'DOM.querySelector', {
+      nodeId: 1,
+      selector: '.menu-trigger',
+    })
+    expect(session.send).toHaveBeenNthCalledWith(5, 'CSS.forcePseudoState', {
+      nodeId: 2,
+      forcedPseudoClasses: ['hover', 'focus-visible'],
+    })
+
+    await cleanup()
+    await cleanup()
+
+    expect(session.send).toHaveBeenNthCalledWith(6, 'CSS.forcePseudoState', {
+      nodeId: 2,
+      forcedPseudoClasses: [],
+    })
+    expect(session.detach).toHaveBeenCalledOnce()
+  })
+
+  it('fails clearly and detaches when the selector does not match', async () => {
+    const {page, session} = fakePage(0)
+
+    await expect(forcePseudoState(page as any, '.missing', ['hover']))
+      .rejects.toThrow('could not find an element matching ".missing"')
+    expect(session.detach).toHaveBeenCalledOnce()
+  })
+
+  it('reports that CDP requires Chromium', async () => {
+    const page = {
+      context: () => ({
+        newCDPSession: vi.fn().mockRejectedValue(new Error('CDP only supported in Chromium')),
+      }),
+    }
+
+    await expect(forcePseudoState(page as any, 'button', ['focus']))
+      .rejects.toThrow('requires a Chromium browser project')
+  })
+
+  it('detaches even when clearing the state fails', async () => {
+    const {page, session} = fakePage()
+    const cleanup = await forcePseudoState(page as any, 'button', ['focus'])
+    session.send.mockRejectedValueOnce(new Error('node disappeared'))
+
+    await expect(cleanup()).rejects.toThrow('node disappeared')
+    expect(session.detach).toHaveBeenCalledOnce()
+  })
+})

package/src/pseudo-state.ts

@@ -0,0 +1,69 @@
+import {Page} from '@playwright/test'
+
+/** Pseudo-classes supported by Chromium's CSS.forcePseudoState command. */
+export type ForcedPseudoClass =
+  | 'active'
+  | 'focus'
+  | 'focus-visible'
+  | 'focus-within'
+  | 'hover'
+  | 'target'
+
+/** A CSS selector and the pseudo-classes to force on its first match. */
+export interface ForcedPseudoState {
+  selector: string
+  pseudoClasses: ForcedPseudoClass[]
+}
+
+/**
+ * Force CSS pseudo-classes on the first element matching a selector.
+ *
+ * This uses Chromium's DevTools Protocol and therefore only works in Chromium
+ * projects. The state is synthetic: moving the pointer or blurring the active
+ * element does not clear it. Call the returned idempotent cleanup function when
+ * the screenshot and accessibility scan are complete.
+ */
+export async function forcePseudoState(
+  page: Page,
+  selector: string,
+  pseudoClasses: ForcedPseudoClass[],
+): Promise<() => Promise<void>> {
+  let session
+  try {
+    session = await page.context().newCDPSession(page)
+  } catch (error) {
+    throw new Error('forcePseudoState() requires a Chromium browser project.', {cause: error})
+  }
+
+  try {
+    await session.send('DOM.enable')
+    await session.send('CSS.enable')
+    const {root} = await session.send('DOM.getDocument')
+    const {nodeId} = await session.send('DOM.querySelector', {
+      nodeId: root.nodeId,
+      selector,
+    })
+
+    if (!nodeId) {
+      throw new Error(`forcePseudoState() could not find an element matching "${selector}".`)
+    }
+
+    await session.send('CSS.forcePseudoState', {nodeId, forcedPseudoClasses: pseudoClasses})
+
+    let cleared = false
+    return async () => {
+      if (cleared) {
+        return
+      }
+      cleared = true
+      try {
+        await session.send('CSS.forcePseudoState', {nodeId, forcedPseudoClasses: []})
+      } finally {
+        await session.detach()
+      }
+    }
+  } catch (error) {
+    await session.detach()
+    throw error
+  }
+}