Programmatic API

/**
 * Main entry point module for programmatic usage
 * Parses command line arguments and executes test runner
 */
const main: {
  /**
   * Main entry point function for programmatic usage
   * @param argv - Command line arguments array, defaults to process.argv.slice(2)
   */
  main(argv?: string[]): void;
};

const { main } = require('electron-mocha/lib/main');

// Run with default arguments (process.argv.slice(2))
main.main();

// Run with custom arguments
main.main(['--renderer', '--timeout', '5000', 'test/**/*.js']);

// Run with programmatic configuration
main.main([
  '--renderer',
  '--require-main', './test/setup.js',
  '--reporter', 'json',
  'test/renderer/'
]);

/**
 * Test execution handler with parsed options
 * @param argv - Parsed command line options object
 * @returns Promise that resolves when tests complete
 */
async function handler(argv: ElectronMochaOptions): Promise<void>;

const { handler } = require('electron-mocha/lib/run');

// Execute main process tests
await handler({
  spec: ['test/main/**/*.js'],
  reporter: 'spec',
  timeout: 5000,
  'require-main': ['./test/setup.js']
});

// Execute renderer process tests
await handler({
  spec: ['test/renderer/**/*.js'],
  renderer: true,
  interactive: false,
  'show-window': false,
  preload: './test/preload.js'
});

/**
 * Mocha module exports
 */
const mocha: {
  Mocha: typeof import('mocha');
  ONE_AND_DONES: Record<string, Function>;
  errors: typeof import('mocha/lib/errors');
  helpers: {
    /**
     * Handle require statements for renderer/main process modules
     * @param mods - Array of module paths to require
     */
    handleRequires(mods: string[]): Promise<void>;
    
    /**
     * Handle require statements for main process modules (legacy)
     * @param mods - Array of module paths to require
     */
    handleLegacyRequires(mods: string[]): Promise<void>;
    
    /**
     * Execute Mocha test suite with Electron-specific configuration
     * @param argv - Test configuration options
     * @param done - Callback function called when tests complete
     */
    runMocha(argv: ElectronMochaOptions, done: (failures: number) => void): Promise<void>;
  };
};

const { helpers } = require('electron-mocha/lib/mocha');

// Custom test execution with callback
await helpers.runMocha({
  spec: ['test/**/*.js'],
  reporter: 'json',
  renderer: true
}, (failures) => {
  console.log(`Tests completed with ${failures} failures`);
  process.exit(failures > 0 ? 1 : 0);
});

// Load setup modules before tests
await helpers.handleLegacyRequires(['./test/setup.js', './test/mocks.js']);

// Access Mocha class directly
const { Mocha } = require('electron-mocha/lib/mocha');
const mocha = new Mocha({ reporter: 'spec', timeout: 5000 });

interface ElectronMochaOptions {
  // Test files and patterns
  spec?: string[];
  file?: string[];
  ignore?: string[];
  extension?: string[];
  
  // Electron-specific options
  renderer?: boolean;
  'require-main'?: string[];
  script?: string[];
  interactive?: boolean;
  url?: string;
  preload?: string;
  'window-config'?: string;
  warnings?: boolean;
  'show-window'?: boolean;
  inspect?: boolean | number;
  
  // Standard Mocha options
  reporter?: string;
  'reporter-option'?: string[];
  grep?: string;
  invert?: boolean;
  timeout?: number;
  recursive?: boolean;
  watch?: boolean;
  'watch-files'?: string[];
  'watch-ignore'?: string[];
  config?: string;
  require?: string[];
  exit?: boolean;
  bail?: boolean;
  slow?: number;
  color?: boolean;
  'full-trace'?: boolean;
  'inline-diffs'?: boolean;
  'check-leaks'?: boolean;
  'forbid-only'?: boolean;
  'forbid-pending'?: boolean;
  'global'?: string[];
  retries?: number;
  'dry-run'?: boolean;
  'allow-uncaught'?: boolean;
}

interface WindowConfig {
  // Window dimensions
  width?: number;
  height?: number;
  x?: number;
  y?: number;
  
  // Window behavior
  show?: boolean;
  focusable?: boolean;
  resizable?: boolean;
  minimizable?: boolean;
  maximizable?: boolean;
  closable?: boolean;
  
  // Web preferences
  webPreferences?: {
    nodeIntegration?: boolean;
    contextIsolation?: boolean;
    enableRemoteModule?: boolean;
    preload?: string;
    sandbox?: boolean;
    webSecurity?: boolean;
    allowRunningInsecureContent?: boolean;
    experimentalFeatures?: boolean;
  };
  
  // All other BrowserWindow options supported
}

// Custom window configuration file (window-config.json)
{
  "width": 1024,
  "height": 768,
  "show": false,
  "webPreferences": {
    "nodeIntegration": true,
    "contextIsolation": false,
    "webSecurity": false
  }
}

// Using custom window config
await handler({
  renderer: true,
  'window-config': './test/window-config.json',
  spec: ['test/renderer/**/*.js']
});

try {
  await handler({
    renderer: true,
    spec: ['test/**/*.js']
  });
} catch (error) {
  console.error('Test execution failed:', error.message);
  if (error.stack) {
    console.error(error.stack);
  }
  process.exit(1);
}

// Gulp integration
const gulp = require('gulp');
const { main } = require('electron-mocha/lib/main');

gulp.task('test:main', (done) => {
  main.main(['--reporter', 'spec', 'test/main/**/*.js']);
  done();
});

gulp.task('test:renderer', (done) => {
  main.main(['--renderer', '--reporter', 'json', 'test/renderer/**/*.js']);
  done();
});

// Webpack plugin integration
class ElectronMochaPlugin {
  apply(compiler) {
    compiler.hooks.done.tap('ElectronMochaPlugin', () => {
      main.main(['--renderer', 'test/**/*.js']);
    });
  }
}

// Jest integration (custom test runner)
const { handler } = require('electron-mocha/lib/run');

module.exports = async (globalConfig, runnerConfig) => {
  await handler({
    renderer: true,
    spec: runnerConfig.testPathPattern,
    reporter: 'json'
  });
};

// TypeScript configuration
await handler({
  require: ['ts-node/register'],
  spec: ['test/**/*.ts'],
  renderer: true,
  extension: ['ts']
});

// With custom TypeScript config
await handler({
  'require-main': ['ts-node/register/transpile-only'],
  spec: ['test/**/*.spec.ts'],
  extension: ['ts'],
  'ts-config': './test/tsconfig.json'
});