tabwright 1.0.0

package/src/kitty-graphics.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, test } from 'vitest'
+import { buildKittySequence, canEmitKittyGraphics } from './kitty-graphics.js'
+
+// Minimal valid PNG (1x1 transparent pixel) as base64
+const TINY_PNG_B64 =
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=='
+
+describe('kitty-graphics', () => {
+  describe('canEmitKittyGraphics', () => {
+    test('returns false when AGENT_GRAPHICS is not set', () => {
+      const prev = process.env.AGENT_GRAPHICS
+      delete process.env.AGENT_GRAPHICS
+      expect(canEmitKittyGraphics()).toBe(false)
+      if (prev !== undefined) {
+        process.env.AGENT_GRAPHICS = prev
+      }
+    })
+
+    test('returns true when AGENT_GRAPHICS=kitty', () => {
+      const prev = process.env.AGENT_GRAPHICS
+      process.env.AGENT_GRAPHICS = 'kitty'
+      expect(canEmitKittyGraphics()).toBe(true)
+      if (prev !== undefined) {
+        process.env.AGENT_GRAPHICS = prev
+      } else {
+        delete process.env.AGENT_GRAPHICS
+      }
+    })
+
+    test('returns true when AGENT_GRAPHICS contains kitty among others', () => {
+      const prev = process.env.AGENT_GRAPHICS
+      process.env.AGENT_GRAPHICS = 'kitty,iterm2'
+      expect(canEmitKittyGraphics()).toBe(true)
+      if (prev !== undefined) {
+        process.env.AGENT_GRAPHICS = prev
+      } else {
+        delete process.env.AGENT_GRAPHICS
+      }
+    })
+  })
+
+  describe('buildKittySequence', () => {
+    test('small payload produces single escape sequence', () => {
+      const result = buildKittySequence({ base64: 'AAAA' })
+      expect(result).toMatchInlineSnapshot(`"_Ga=T,f=100;AAAA\\"`)
+    })
+
+    test('sequence starts with APC and ends with ST', () => {
+      const result = buildKittySequence({ base64: 'AAAA' })
+      expect(result.startsWith('\x1b_G')).toBe(true)
+      expect(result.endsWith('\x1b\\')).toBe(true)
+    })
+
+    test('real PNG base64 produces valid sequence', () => {
+      const result = buildKittySequence({ base64: TINY_PNG_B64 })
+      // Should be a single chunk (small payload)
+      expect(result).toContain('a=T,f=100')
+      expect(result).toContain(TINY_PNG_B64)
+    })
+
+    test('large payload is chunked at 4096 bytes', () => {
+      // Create a payload larger than 4096 bytes
+      const bigPayload = 'A'.repeat(10000)
+      const result = buildKittySequence({ base64: bigPayload })
+
+      // Should have multiple escape sequences
+      // First chunk: a=T,f=100,m=1
+      expect(result).toContain('a=T,f=100,m=1')
+      // Last chunk: m=0
+      expect(result).toContain('\x1b_Gm=0;')
+      // Should NOT contain single-shot a=T,f=100; (without m=)
+      expect(result).not.toMatch(/a=T,f=100;/)
+    })
+
+    test('three-chunk payload has correct structure', () => {
+      // 9000 bytes = 3 chunks: 4096 + 4096 + 808
+      const payload = 'B'.repeat(9000)
+      const result = buildKittySequence({ base64: payload })
+
+      const sequences = result.split('\x1b\\').filter(Boolean)
+      expect(sequences.length).toBe(3)
+
+      // First: a=T,f=100,m=1
+      expect(sequences[0]).toContain('a=T,f=100,m=1')
+      // Middle: m=1
+      expect(sequences[1]).toContain('\x1b_Gm=1;')
+      // Last: m=0
+      expect(sequences[2]).toContain('\x1b_Gm=0;')
+    })
+  })
+
+  describe('round-trip with kitty-graphics-agent parser', () => {
+    test('emitted sequence can be parsed back to extract the image', async () => {
+      // Dynamically import the parser to test round-trip
+      let extractKittyGraphics: typeof import('kitty-graphics-agent/parser').extractKittyGraphics
+      try {
+        const mod = await import('kitty-graphics-agent/parser')
+        extractKittyGraphics = mod.extractKittyGraphics
+      } catch {
+        // kitty-graphics-agent not installed, skip
+        console.log('kitty-graphics-agent not installed, skipping round-trip test')
+        return
+      }
+
+      const sequence = buildKittySequence({ base64: TINY_PNG_B64 })
+      const output = `some text before\n${sequence}\nsome text after`
+      const result = extractKittyGraphics(output)
+
+      expect(result.cleanedOutput).toMatchInlineSnapshot(`
+        "some text before
+        
+        some text after"
+      `)
+      expect(result.images.length).toBe(1)
+      expect(result.images[0].mime).toBe('image/png')
+      expect(result.images[0].data).toBe(TINY_PNG_B64)
+    })
+
+    test('chunked sequence round-trips correctly', async () => {
+      let extractKittyGraphics: typeof import('kitty-graphics-agent/parser').extractKittyGraphics
+      try {
+        const mod = await import('kitty-graphics-agent/parser')
+        extractKittyGraphics = mod.extractKittyGraphics
+      } catch {
+        console.log('kitty-graphics-agent not installed, skipping round-trip test')
+        return
+      }
+
+      const bigPayload = 'A'.repeat(10000)
+      const sequence = buildKittySequence({ base64: bigPayload })
+      const result = extractKittyGraphics(sequence)
+
+      expect(result.cleanedOutput).toBe('')
+      expect(result.images.length).toBe(1)
+      expect(result.images[0].mime).toBe('image/png')
+      expect(result.images[0].data).toBe(bigPayload)
+    })
+  })
+})

package/src/kitty-graphics.ts

@@ -0,0 +1,79 @@
+// Kitty Graphics Protocol emitter for CLI output.
+// Emits base64-encoded PNG images as APC escape sequences so agents with
+// kitty-graphics-agent (or compatible parsers) can extract and pass them
+// to LLMs as media parts.
+//
+// Protocol format:
+//   \x1b_G<control_data>;<base64_payload>\x1b\\
+//
+// Only emits when AGENT_GRAPHICS env var contains 'kitty', signaling that
+// an agent is intercepting stdout and can handle Kitty Graphics Protocol.
+// See: https://github.com/remorses/kitty-graphics-agent
+
+// Kitty spec recommends max 4096 bytes per chunk payload
+const CHUNK_SIZE = 4096
+
+/**
+ * Check if the current environment supports Kitty Graphics Protocol output.
+ * Returns true when AGENT_GRAPHICS=kitty is set (agent is intercepting stdout).
+ */
+export function canEmitKittyGraphics(): boolean {
+  return process.env.AGENT_GRAPHICS?.includes('kitty') ?? false
+}
+
+/**
+ * Emit a PNG image to stdout using the Kitty Graphics Protocol.
+ * The image is chunked per the spec (4096 bytes per chunk).
+ *
+ * Only call this when canEmitKittyGraphics() returns true.
+ */
+export function emitKittyImage({ base64 }: { base64: string }): void {
+  const chunks = splitIntoChunks(base64, CHUNK_SIZE)
+
+  if (chunks.length === 1) {
+    // Single chunk: no chunked transfer needed
+    process.stdout.write(`\x1b_Ga=T,f=100;${chunks[0]}\x1b\\`)
+    return
+  }
+
+  // Multi-chunk: first chunk has full control data + m=1,
+  // continuation chunks have only m=1, last chunk has m=0
+  for (let i = 0; i < chunks.length; i++) {
+    const isFirst = i === 0
+    const isLast = i === chunks.length - 1
+    const control = isFirst ? 'a=T,f=100,m=1' : isLast ? 'm=0' : 'm=1'
+    process.stdout.write(`\x1b_G${control};${chunks[i]}\x1b\\`)
+  }
+}
+
+function splitIntoChunks(str: string, size: number): string[] {
+  if (str.length <= size) {
+    return [str]
+  }
+  const chunks: string[] = []
+  for (let i = 0; i < str.length; i += size) {
+    chunks.push(str.slice(i, i + size))
+  }
+  return chunks
+}
+
+/**
+ * Build the raw Kitty Graphics escape sequence string for a PNG image.
+ * Useful for testing without writing to stdout.
+ */
+export function buildKittySequence({ base64 }: { base64: string }): string {
+  const chunks = splitIntoChunks(base64, CHUNK_SIZE)
+
+  if (chunks.length === 1) {
+    return `\x1b_Ga=T,f=100;${chunks[0]}\x1b\\`
+  }
+
+  const parts: string[] = []
+  for (let i = 0; i < chunks.length; i++) {
+    const isFirst = i === 0
+    const isLast = i === chunks.length - 1
+    const control = isFirst ? 'a=T,f=100,m=1' : isLast ? 'm=0' : 'm=1'
+    parts.push(`\x1b_G${control};${chunks[i]}\x1b\\`)
+  }
+  return parts.join('')
+}

package/src/locator-selector.test.ts

@@ -0,0 +1,119 @@
+// Tests for Locator.selector() — verifies the raw selector strings returned
+// by various locator creation methods (getByRole, locator, getByText, etc.)
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest'
+import { chromium, type Page, type Browser } from '@xmorse/playwright-core'
+import { getLocalChromeExecutable } from './test-utils.js'
+
+const HTML = `<!DOCTYPE html>
+<html>
+<body>
+  <div id="main">
+    <button>Submit</button>
+    <button>Cancel</button>
+    <button class="primary">Save</button>
+    <input type="text" placeholder="Enter name" />
+    <input type="email" placeholder="Enter email" />
+    <a href="/about">About Us</a>
+    <h1>Page Title</h1>
+    <p>Some paragraph text</p>
+    <div class="card">
+      <span>Card content</span>
+    </div>
+    <div class="card">
+      <span>Another card</span>
+    </div>
+    <div class="card">
+      <span>Third card</span>
+    </div>
+    <label for="age">Age</label>
+    <input id="age" type="number" />
+    <img alt="Logo" src="/logo.png" />
+    <div data-testid="dashboard">Dashboard</div>
+  </div>
+</body>
+</html>`
+
+describe('Locator.selector()', () => {
+  let browser: Browser
+  let page: Page
+
+  beforeAll(async () => {
+    const chromeExecutable = getLocalChromeExecutable()
+    browser = await chromium.launch(
+      chromeExecutable ? { executablePath: chromeExecutable, headless: true } : { channel: 'chromium', headless: true },
+    )
+    const context = await browser.newContext()
+    page = await context.newPage()
+    await page.setContent(HTML)
+  })
+
+  afterAll(async () => {
+    await browser.close()
+  })
+
+  it('CSS selectors', () => {
+    expect(page.locator('#main').selector()).toMatchInlineSnapshot(`"#main"`)
+    expect(page.locator('.card').selector()).toMatchInlineSnapshot(`".card"`)
+    expect(page.locator('button').selector()).toMatchInlineSnapshot(`"button"`)
+    expect(page.locator('div.card > span').selector()).toMatchInlineSnapshot(`"div.card > span"`)
+    expect(page.locator('#main .card:first-child').selector()).toMatchInlineSnapshot(`"#main .card:first-child"`)
+  })
+
+  it('getByRole', () => {
+    expect(page.getByRole('button').selector()).toMatchInlineSnapshot(`"internal:role=button"`)
+    expect(page.getByRole('button', { name: 'Submit' }).selector()).toMatchInlineSnapshot(`"internal:role=button[name="Submit"i]"`)
+    expect(page.getByRole('link').selector()).toMatchInlineSnapshot(`"internal:role=link"`)
+    expect(page.getByRole('heading').selector()).toMatchInlineSnapshot(`"internal:role=heading"`)
+    expect(page.getByRole('textbox').selector()).toMatchInlineSnapshot(`"internal:role=textbox"`)
+  })
+
+  it('getByText', () => {
+    expect(page.getByText('Submit').selector()).toMatchInlineSnapshot(`"internal:text="Submit"i"`)
+    expect(page.getByText('Some paragraph').selector()).toMatchInlineSnapshot(`"internal:text="Some paragraph"i"`)
+    expect(page.getByText(/card/i).selector()).toMatchInlineSnapshot(`"internal:text=/card/i"`)
+  })
+
+  it('getByPlaceholder', () => {
+    expect(page.getByPlaceholder('Enter name').selector()).toMatchInlineSnapshot(`"internal:attr=[placeholder="Enter name"i]"`)
+    expect(page.getByPlaceholder('Enter email').selector()).toMatchInlineSnapshot(`"internal:attr=[placeholder="Enter email"i]"`)
+  })
+
+  it('getByLabel', () => {
+    expect(page.getByLabel('Age').selector()).toMatchInlineSnapshot(`"internal:label="Age"i"`)
+  })
+
+  it('getByAltText', () => {
+    expect(page.getByAltText('Logo').selector()).toMatchInlineSnapshot(`"internal:attr=[alt="Logo"i]"`)
+  })
+
+  it('getByTestId', () => {
+    expect(page.getByTestId('dashboard').selector()).toMatchInlineSnapshot(`"internal:testid=[data-testid="dashboard"s]"`)
+  })
+
+  it('chained locators', () => {
+    expect(page.locator('#main').locator('.card').selector()).toMatchInlineSnapshot(`"#main >> .card"`)
+    expect(page.locator('.card').first().selector()).toMatchInlineSnapshot(`".card >> nth=0"`)
+    expect(page.locator('.card').last().selector()).toMatchInlineSnapshot(`".card >> nth=-1"`)
+    expect(page.locator('.card').nth(1).selector()).toMatchInlineSnapshot(`".card >> nth=1"`)
+  })
+
+  it('filtered locators', () => {
+    expect(page.locator('button').filter({ hasText: 'Save' }).selector()).toMatchInlineSnapshot(`"button >> internal:has-text="Save"i"`)
+    expect(page.locator('div').filter({ has: page.locator('span') }).selector()).toMatchInlineSnapshot(`"div >> internal:has="span""`)
+    expect(page.locator('button').filter({ hasNotText: 'Cancel' }).selector()).toMatchInlineSnapshot(`"button >> internal:has-not-text="Cancel"i"`)
+  })
+
+  it('described locators', () => {
+    expect(page.locator('button').describe('main action button').selector()).toMatchInlineSnapshot(`"button >> internal:describe="main action button""`)
+  })
+
+  it('combined with and/or', () => {
+    expect(
+      page.locator('button').and(page.locator('.primary')).selector(),
+    ).toMatchInlineSnapshot(`"button >> internal:and=".primary""`)
+    expect(
+      page.locator('button').or(page.locator('a')).selector(),
+    ).toMatchInlineSnapshot(`"button >> internal:or="a""`)
+  })
+})

package/src/mcp-client.ts

@@ -0,0 +1,78 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js'
+import { Stream } from 'node:stream'
+import path from 'node:path'
+import url from 'node:url'
+
+const __filename = url.fileURLToPath(import.meta.url)
+
+export interface CreateTransportOptions {
+  clientName?: string
+  port?: number
+}
+
+export async function createTransport({ args = [], port }: { args?: string[]; port?: number } = {}): Promise<{
+  transport: Transport
+  stderr: Stream | null
+}> {
+  const env: Record<string, string> = {
+    ...(process.env as Record<string, string>),
+    DEBUG: 'tabwright:mcp:test',
+    DEBUG_COLORS: '0',
+    DEBUG_HIDE_DATE: '1',
+  }
+  if (port) {
+    env.PLAYWRITER_PORT = String(port)
+  }
+  const transport = new StdioClientTransport({
+    command: 'pnpm',
+    args: ['vite-node', path.join(path.dirname(__filename), 'cli.ts'), ...args],
+    cwd: path.join(path.dirname(__filename), '..'),
+    stderr: 'pipe',
+    env,
+  })
+
+  return {
+    transport,
+    stderr: transport.stderr!,
+  }
+}
+
+export async function createMCPClient(options?: CreateTransportOptions): Promise<{
+  client: Client
+  stderr: string
+  cleanup: () => Promise<void>
+}> {
+  const client = new Client({
+    name: options?.clientName ?? 'test',
+    version: '1.0.0',
+  })
+
+  const { transport, stderr } = await createTransport({ port: options?.port })
+
+  let stderrBuffer = ''
+  stderr?.on('data', (data) => {
+    process.stderr.write(data)
+
+    stderrBuffer += data.toString()
+  })
+
+  await client.connect(transport)
+  await client.ping()
+
+  const cleanup = async () => {
+    try {
+      await client.close()
+    } catch (e) {
+      console.error('Error during MCP client cleanup:', e)
+      // Ignore errors during cleanup
+    }
+  }
+
+  return {
+    client,
+    stderr: stderrBuffer,
+    cleanup,
+  }
+}