electron/spec/api-utility-process-spec.ts

import { systemPreferences } from 'electron';
import { BrowserWindow, MessageChannelMain, utilityProcess, app } from 'electron/main';

import { expect } from 'chai';

import * as childProcess from 'node:child_process';
import { once } from 'node:events';
import * as path from 'node:path';
import { setImmediate } from 'node:timers/promises';
import { pathToFileURL } from 'node:url';

import { ifit } from './lib/spec-helpers';
import { closeWindow } from './lib/window-helpers';

const fixturesPath = path.resolve(__dirname, 'fixtures', 'api', 'utility-process');
const isWindowsOnArm = process.platform === 'win32' && process.arch === 'arm64';
const isWindows32Bit = process.platform === 'win32' && process.arch === 'ia32';

describe('utilityProcess module', () => {
  describe('UtilityProcess constructor', () => {
    it('throws when empty script path is provided', async () => {
      expect(() => {
        utilityProcess.fork('');
      }).to.throw();
    });

    it('throws when options.stdio is not valid', async () => {
      expect(() => {
        utilityProcess.fork(path.join(fixturesPath, 'empty.js'), [], {
          execArgv: ['--test', '--test2'],
          serviceName: 'test',
          stdio: 'ipc'
        });
      }).to.throw(/stdio must be of the following values: inherit, pipe, ignore/);

      expect(() => {
        utilityProcess.fork(path.join(fixturesPath, 'empty.js'), [], {
          execArgv: ['--test', '--test2'],
          serviceName: 'test',
          stdio: ['ignore', 'ignore']
        });
      }).to.throw(/configuration missing for stdin, stdout or stderr/);

      expect(() => {
        utilityProcess.fork(path.join(fixturesPath, 'empty.js'), [], {
          execArgv: ['--test', '--test2'],
          serviceName: 'test',
          stdio: ['pipe', 'inherit', 'inherit']
        });
      }).to.throw(/stdin value other than ignore is not supported/);
    });
  });

  describe('lifecycle events', () => {
    it('emits \'spawn\' when child process successfully launches', async () => {
      const child = utilityProcess.fork(path.join(fixturesPath, 'empty.js'));
      await once(child, 'spawn');
    });

    it('emits \'exit\' when child process exits gracefully', (done) => {
      const child = utilityProcess.fork(path.join(fixturesPath, 'empty.js'));
      child.on('exit', (code) => {
        expect(code).to.equal(0);
        done();
      });
    });

    it('emits \'exit\' when the child process file does not exist', (done) => {
      const child = utilityProcess.fork('nonexistent');
      child.on('exit', (code) => {
        expect(code).to.equal(1);
        done();
      });
    });

    ifit(!isWindows32Bit)('emits the correct error code when child process exits nonzero', async () => {
      const child = utilityProcess.fork(path.join(fixturesPath, 'empty.js'));
      await once(child, 'spawn');
      const exit = once(child, 'exit');
      process.kill(child.pid!);
      const [code] = await exit;
      expect(code).to.not.equal(0);
    });

    ifit(!isWindows32Bit)('emits the correct error code when child process is killed', async () => {
      const child = utilityProcess.fork(path.join(fixturesPath, 'empty.js'));
      await once(child, 'spawn');
      const exit = once(child, 'exit');
      process.kill(child.pid!);
      const [code] = await exit;
      expect(code).to.not.equal(0);
    });

    ifit(!isWindows32Bit)('emits \'exit\' when child process crashes', async () => {
      const child = utilityProcess.fork(path.join(fixturesPath, 'crash.js'));
      // SIGSEGV code can differ across pipelines but should never be 0.
      const [code] = await once(child, 'exit');
      expect(code).to.not.equal(0);
    });

    ifit(!isWindows32Bit)('emits \'exit\' corresponding to the child process', async () => {
      const child1 = utilityProcess.fork(path.join(fixturesPath, 'endless.js'));
      await once(child1, 'spawn');
      const child2 = utilityProcess.fork(path.join(fixturesPath, 'crash.js'));
      await once(child2, 'exit');
      expect(child1.kill()).to.be.true();
      await once(child1, 'exit');
    });

    it('emits \'exit\' when there is uncaught exception', async () => {
      const child = utilityProcess.fork(path.join(fixturesPath, 'exception.js'));
      const [code] = await once(child, 'exit');
      expect(code).to.equal(1);
    });

    it('emits \'exit\' when there is uncaught exception in ESM', async () => {
      const child = utilityProcess.fork(path.join(fixturesPath, 'exception.mjs'));
      const [code] = await once(child, 'exit');
      expect(code).to.equal(1);
    });

    it('emits \'exit\' when process.exit is called', async () => {
      const exitCode = 2;
      const child = utilityProcess.fork(path.join(fixturesPath, 'custom-exit.js'), [`--exitCode=${exitCode}`]);
      const [code] = await once(child, 'exit');
      expect(code).to.equal(exitCode);
    });
  });

  describe('app \'child-process-gone\' event', () => {
    ifit(!isWindows32Bit)('with default serviceName', async () => {
      utilityProcess.fork(path.join(fixturesPath, 'crash.js'));
      const [, details] = await once(app, 'child-process-gone') as [any, Electron.Details];
      expect(details.type).to.equal('Utility');
      expect(details.serviceName).to.equal('node.mojom.NodeService');
      expect(details.name).to.equal('Node Utility Process');
      expect(details.reason).to.be.oneOf(['crashed', 'abnormal-exit']);
    });

    ifit(!isWindows32Bit)('with custom serviceName', async () => {
      utilityProcess.fork(path.join(fixturesPath, 'crash.js'), [], { serviceName: 'Hello World!' });
      const [, details] = await once(app, 'child-process-gone') as [any, Electron.Details];
      expect(details.type).to.equal('Utility');
      expect(details.serviceName).to.equal('node.mojom.NodeService');
      expect(details.name).to.equal('Hello World!');
      expect(details.reason).to.be.oneOf(['crashed', 'abnormal-exit']);
    });
  });

  describe('app.getAppMetrics()', () => {
    it('with default serviceName', async () => {
      const child = utilityProcess.fork(path.join(fixturesPath, 'endless.js'));
      await once(child, 'spawn');
      expect(child.pid).to.not.be.null();

      await setImmediate();

      const details = app.getAppMetrics().find(item => item.pid === child.pid)!;
      expect(details).to.be.an('object');
      expect(details.type).to.equal('Utility');
      expect(details.serviceName).to.to.equal('node.mojom.NodeService');
      expect(details.name).to.equal('Node Utility Process');
    });

    it('with custom serviceName', async () => {
      const child = utilityProcess.fork(path.join(fixturesPath, 'endless.js'), [], { serviceName: 'Hello World!' });
      await once(child, 'spawn');
      expect(child.pid).to.not.be.null();

      await setImmediate();

      const details = app.getAppMetrics().find(item => item.pid === child.pid)!;
      expect(details).to.be.an('object');
      expect(details.type).to.equal('Utility');
      expect(details.serviceName).to.to.equal('node.mojom.NodeService');
      expect(details.name).to.equal('Hello World!');
    });
  });

  describe('kill() API', () => {
    it('terminates the child process gracefully', async () => {
      const child = utilityProcess.fork(path.join(fixturesPath, 'endless.js'), [], {
        serviceName: 'endless'
      });
      await once(child, 'spawn');
      expect(child.kill()).to.be.true();
      await once(child, 'exit');
    });
  });

  describe('esm', () => {
    it('is launches an mjs file', async () => {
      const fixtureFile = path.join(fixturesPath, 'esm.mjs');
      const child = utilityProcess.fork(fixtureFile, [], {
        stdio: 'pipe'
      });
      await once(child, 'spawn');
      expect(child.stdout).to.not.be.null();
      let log = '';
      child.stdout!.on('data', (chunk) => {
        log += chunk.toString('utf8');
      });
      await once(child, 'exit');
      expect(log).to.equal(pathToFileURL(fixtureFile) + '\n');
    });
  });

  describe('pid property', () => {
    it('is valid when child process launches successfully', async () => {
      const child = utilityProcess.fork(path.join(fixturesPath, 'empty.js'));
      await once(child, 'spawn');
      expect(child.pid).to.not.be.null();
    });

    it('is undefined when child process fails to launch', async () => {
      const child = utilityProcess.fork(path.join(fixturesPath, 'does-not-exist.js'));
      expect(child.pid).to.be.undefined();
    });
  });

  describe('stdout property', () => {
    it('is null when child process launches with default stdio', async () => {
      const child = utilityProcess.fork(path.join(fixturesPath, 'log.js'));
      await once(child, 'spawn');
      expect(child.stdout).to.be.null();
      expect(child.stderr).to.be.null();
      await once(child, 'exit');
    });

    it('is null when child process launches with ignore stdio configuration', async () => {
      const child = utilityProcess.fork(path.join(fixturesPath, 'log.js'), [], {
        stdio: 'ignore'
      });
      await once(child, 'spawn');
      expect(child.stdout).to.be.null();
      expect(child.stderr).to.be.null();
      await once(child, 'exit');
    });

    it('is valid when child process launches with pipe stdio configuration', async () => {
      const child = utilityProcess.fork(path.join(fixturesPath, 'log.js'), [], {
        stdio: 'pipe'
      });
      await once(child, 'spawn');
      expect(child.stdout).to.not.be.null();
      let log = '';
      child.stdout!.on('data', (chunk) => {
        log += chunk.toString('utf8');
      });
      await once(child, 'exit');
      expect(log).to.equal('hello\n');
    });
  });

  describe('stderr property', () => {
    it('is null when child process launches with default stdio', async () => {
      const child = utilityProcess.fork(path.join(fixturesPath, 'log.js'));
      await once(child, 'spawn');
      expect(child.stdout).to.be.null();
      expect(child.stderr).to.be.null();
      await once(child, 'exit');
    });

    it('is null when child process launches with ignore stdio configuration', async () => {
      const child = utilityProcess.fork(path.join(fixturesPath, 'log.js'), [], {
        stdio: 'ignore'
      });
      await once(child, 'spawn');
      expect(child.stderr).to.be.null();
      await once(child, 'exit');
    });

    ifit(!isWindowsOnArm)('is valid when child process launches with pipe stdio configuration', async () => {
      const child = utilityProcess.fork(path.join(fixturesPath, 'log.js'), [], {
        stdio: ['ignore', 'pipe', 'pipe']
      });
      await once(child, 'spawn');
      expect(child.stderr).to.not.be.null();
      let log = '';
      child.stderr!.on('data', (chunk) => {
        log += chunk.toString('utf8');
      });
      await once(child, 'exit');
      expect(log).to.equal('world');
    });
  });

  describe('postMessage() API', () => {
    it('establishes a default ipc channel with the child process', async () => {
      const result = 'I will be echoed.';
      const child = utilityProcess.fork(path.join(fixturesPath, 'post-message.js'));
      await once(child, 'spawn');
      child.postMessage(result);
      const [data] = await once(child, 'message');
      expect(data).to.equal(result);
      const exit = once(child, 'exit');
      expect(child.kill()).to.be.true();
      await exit;
    });

    it('supports queuing messages on the receiving end', async () => {
      const child = utilityProcess.fork(path.join(fixturesPath, 'post-message-queue.js'));
      const p = once(child, 'spawn');
      child.postMessage('This message');
      child.postMessage(' is');
      child.postMessage(' queued');
      await p;
      const [data] = await once(child, 'message');
      expect(data).to.equal('This message is queued');
      const exit = once(child, 'exit');
      expect(child.kill()).to.be.true();
      await exit;
    });

    it('handles the parent port trying to send an non-clonable object', async () => {
      const child = utilityProcess.fork(path.join(fixturesPath, 'non-cloneable.js'));
      await once(child, 'spawn');
      child.postMessage('non-cloneable');
      const [data] = await once(child, 'message');
      expect(data).to.equal('caught-non-cloneable');
      const exit = once(child, 'exit');
      expect(child.kill()).to.be.true();
      await exit;
    });
  });

  describe('behavior', () => {
    it('supports starting the v8 inspector with --inspect-brk', (done) => {
      const child = utilityProcess.fork(path.join(fixturesPath, 'log.js'), [], {
        stdio: 'pipe',
        execArgv: ['--inspect-brk']
      });

      let output = '';
      const cleanup = () => {
        child.stderr!.removeListener('data', listener);
        child.stdout!.removeListener('data', listener);
        child.once('exit', () => { done(); });
        child.kill();
      };

      const listener = (data: Buffer) => {
        output += data;
        if (/Debugger listening on ws:/m.test(output)) {
          cleanup();
        }
      };

      child.stderr!.on('data', listener);
      child.stdout!.on('data', listener);
    });

    it('supports starting the v8 inspector with --inspect and a provided port', (done) => {
      const child = utilityProcess.fork(path.join(fixturesPath, 'log.js'), [], {
        stdio: 'pipe',
        execArgv: ['--inspect=17364']
      });

      let output = '';
      const cleanup = () => {
        child.stderr!.removeListener('data', listener);
        child.stdout!.removeListener('data', listener);
        child.once('exit', () => { done(); });
        child.kill();
      };

      const listener = (data: Buffer) => {
        output += data;
        if (/Debugger listening on ws:/m.test(output)) {
          expect(output.trim()).to.contain(':17364', 'should be listening on port 17364');
          cleanup();
        }
      };

      child.stderr!.on('data', listener);
      child.stdout!.on('data', listener);
    });

    it('supports changing dns verbatim with --dns-result-order', (done) => {
      const child = utilityProcess.fork(path.join(fixturesPath, 'dns-result-order.js'), [], {
        stdio: 'pipe',
        execArgv: ['--dns-result-order=ipv4first']
      });

      let output = '';
      const cleanup = () => {
        child.stderr!.removeListener('data', listener);
        child.stdout!.removeListener('data', listener);
        child.once('exit', () => { done(); });
        child.kill();
      };

      const listener = (data: Buffer) => {
        output += data;
        expect(output.trim()).to.contain('ipv4first', 'default verbatim should be ipv4first');
        cleanup();
      };

      child.stderr!.on('data', listener);
      child.stdout!.on('data', listener);
    });

    ifit(process.platform !== 'win32')('supports redirecting stdout to parent process', async () => {
      const result = 'Output from utility process';
      const appProcess = childProcess.spawn(process.execPath, [path.join(fixturesPath, 'inherit-stdout'), `--payload=${result}`]);
      let output = '';
      appProcess.stdout.on('data', (data: Buffer) => { output += data; });
      await once(appProcess, 'exit');
      expect(output).to.equal(result);
    });

    ifit(process.platform !== 'win32')('supports redirecting stderr to parent process', async () => {
      const result = 'Error from utility process';
      const appProcess = childProcess.spawn(process.execPath, [path.join(fixturesPath, 'inherit-stderr'), `--payload=${result}`]);
      let output = '';
      appProcess.stderr.on('data', (data: Buffer) => { output += data; });
      await once(appProcess, 'exit');
      expect(output).to.include(result);
    });

    ifit(process.platform !== 'linux')('can access exposed main process modules from the utility process', async () => {
      const message = 'Message from utility process';
      const child = utilityProcess.fork(path.join(fixturesPath, 'expose-main-process-module.js'));
      await once(child, 'spawn');
      child.postMessage(message);
      const [data] = await once(child, 'message');
      expect(data).to.equal(systemPreferences.getMediaAccessStatus('screen'));
      const exit = once(child, 'exit');
      expect(child.kill()).to.be.true();
      await exit;
    });

    it('can establish communication channel with sandboxed renderer', async () => {
      const result = 'Message from sandboxed renderer';
      const w = new BrowserWindow({
        show: false,
        webPreferences: {
          preload: path.join(fixturesPath, 'preload.js')
        }
      });
      await w.loadFile(path.join(__dirname, 'fixtures', 'blank.html'));
      // Create Message port pair for Renderer <-> Utility Process.
      const { port1: rendererPort, port2: childPort1 } = new MessageChannelMain();
      w.webContents.postMessage('port', result, [rendererPort]);
      // Send renderer and main channel port to utility process.
      const child = utilityProcess.fork(path.join(fixturesPath, 'receive-message.js'));
      await once(child, 'spawn');
      child.postMessage('', [childPort1]);
      const [data] = await once(child, 'message');
      expect(data).to.equal(result);
      // Cleanup.
      const exit = once(child, 'exit');
      expect(child.kill()).to.be.true();
      await exit;
      await closeWindow(w);
    });

    ifit(process.platform === 'linux')('allows executing a setuid binary with child_process', async () => {
      const child = utilityProcess.fork(path.join(fixturesPath, 'suid.js'));
      await once(child, 'spawn');
      const [data] = await once(child, 'message');
      expect(data).to.not.be.empty();
      const exit = once(child, 'exit');
      expect(child.kill()).to.be.true();
      await exit;
    });

    it('inherits parent env as default', async () => {
      const appProcess = childProcess.spawn(process.execPath, [path.join(fixturesPath, 'env-app')], {
        env: {
          FROM: 'parent',
          ...process.env
        }
      });
      let output = '';
      appProcess.stdout.on('data', (data: Buffer) => { output += data; });
      await once(appProcess.stdout, 'end');
      const result = process.platform === 'win32' ? '\r\nparent' : 'parent';
      expect(output).to.equal(result);
    });

    it('does not inherit parent env when custom env is provided', async () => {
      const appProcess = childProcess.spawn(process.execPath, [path.join(fixturesPath, 'env-app'), '--create-custom-env'], {
        env: {
          FROM: 'parent',
          ...process.env
        }
      });
      let output = '';
      appProcess.stdout.on('data', (data: Buffer) => { output += data; });
      await once(appProcess.stdout, 'end');
      const result = process.platform === 'win32' ? '\r\nchild' : 'child';
      expect(output).to.equal(result);
    });

    it('changes working directory with cwd', async () => {
      const child = utilityProcess.fork('./log.js', [], {
        cwd: fixturesPath,
        stdio: ['ignore', 'pipe', 'ignore']
      });
      await once(child, 'spawn');
      expect(child.stdout).to.not.be.null();
      let log = '';
      child.stdout!.on('data', (chunk) => {
        log += chunk.toString('utf8');
      });
      await once(child, 'exit');
      expect(log).to.equal('hello\n');
    });

    it('does not crash when running eval', async () => {
      const child = utilityProcess.fork('./eval.js', [], {
        cwd: fixturesPath,
        stdio: 'ignore'
      });
      await once(child, 'spawn');
      const [data] = await once(child, 'message');
      expect(data).to.equal(42);
      // Cleanup.
      const exit = once(child, 'exit');
      expect(child.kill()).to.be.true();
      await exit;
    });
  });
});