electron/spec/api-desktop-capturer.spec.ts

import { screen, desktopCapturer, BrowserWindow } from 'electron/main';

import { afterAll, beforeAll, describe, expect, it } from 'vitest';

import { once } from 'node:events';
import { setTimeout } from 'node:timers/promises';

import { ifdescribe, ifit, isWayland } from './lib/spec-helpers.ts';
import { closeAllWindows } from './lib/window-helpers.ts';

function getSourceTypes(): ('window' | 'screen')[] {
  if (process.platform === 'linux') {
    return ['screen'];
  }
  return ['window', 'screen'];
}

describe('desktopCapturer', { tags: ['serial'] }, () => {
  it('should return a non-empty array of sources', async () => {
    const sources = await desktopCapturer.getSources({ types: getSourceTypes() });
    expect(sources).toBeInstanceOf(Array);
    expect(sources).not.toHaveLength(0);
  });

  it('throws an error for invalid options', async () => {
    const promise = desktopCapturer.getSources(['window', 'screen'] as any);
    await expect(promise).rejects.toThrow('Invalid options');
  });

  it('throws an error for an unknown persistMode', async () => {
    const promise = desktopCapturer.getSources({ types: getSourceTypes(), persistMode: 'forever' as any });
    await expect(promise).rejects.toThrow('Invalid options');
  });

  it('throws an error for a non-string restoreToken', async () => {
    const promise = desktopCapturer.getSources({ types: getSourceTypes(), restoreToken: 42 as any });
    await expect(promise).rejects.toThrow('Invalid options');
  });

  it('accepts persistMode and restoreToken and returns a restoreToken for each source', async () => {
    const sources = await desktopCapturer.getSources({
      types: getSourceTypes(),
      thumbnailSize: { width: 0, height: 0 },
      persistMode: 'transient',
      restoreToken: ''
    });
    expect(sources).toBeInstanceOf(Array);
    expect(sources).not.toHaveLength(0);
    for (const source of sources) {
      expect(source.restoreToken).toBeTypeOf('string');
      if (!isWayland) expect(source.restoreToken).toBe('');
    }
  });

  it('throws when restoreToken is passed without persistMode', async () => {
    const promise = desktopCapturer.getSources({ types: getSourceTypes(), restoreToken: 'token' });
    await expect(promise).rejects.toThrow('Invalid options');
  });

  it('getRestoreToken returns an empty string for a source that has no token', () => {
    expect(desktopCapturer.getRestoreToken('window:0:0')).toBe('');
    expect(desktopCapturer.getRestoreToken('not-a-source-id')).toBe('');
  });

  it('getRestoreToken returns the restoreToken of a returned source', async () => {
    const sources = await desktopCapturer.getSources({
      types: getSourceTypes(),
      thumbnailSize: { width: 0, height: 0 }
    });
    expect(sources).toBeInstanceOf(Array);
    expect(sources).not.toHaveLength(0);
    for (const source of sources) {
      expect(desktopCapturer.getRestoreToken(source.id)).toBe(source.restoreToken);
    }
  });

  it('does not throw an error when called more than once (regression)', async () => {
    const sources1 = await desktopCapturer.getSources({ types: getSourceTypes() });
    expect(sources1).toBeInstanceOf(Array);
    expect(sources1).not.toHaveLength(0);

    const sources2 = await desktopCapturer.getSources({ types: getSourceTypes() });
    expect(sources2).toBeInstanceOf(Array);
    expect(sources2).not.toHaveLength(0);
  });

  // Linux doesn't return any window sources.
  ifit(process.platform !== 'linux')('responds to subsequent calls of different options', async () => {
    const promise1 = desktopCapturer.getSources({ types: ['window'] });
    await promise1;

    const promise2 = desktopCapturer.getSources({ types: ['screen'] });
    await promise2;
  });

  // Linux doesn't return any window sources.
  ifit(process.platform !== 'linux')('returns an empty display_id for window sources', async () => {
    const w2 = new BrowserWindow({ width: 200, height: 200 });
    await w2.loadURL('about:blank');

    const sources = await desktopCapturer.getSources({ types: ['window'] });
    w2.destroy();
    expect(sources).toBeInstanceOf(Array);
    expect(sources).not.toHaveLength(0);
    for (const { display_id: displayId } of sources) {
      expect(displayId).toBeTypeOf('string');
      expect(displayId).toHaveLength(0);
    }
  });

  ifit(process.platform !== 'linux')('returns display_ids matching the Screen API', async () => {
    const displays = screen.getAllDisplays();
    const sources = await desktopCapturer.getSources({ types: ['screen'] });
    expect(sources).toBeInstanceOf(Array);
    expect(sources).toHaveLength(displays.length);

    for (const [i, source] of sources.entries()) {
      expect(source.display_id).toBe(displays[i].id.toString());
    }
  });

  it('enabling thumbnail should return non-empty images', async () => {
    const w2 = new BrowserWindow({ show: false, width: 200, height: 200, webPreferences: { contextIsolation: false } });
    const wShown = once(w2, 'show');
    w2.show();
    await wShown;

    const isNonEmpties: boolean[] = (
      await desktopCapturer.getSources({
        types: getSourceTypes(),
        thumbnailSize: { width: 100, height: 100 }
      })
    ).map((s) => s.thumbnail.constructor.name === 'NativeImage' && !s.thumbnail.isEmpty());

    w2.destroy();
    expect(isNonEmpties).toBeInstanceOf(Array);
    expect(isNonEmpties).not.toHaveLength(0);
    expect(isNonEmpties.every((e) => e === true)).toBe(true);
  });

  it('disabling thumbnail should return empty images', async () => {
    const w2 = new BrowserWindow({ show: false, width: 200, height: 200, webPreferences: { contextIsolation: false } });
    const wShown = once(w2, 'show');
    w2.show();
    await wShown;

    const isEmpties: boolean[] = (
      await desktopCapturer.getSources({
        types: getSourceTypes(),
        thumbnailSize: { width: 0, height: 0 }
      })
    ).map((s) => s.thumbnail.constructor.name === 'NativeImage' && s.thumbnail.isEmpty());

    w2.destroy();
    expect(isEmpties).toBeInstanceOf(Array);
    expect(isEmpties).not.toHaveLength(0);
    expect(isEmpties.every((e) => e === true)).toBe(true);
  });

  // Linux doesn't return any window sources.
  ifit(process.platform !== 'linux')('getMediaSourceId should match DesktopCapturerSource.id', async () => {
    const w2 = new BrowserWindow({ show: false, width: 100, height: 100, webPreferences: { contextIsolation: false } });
    const wShown = once(w2, 'show');
    const wFocused = once(w2, 'focus');
    w2.show();
    w2.focus();
    await wShown;
    await wFocused;

    const mediaSourceId = w2.getMediaSourceId();
    const sources = await desktopCapturer.getSources({
      types: ['window'],
      thumbnailSize: { width: 0, height: 0 }
    });
    w2.destroy();

    expect(sources).toBeInstanceOf(Array);
    expect(sources).not.toHaveLength(0);
    const foundSource = sources.find((source) => {
      return source.id === mediaSourceId;
    });
    expect(mediaSourceId).toBe(foundSource!.id);
  });

  // Linux doesn't return any window sources.
  ifit(process.platform !== 'linux')('getSources should not incorrectly duplicate window_id', async () => {
    const w2 = new BrowserWindow({ show: false, width: 100, height: 100, webPreferences: { contextIsolation: false } });
    const wShown = once(w2, 'show');
    const wFocused = once(w2, 'focus');
    w2.show();
    w2.focus();
    await wShown;
    await wFocused;

    // ensure window_id isn't duplicated in getMediaSourceId,
    // which uses a different method than getSources
    const mediaSourceId = w2.getMediaSourceId();
    const ids = mediaSourceId.split(':');
    expect(ids[1]).not.toBe(ids[2]);

    const sources = await desktopCapturer.getSources({
      types: ['window'],
      thumbnailSize: { width: 0, height: 0 }
    });
    w2.destroy();

    expect(sources).toBeInstanceOf(Array);
    expect(sources).not.toHaveLength(0);
    for (const source of sources) {
      const sourceIds = source.id.split(':');
      expect(sourceIds[1]).not.toBe(sourceIds[2]);
    }
  });

  // Regression test - see https://github.com/electron/electron/issues/43002
  it('does not affect window resizable state', async () => {
    const w = new BrowserWindow({ show: false, webPreferences: { nodeIntegration: true, contextIsolation: false } });
    await w.loadURL('about:blank');
    w.resizable = false;

    const wShown = once(w, 'show');
    w.show();
    await wShown;

    const sources = await desktopCapturer.getSources({ types: getSourceTypes() });
    expect(sources).toBeInstanceOf(Array);
    expect(sources).not.toHaveLength(0);

    expect(w.resizable).toBe(false);
    await closeAllWindows();
  });

  // Linux doesn't return any window sources.
  ifit(process.platform !== 'linux')('moveAbove should move the window at the requested place', async () => {
    // DesktopCapturer.getSources() is guaranteed to return in the correct
    // z-order from foreground to background.
    const MAX_WIN = 4;
    const wList: BrowserWindow[] = [];

    const destroyWindows = () => {
      for (const w of wList) {
        w.destroy();
      }
    };

    try {
      for (let i = 0; i < MAX_WIN; i++) {
        const w = new BrowserWindow({ show: false, width: 100, height: 100 });
        wList.push(w);
      }
      expect(wList.length).toBe(MAX_WIN);

      // Show and focus all the windows.
      for (const w of wList) {
        const wShown = once(w, 'show');
        const wFocused = once(w, 'focus');

        w.show();
        w.focus();

        await wShown;
        await wFocused;
      }

      // At this point our windows should be showing from bottom to top.

      // DesktopCapturer.getSources() returns sources sorted from foreground to
      // background, i.e. top to bottom.
      let sources = await desktopCapturer.getSources({
        types: ['window'],
        thumbnailSize: { width: 0, height: 0 }
      });

      expect(sources).toBeInstanceOf(Array);
      expect(sources).not.toHaveLength(0);
      expect(sources.length).toBeGreaterThanOrEqual(MAX_WIN);

      // Only keep our windows, they must be in the MAX_WIN first windows.
      sources.splice(MAX_WIN, sources.length - MAX_WIN);
      expect(sources.length).toBe(MAX_WIN);
      expect(sources.length).toBe(wList.length);

      // Check that the sources and wList are sorted in the reverse order.
      // If they're not, skip remaining checks because either focus or
      // window placement are not reliable in the running test environment.
      const wListReversed = wList.slice().reverse();
      const proceed = sources.every((source, index) => source.id === wListReversed[index].getMediaSourceId());
      if (!proceed) return;

      // Move windows so wList is sorted from foreground to background.
      for (const [i, w] of wList.entries()) {
        if (i < wList.length - 1) {
          const next = wList[wList.length - 1];
          w.focus();
          w.moveAbove(next.getMediaSourceId());
          // Ensure the window has time to move.
          await setTimeout(2000);
        }
      }

      sources = await desktopCapturer.getSources({
        types: ['window'],
        thumbnailSize: { width: 0, height: 0 }
      });

      sources.splice(MAX_WIN, sources.length);
      expect(sources.length).toBe(MAX_WIN);
      expect(sources.length).toBe(wList.length);

      // Check that the sources and wList are sorted in the same order.
      for (const [index, source] of sources.entries()) {
        const wID = wList[index].getMediaSourceId();
        expect(source.id).toBe(wID);
      }
    } finally {
      destroyWindows();
    }
  });

  // Linux doesn't return any window sources.
  // Tests are sequentially dependent.
  ifdescribe(process.platform !== 'linux')('fetchWindowIcons', () => {
    let w: BrowserWindow;
    let testSource: Electron.DesktopCapturerSource | undefined;
    let appIcon: Electron.NativeImage | undefined;

    beforeAll(async () => {
      w = new BrowserWindow({
        width: 200,
        height: 200,
        show: true,
        title: 'desktop-capturer-test-window'
      });
      await w.loadURL('about:blank');
      const sources = await desktopCapturer.getSources({
        types: ['window'],
        fetchWindowIcons: true
      });
      testSource = sources.find((s) => s.name === 'desktop-capturer-test-window');
      appIcon = testSource?.appIcon;
    });

    afterAll(() => {
      if (w) w.destroy();
    });

    it('should find the test window in the list of captured sources', () => {
      expect(testSource, `The ${w.getTitle()} window was not found by desktopCapturer`).toEqual(expect.anything());
    });

    it('should return a non-null appIcon for the captured window', () => {
      expect(appIcon, 'appIcon property is null or undefined').toEqual(expect.anything());
    });

    it('should return an appIcon that is not an empty image', () => {
      expect(appIcon?.isEmpty()).toBe(false);
    });

    it('should return an appIcon that encodes to a valid PNG data URL', () => {
      const url = appIcon?.toDataURL();
      expect(url).toBeTypeOf('string');
      // This is header 'data:image/png;base64,' length;
      expect(url?.length).toBeGreaterThan(22);
      expect(url?.startsWith('data:image/png;base64,')).toBe(true);
    });

    it('should return an appIcon with dimensions greater than 0x0 pixels', () => {
      const { width, height } = appIcon?.getSize() || { width: 0, height: 0 };
      expect(width).toBeGreaterThan(0);
      expect(height).toBeGreaterThan(0);
    });
  });
});