Skip to content

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

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

import { createAPI } from '#core-tests/helpers/figma-api'

import { headlessRenderNodes, MAX_RASTER_PIXELS } from '#core/io/formats/raster'

// Figma's answers measured in Figma desktop 126.

function refusal(run: () => unknown): string | null {
  try {
    run()
  } catch (error) {
    return error instanceof Error ? error.message : String(error)
  }
  return null
}

/** A PNG's size, from its header. */
function pngSize(data: Uint8Array | string): [number, number] {
  if (typeof data === 'string') throw new Error('expected PNG bytes')
  const view = new DataView(data.buffer, data.byteOffset, data.byteLength)
  return [view.getUint32(16), view.getUint32(20)]
}

describe('exportSettings', () => {
  test('reads each export with Figma’s defaults filled in', () => {
    const figma = createAPI()
    const rect = figma.createRectangle()
    expect(rect.exportSettings).toEqual([])
    rect.exportSettings = [
      { format: 'PNG', constraint: { type: 'SCALE', value: 2 }, suffix: '@2x' },
      { format: 'SVG', svgIdAttribute: true },
      { format: 'JPG', constraint: { type: 'HEIGHT', value: 30 }, colorProfile: 'SRGB' },
      { format: 'PDF' }
    ]
    expect(rect.exportSettings).toEqual([
      {
        format: 'PNG',
        suffix: '@2x',
        contentsOnly: true,
        colorProfile: 'DOCUMENT',
        constraint: { type: 'SCALE', value: 2 }
      },
      {
        format: 'SVG',
        suffix: '',
        contentsOnly: true,
        colorProfile: 'DOCUMENT',
        svgOutlineText: true,
        svgIdAttribute: true,
        svgSimplifyStroke: true
      },
      {
        format: 'JPG',
        suffix: '',
        contentsOnly: true,
        colorProfile: 'SRGB',
        constraint: { type: 'HEIGHT', value: 30 }
      },
      { format: 'PDF', suffix: '', contentsOnly: true, colorProfile: 'DOCUMENT' }
    ])
    expect(figma.graph.getNode(rect.id)?.exportSettings[2]).toEqual({
      scale: 1,
      format: 'jpg',
      size: { type: 'HEIGHT', value: 30 },
      colorProfile: 'SRGB'
    })
  })

  test('drops keys Figma does not know, and options its format has no use for', () => {
    const figma = createAPI()
    const rect = figma.createRectangle()
    rect.exportSettings = [
      { format: 'PNG', foo: 1 },
      { format: 'PDF', constraint: { type: 'SCALE', value: 2 } }
    ] as never
    expect(rect.exportSettings).toEqual([
      {
        format: 'PNG',
        suffix: '',
        contentsOnly: true,
        colorProfile: 'DOCUMENT',
        constraint: { type: 'SCALE', value: 1 }
      },
      { format: 'PDF', suffix: '', contentsOnly: true, colorProfile: 'DOCUMENT' }
    ])
  })

  test('leaves out exports in formats Figma has no setting for', () => {
    const figma = createAPI()
    const rect = figma.createRectangle()
    figma.graph.updateNode(rect.id, {
      exportSettings: [
        { scale: 1, format: 'webp' },
        { scale: 1, format: 'png' }
      ]
    })
    expect(rect.exportSettings.map((setting) => setting.format)).toEqual(['PNG'])
  })

  test('refuses what Figma refuses, in its words', () => {
    const figma = createAPI()
    const rect = figma.createRectangle()
    const text = figma.createText()
    const set = (value: unknown) =>
      refusal(() => {
        rect.exportSettings = value as never
      })
    const invalid = 'in set_exportSettings: Property "exportSettings" failed validation: '
    expect(set([{ format: 'WEBP' }])).toBe(
      `${invalid}Expected [0].format to be one of the following: PNG, JPG, PDF, SVG, SVG_STRING`
    )
    expect(set({ format: 'PNG' })).toBe(`${invalid}Expected array, received object`)
    expect(set([null])).toBe(`${invalid}Expected object, received null at index 0`)
    expect(set([{ format: 'PNG', suffix: 1 }])).toBe(
      `${invalid}Expected string, received number at [0].suffix`
    )
    expect(set([{ format: 'PNG', colorProfile: 'P3' }])).toBe(
      `${invalid}Invalid option: expected one of "DOCUMENT"|"SRGB"|"DISPLAY_P3_V4" at [0].colorProfile`
    )
    expect(set([{ format: 'PNG', constraint: { type: 'SCALE' } }])).toBe(
      `${invalid}Expected [0].constraint to be one of the following, but none matched:\n` +
        '  Required value missing at [0].constraint.value\n' +
        '  Multiple issues at [0].constraint:\n' +
        '    Invalid option: expected one of "WIDTH"|"HEIGHT" at [0].constraint.type\n' +
        '    Required value missing at [0].constraint.value'
    )
    expect(set([{ format: 'PNG', constraint: { type: 'WIDTH', value: 2, foo: 1 } }])).toBe(
      `${invalid}Unrecognized key: "foo" at [0].constraint`
    )
    expect(set([{ format: 'SVG_STRING' }])).toBe(
      'in set_exportSettings: Invalid value "SVG_STRING" for enum "ImageType"'
    )
    expect(set([{ format: 'PNG', useAbsoluteBounds: true }])).toBe(
      'in set_exportSettings: Cannot set useAbsoluteBounds for ExportSetting on node that is not type text.'
    )
    text.exportSettings = [{ format: 'PNG', useAbsoluteBounds: true }]
    expect(text.exportSettings[0]).toMatchObject({ useAbsoluteBounds: true })
  })

  test('pages keep exports, and the document has none', () => {
    const figma = createAPI()
    figma.currentPage.exportSettings = [{ format: 'PDF' }]
    expect(figma.currentPage.exportSettings).toHaveLength(1)
    expect('exportSettings' in figma.root).toBe(false)
    expect('exportAsync' in figma.root).toBe(false)
  })
})

describe('exportAsync', () => {
  test('refuses settings Figma refuses, in its words', async () => {
    const figma = createAPI()
    const rect = figma.createRectangle()
    const invalid = 'in exportAsync: Property "settings" failed validation: '
    await expect(rect.exportAsync({ format: 'WEBP' } as never)).rejects.toThrow(
      `${invalid}Expected .format to be one of the following: PNG, JPG, PDF, SVG, SVG_STRING, JSON_REST_V1, MP4, GIF, WEBM`
    )
    await expect(rect.exportAsync(null as never)).rejects.toThrow(
      `${invalid}Expected object, received null`
    )
    await expect(rect.exportAsync({ format: 'JSON_REST_V1', foo: 1 } as never)).rejects.toThrow(
      `${invalid}Unrecognized key: "foo"`
    )
    await expect(rect.exportAsync({ format: 'GIF' })).rejects.toThrow('Cannot export node as video')
    const gone = figma.createRectangle()
    gone.remove()
    await expect(gone.exportAsync({ format: 'SVG' })).rejects.toThrow(
      `in exportAsync: The node with id "${gone.id}" does not exist`
    )
  })

  test('writes SVG as bytes or a string, with layer names as ids on request', async () => {
    const figma = createAPI()
    const frame = figma.createFrame()
    frame.name = 'Card'
    frame.resize(60, 40)
    for (const x of [0, 20]) {
      const box = figma.createRectangle()
      box.name = 'Box'
      box.resize(10, 10)
      box.x = x
      frame.appendChild(box)
    }
    const bytes = await frame.exportAsync({ format: 'SVG' })
    expect(bytes).toBeInstanceOf(Uint8Array)
    const svg = await frame.exportAsync({ format: 'SVG_STRING', svgIdAttribute: true })
    expect(svg.startsWith('<svg')).toBe(true)
    // Layers' ids, not those of the clip paths and gradients they use.
    const layerIds = [...svg.matchAll(/<(?:g|rect|path) id="([^"]+)"/g)].map((match) => match[1])
    expect(layerIds).toEqual(['Card', 'Box', 'Box_2'])
    expect(await frame.exportAsync({ format: 'SVG_STRING' })).not.toContain(' id="Box"')
  })

  test('writes a PDF', async () => {
    const figma = createAPI()
    const pdf = await figma.createRectangle().exportAsync({ format: 'PDF' })
    expect(new TextDecoder().decode(pdf.slice(0, 5))).toBe('%PDF-')
  })

  test('sizes images by scale, width, or height, around what the layer draws', async () => {
    const figma = createAPI()
    figma.exportImage = (ids, options) =>
      headlessRenderNodes(figma.graph, options.pageId ?? figma.currentPageId, ids, options)
    const rect = figma.createRectangle()
    rect.resize(20, 10)
    rect.strokes = [{ type: 'SOLID', color: { r: 0, g: 0, b: 0 } }]
    rect.strokeWeight = 2
    rect.strokeAlign = 'OUTSIDE'
    expect(pngSize(await rect.exportAsync())).toEqual([24, 14])
    expect(pngSize(await rect.exportAsync({ format: 'PNG', useAbsoluteBounds: true }))).toEqual([
      20, 10
    ])
    const scaled = { format: 'PNG', constraint: { type: 'SCALE', value: 0.5 } } as const
    expect(pngSize(await rect.exportAsync(scaled))).toEqual([12, 7])
    const wide = { format: 'PNG', constraint: { type: 'WIDTH', value: 48 } } as const
    expect(pngSize(await rect.exportAsync(wide))).toEqual([48, 28])
    const tall = { format: 'PNG', constraint: { type: 'HEIGHT', value: 7 } } as const
    expect(pngSize(await rect.exportAsync(tall))).toEqual([12, 7])
    // Figma reads a scale of 0 as none.
    const unscaled = { format: 'PNG', constraint: { type: 'SCALE', value: 0 } } as const
    expect(pngSize(await rect.exportAsync(unscaled))).toEqual([24, 14])
    const jpg = await rect.exportAsync({ format: 'JPG' })
    expect([jpg[0], jpg[1]]).toEqual([0xff, 0xd8])
  })

  test('lays out a script’s pending edits before exporting', async () => {
    const figma = createAPI()
    const frame = figma.createFrame()
    frame.layoutMode = 'HORIZONTAL'
    frame.primaryAxisSizingMode = 'AUTO'
    frame.counterAxisSizingMode = 'AUTO'
    for (let index = 0; index < 3; index += 1) {
      const box = figma.createRectangle()
      box.resize(10, 10)
      frame.appendChild(box)
    }
    const svg = await frame.exportAsync({ format: 'SVG_STRING' })
    expect(svg).toContain('width="30"')
  })

  test('keeps every SVG id unique', async () => {
    const figma = createAPI()
    const frame = figma.createFrame()
    frame.name = 'clip0'
    frame.resize(60, 40)
    frame.clipsContent = true
    for (const name of ['Box', 'Box_2', 'Box']) {
      const box = figma.createRectangle()
      box.name = name
      box.resize(10, 10)
      frame.appendChild(box)
    }
    const unnamed = figma.createRectangle()
    unnamed.name = ''
    frame.appendChild(unnamed)
    const svg = await frame.exportAsync({ format: 'SVG_STRING', svgIdAttribute: true })
    expect(svg).not.toContain('id=""')
    const ids = [...svg.matchAll(/ id="([^"]+)"/g)].map((match) => match[1])
    expect(new Set(ids).size).toBe(ids.length)
    expect(ids).toEqual(expect.arrayContaining(['clip0', 'Box', 'Box_2', 'Box_3']))
  })

  test('sizes an SVG to the layer’s box with useAbsoluteBounds', async () => {
    const figma = createAPI()
    const rect = figma.createRectangle()
    rect.resize(20, 10)
    rect.strokes = [{ type: 'SOLID', color: { r: 0, g: 0, b: 0 } }]
    rect.strokeWeight = 2
    rect.strokeAlign = 'OUTSIDE'
    expect(await rect.exportAsync({ format: 'SVG_STRING' })).toContain('width="24"')
    const boxed = await rect.exportAsync({ format: 'SVG_STRING', useAbsoluteBounds: true })
    expect(boxed).toContain('width="20"')
  })

  test('refuses an image size past the export scale limits rather than shrinking it', async () => {
    const figma = createAPI()
    figma.exportImage = () => Promise.resolve(new Uint8Array([1]))
    const rect = figma.createRectangle()
    rect.resize(1, 1)
    const limit = "in exportAsync: An image must be exported at 0.01 to 1024 times the layer's size"
    await expect(
      rect.exportAsync({ format: 'PNG', constraint: { type: 'WIDTH', value: 2000 } })
    ).rejects.toThrow(limit)
    await expect(
      rect.exportAsync({ format: 'PNG', constraint: { type: 'SCALE', value: -1 } })
    ).rejects.toThrow(limit)
  })

  test('refuses an image too big for the renderer before drawing it', async () => {
    const figma = createAPI()
    let drawn = 0
    figma.exportImage = () => {
      drawn++
      return Promise.resolve(new Uint8Array([1]))
    }
    const rect = figma.createRectangle()
    rect.resize(10, 10)
    await expect(
      rect.exportAsync({ format: 'PNG', constraint: { type: 'SCALE', value: 1024 } })
    ).rejects.toThrow(
      `in exportAsync: An image can hold at most ${MAX_RASTER_PIXELS} pixels; this one would be 10240 by 10240`
    )
    expect(drawn).toBe(0)
    // The renderer refuses it as well, for callers that skip exportAsync.
    await expect(
      headlessRenderNodes(figma.graph, figma.currentPageId, [rect.id], {
        scale: 1024,
        format: 'PNG'
      })
    ).rejects.toThrow(`at most ${MAX_RASTER_PIXELS} pixels`)
  })

  test('says so when the host has no renderer for images', async () => {
    const figma = createAPI()
    await expect(figma.createRectangle().exportAsync()).rejects.toThrow(
      'in exportAsync: This host has no renderer to export PNG or JPG images with'
    )
  })
})