Skip to content

AI-native design editor. Open-source Figma alternative.

14.2 KB
Raw Blame
import { beforeAll, describe, expect, test } from 'bun:test'

import { DEFAULT_FONT_FAMILY } from '@open-pencil/core/constants'
import { FigmaAPI } from '@open-pencil/core/figma-api'
import { fontManager } from '@open-pencil/core/text'

import { expectDefined } from '#tests/helpers/assert'
import { registerTestFont } from '#tests/helpers/fonts/bundled'
import { getTool, setupToolTest, type ALL_TOOLS, type ToolResult } from '#tests/helpers/tools'

beforeAll(() => registerTestFont())

/** The `list_pages` tool answers with the document's pages. */
interface ListPagesResult extends ToolResult {
  pages: Array<{ id: string; name: string }>
}

describe('find_nodes', () => {
  test('finds by name', () => {
    const { figma } = setupToolTest()
    const rect = figma.createRectangle()
    rect.name = 'Button Primary'
    const text = figma.createText()
    text.name = 'Label'

    const tool = getTool('find_nodes')
    const result = tool.execute(figma, { name: 'button' }) as ToolResult
    expect(result.count).toBe(1)
    expect(expectDefined(result.nodes, 'found nodes')[0].name).toBe('Button Primary')
  })

  test('finds by type', () => {
    const { figma } = setupToolTest()
    figma.createRectangle()
    figma.createRectangle()
    figma.createText()

    const tool = getTool('find_nodes')
    const result = tool.execute(figma, { type: 'RECTANGLE' }) as ToolResult
    expect(result.count).toBe(2)
  })
})

describe('query_nodes', () => {
  test('finds all frames with //FRAME', async () => {
    const { figma } = setupToolTest()
    const f1 = figma.createFrame()
    f1.resize(200, 200)
    f1.name = 'Frame A'
    const f2 = figma.createFrame()
    f2.resize(300, 300)
    f2.name = 'Frame B'
    figma.createRectangle()

    const tool = getTool('query_nodes')
    const result = (await tool.execute(figma, { selector: '//FRAME' })) as ToolResult
    expect(result.count).toBe(2)
    expect(result.nodes?.every((n) => n.type === 'FRAME')).toBe(true)
  })

  test('finds by attribute //RECTANGLE[@width < 200]', async () => {
    const { figma } = setupToolTest()
    const small = figma.createRectangle()
    small.resize(100, 50)
    small.name = 'Small'
    const big = figma.createRectangle()
    big.resize(400, 400)
    big.name = 'Big'

    const tool = getTool('query_nodes')
    const result = (await tool.execute(figma, {
      selector: '//RECTANGLE[@width < 200]'
    })) as ToolResult
    expect(result.count).toBe(1)
    expect(expectDefined(result.nodes, 'queried nodes')[0].name).toBe('Small')
  })

  test('finds by name with contains', async () => {
    const { figma } = setupToolTest()
    const t1 = figma.createText()
    t1.name = 'Label Primary'
    const t2 = figma.createText()
    t2.name = 'Title'
    const t3 = figma.createText()
    t3.name = 'Label Secondary'

    const tool = getTool('query_nodes')
    const result = (await tool.execute(figma, {
      selector: '//TEXT[contains(@name, "Label")]'
    })) as ToolResult
    expect(result.count).toBe(2)
    expect(result.nodes?.every((n) => n.name.includes('Label'))).toBe(true)
  })

  test('returns error for invalid xpath', async () => {
    const { figma } = setupToolTest()
    const tool = getTool('query_nodes')
    const result = (await tool.execute(figma, { selector: '///invalid[[[[' })) as ToolResult
    expect(result.error).toBeTruthy()
    expect(result.error).toContain('XPath error')
  })

  test('respects limit param', async () => {
    const { figma } = setupToolTest()
    for (let i = 0; i < 10; i++) {
      const r = figma.createRectangle()
      r.name = `Rect ${i}`
    }

    const tool = getTool('query_nodes')
    const result = (await tool.execute(figma, { selector: '//RECTANGLE', limit: 3 })) as ToolResult
    expect(result.count).toBe(3)
  })

  test('returns the text of visible TEXT nodes inside a frame in layer order', async () => {
    const { figma } = setupToolTest()
    const card = figma.createFrame()
    const title = figma.createText()
    title.characters = 'Balance'
    const hiddenGroup = figma.createFrame()
    hiddenGroup.visible = false
    const hiddenText = figma.createText()
    hiddenText.characters = 'Draft'
    hiddenGroup.appendChild(hiddenText)
    const amount = figma.createText()
    amount.characters = '$12,450\nAvailable'
    card.appendChild(title)
    card.appendChild(hiddenGroup)
    card.appendChild(amount)
    figma.createText().characters = 'Outside'

    const tool = getTool('query_nodes')
    const result = (await tool.execute(figma, {
      selector: `//*[@id='${card.id}']//TEXT[not(ancestor-or-self::*[@visible='false'])]`
    })) as ToolResult
    expect(result.nodes?.map((node) => [node.id, node.text])).toEqual([
      [title.id, 'Balance'],
      [amount.id, '$12,450\nAvailable']
    ])
  })

  test('omits text for non-text nodes', async () => {
    const { figma } = setupToolTest()
    figma.createRectangle()

    const tool = getTool('query_nodes')
    const result = (await tool.execute(figma, { selector: '//RECTANGLE' })) as ToolResult
    expect(expectDefined(result.nodes, 'queried nodes')[0]).not.toHaveProperty('text')
  })

  test('returns empty array when nothing matches', async () => {
    const { figma } = setupToolTest()
    figma.createRectangle()

    const tool = getTool('query_nodes')
    const result = (await tool.execute(figma, { selector: '//ELLIPSE' })) as ToolResult
    expect(result.count).toBe(0)
    expect(result.nodes).toEqual([])
  })
})

describe('get_font_status', () => {
  test('returns font fidelity diagnostics for agents', () => {
    const { figma, graph } = setupToolTest()
    const text = figma.createText()
    text.name = 'Missing label'
    // A document can name a font this machine lacks; a script cannot set one it did not load.
    graph.updateNode(text.id, { fontFamily: 'Unavailable Sans' })

    const tool = getTool('get_font_status')
    const result = tool.execute(figma, {}) as {
      faithful: boolean
      issues: Array<{
        family: string
        style: string
        status: string
        nodeIds: string[]
      }>
    }

    // The tool reads the process-wide font manager. A missing family is
    // 'unresolved' in a pristine process and 'substituted' by the default font
    // once any earlier suite in the shard has loaded it; both are issues.
    const defaultLoaded = fontManager.loadedFontSource(DEFAULT_FONT_FAMILY, 'Regular') !== null

    expect(result.faithful).toBe(false)
    expect(result.issues).toEqual([
      expect.objectContaining({
        family: 'Unavailable Sans',
        style: 'Regular',
        status: defaultLoaded ? 'substituted' : 'unresolved',
        substituteFamily: defaultLoaded ? DEFAULT_FONT_FAMILY : null,
        nodeIds: [text.id]
      })
    ])
  })
})

describe('get_node', () => {
  test('returns node details', async () => {
    const { figma } = setupToolTest()
    const rect = figma.createRectangle()
    rect.name = 'Test Rect'
    rect.resize(100, 50)

    const tool = getTool('get_node')
    const result = (await tool.execute(figma, { id: rect.id })) as ToolResult
    expect(result.name).toBe('Test Rect')
    expect(result.width).toBe(100)
    expect(result.height).toBe(50)
  })
})

describe('get_page_tree', () => {
  test('includes the text of TEXT nodes', async () => {
    const { figma } = setupToolTest()
    const card = figma.createFrame()
    const label = figma.createText()
    label.characters = 'Saldo disponível'
    card.appendChild(label)

    const tool = getTool('get_page_tree')
    const result = await tool.execute(figma, { root_id: card.id, node_types: ['TEXT'] })
    expect(result).toMatchObject({
      root: card.id,
      tree: { id: card.id, children: [{ id: label.id, text: 'Saldo disponível' }] }
    })
    expect(result).not.toHaveProperty('tree.text')
  })
})

describe('pages not yet visited', () => {
  /** A document whose second page has no layers until the host loads it, as the editor's do. */
  function lazyDocument() {
    const { graph } = setupToolTest()
    const later = graph.addPage('Later')
    const loads: string[] = []
    const figma = new FigmaAPI(graph, {
      loadPage: async (id) => {
        loads.push(id)
        if (id === later.id && graph.getChildren(id).length === 0)
          graph.createNode('COMPONENT', id, { name: 'Loaded button' })
      }
    })
    return { figma, later, loads }
  }

  test('load before a tool reads them', async () => {
    const tree = lazyDocument()
    expect(
      await getTool('get_page_tree').execute(tree.figma, { root_id: tree.later.id })
    ).toMatchObject({ tree: { children: [{ name: 'Loaded button' }] } })
    const query = lazyDocument()
    expect(
      await getTool('query_nodes').execute(query.figma, { selector: '//COMPONENT', page: 'Later' })
    ).toMatchObject({ count: 1 })
    const components = lazyDocument()
    expect(await getTool('get_components').execute(components.figma, {})).toMatchObject({
      components: [{ name: 'Loaded button', page: 'Later' }]
    })
  })

  test('switch to the page asked for last, whichever loads last', async () => {
    const { graph } = setupToolTest()
    const [first] = graph.getPages()
    const slow = graph.addPage('Slow')
    const fast = graph.addPage('Fast')
    const slowLoad = Promise.withResolvers<undefined>()
    const figma = new FigmaAPI(graph, {
      loadPage: async (id) => {
        if (id === slow.id) await slowLoad.promise
      }
    })
    const slowSwitch = figma.setCurrentPageAsync(figma.wrapNode(slow.id))
    await figma.setCurrentPageAsync(figma.wrapNode(fast.id))
    slowLoad.resolve(undefined)
    await slowSwitch
    expect(figma.currentPage.id).toBe(fast.id)

    // A page set directly counts as asked for last too.
    const pending = Promise.withResolvers<undefined>()
    const later = new FigmaAPI(graph, { loadPage: () => pending.promise })
    const switching = later.setCurrentPageAsync(later.wrapNode(slow.id))
    later.currentPage = later.wrapNode(first.id)
    pending.resolve(undefined)
    await switching
    expect(later.currentPage.id).toBe(first.id)
  })

  test('refuse to switch to a page removed while it loaded', async () => {
    const { graph } = setupToolTest()
    const doomed = graph.addPage('Doomed')
    const figma = new FigmaAPI(graph, {
      loadPage: async () => {
        graph.deleteNode(doomed.id)
      }
    })
    await expect(figma.setCurrentPageAsync(figma.wrapNode(doomed.id))).rejects.toThrow(
      'removed while it loaded'
    )

    const later = graph.addPage('Later')
    const removing = new FigmaAPI(graph, {
      loadPage: async () => {
        await Promise.resolve()
        graph.deleteNode(later.id)
      }
    })
    await expect(removing.setCurrentPageAsync(removing.wrapNode(later.id))).rejects.toThrow(
      'removed while it loaded'
    )
  })

  test('load when a script or a tool switches to them', async () => {
    const { figma, later, loads } = lazyDocument()
    await getTool('switch_page').execute(figma, { page: 'Later' })
    expect(figma.currentPage.children.map((node) => node.name)).toEqual(['Loaded button'])
    await figma.loadAllPagesAsync()
    expect(loads).toContain(later.id)
  })
})

describe('page tools', () => {
  test('list_pages returns pages', () => {
    const { figma } = setupToolTest()
    const tool = getTool('list_pages')
    const result = tool.execute(figma, {}) as ListPagesResult
    expect(result.pages.length).toBeGreaterThanOrEqual(1)
  })

  test('switch_page changes page', async () => {
    const { figma } = setupToolTest()
    const page2 = figma.createPage()
    page2.name = 'Page 2'

    const tool = getTool('switch_page')
    await tool.execute(figma, { page: 'Page 2' })

    expect(figma.currentPage.name).toBe('Page 2')
  })

  test('switch_page persists across separate FigmaAPI instances (RPC simulation)', async () => {
    const { graph } = setupToolTest()
    const switchPage = getTool('switch_page')
    const getCurrentPage = getTool('get_current_page')
    const createPage = getTool('create_page')

    let currentPageId = graph.getPages()[0].id

    async function rpcCall(tool: (typeof ALL_TOOLS)[number], args: Record<string, unknown>) {
      const figma = new FigmaAPI(graph)
      figma.currentPage = figma.wrapNode(currentPageId)
      const result = await tool.execute(figma, args)
      if (figma.currentPageId !== currentPageId) {
        currentPageId = figma.currentPageId
      }
      return result
    }

    await rpcCall(createPage, { name: 'Second' })
    await rpcCall(switchPage, { page: 'Second' })
    const result = (await rpcCall(getCurrentPage, {})) as { id: string; name: string }

    expect(result.name).toBe('Second')
  })
})

describe('eval', () => {
  test('executes code with figma api', async () => {
    const { figma } = setupToolTest()
    const tool = getTool('eval')
    const result = await tool.execute(figma, {
      code: 'const r = figma.createRectangle(); r.name = "FromEval"; return r.name;'
    })
    expect(result).toBe('FromEval')
  })
})

describe('get_selection', () => {
  /** A card selected on the page, holding a row that holds a chip. */
  function selectedCard() {
    const { figma } = setupToolTest()
    const card = figma.createFrame()
    card.name = 'Card'
    const row = figma.createFrame()
    row.name = 'Row'
    card.appendChild(row)
    const chip = figma.createRectangle()
    chip.name = 'Chip'
    row.appendChild(chip)
    figma.currentPage.selection = [card]
    return figma
  }

  test('returns the selection with its direct children by default', () => {
    const result = getTool('get_selection').execute(selectedCard(), {}) as {
      selection: Array<{ name: string; children?: Array<{ name: string; childCount?: number }> }>
    }
    const [card] = result.selection
    expect(card.name).toBe('Card')
    expect(card.children?.map((child) => child.name)).toEqual(['Row'])
    expect(card.children?.[0].childCount).toBe(1)
  })

  test('takes a depth', () => {
    const tool = getTool('get_selection')
    const shallow = tool.execute(selectedCard(), { depth: 0 }) as {
      selection: Array<{ children?: unknown; childCount?: number }>
    }
    expect(shallow.selection[0].children).toBeUndefined()
    expect(shallow.selection[0].childCount).toBe(1)

    const deep = tool.execute(selectedCard(), { depth: 2 }) as {
      selection: Array<{ children: Array<{ children: Array<{ name: string }> }> }>
    }
    expect(deep.selection[0].children[0].children[0].name).toBe('Chip')
  })
})