Worker Process Execution

/**
 * Runner interface extending NodeJS EventEmitter
 * Used within worker child processes for test execution
 */
interface RunnerInterface extends NodeJS.EventEmitter {
  sigintWasCalled: boolean;
  [key: string]: unknown;
}

/**
 * Runner instance for executing tests within worker processes
 * Automatically handles command processing and framework integration
 */
const runner: RunnerInterface;

// This module is primarily used internally by @wdio/local-runner
// It's automatically imported and used by WorkerInstance

import { runner } from "@wdio/local-runner/run";

// The runner handles test execution within worker processes
// and communicates with the main process via IPC

// Listen for exit events
runner.on('exit', (code) => {
  console.log(`Test execution completed with code: ${code}`);
});

// Listen for error events  
runner.on('error', ({ name, message, stack }) => {
  console.error('Test execution error:', { name, message, stack });
});

// The runner listens for IPC messages and executes corresponding commands
// Message format follows Workers.WorkerCommand interface:
interface WorkerCommand {
  cid: string;
  command: string;
  configFile: string;
  args: Workers.WorkerMessageArgs;
  caps: WebdriverIO.Capabilities;
  specs: string[];
  retries: number;
}

// Internal integration with @wdio/runner
// - Processes test execution commands
// - Handles framework-specific operations
// - Manages browser session lifecycle
// - Reports results back to main process

// SIGINT handling
runner.sigintWasCalled = false;

// When SIGINT is received:
// 1. sigintWasCalled is set to true
// 2. Graceful exit with code 130 is initiated
// 3. Cleanup operations are performed

// Automatically sent when worker process starts
{
  name: 'ready',
  origin: 'worker'
}

// Sent after successful command execution
{
  origin: 'worker',
  name: 'finishedCommand',
  content: {
    command: string,
    result: any
  }
}

// Sent when errors occur
{
  origin: 'worker',
  name: 'error',
  content: {
    name: string,
    message: string,
    stack: string
  }
}

// 1. Worker process starts
// 2. Runner imports and initializes
// 3. 'ready' message sent to main process
// 4. Worker begins listening for commands

// 1. Receive WorkerCommand via IPC
// 2. Validate command and parameters
// 3. Execute corresponding runner method
// 4. Send 'finishedCommand' with results
// 5. Continue listening for next command

// 1. Receive shutdown signal or command
// 2. Complete current operations
// 3. Clean up resources (browser sessions, etc.)
// 4. Exit with appropriate code

// Invalid commands are ignored:
// - Missing command property
// - Non-existent runner method
// - Non-function runner method

// Failed test executions:
// 1. Log error with stack trace
// 2. Report error to main process
// 3. Exit worker process with code 1
// 4. Allow main process to handle retry logic

// SIGINT handling:
// 1. Set sigintWasCalled flag
// 2. Allow current operations to complete
// 3. Exit gracefully with code 130
// 4. Main process detects worker termination

// Outbound messages to main process:
// - ready: Worker is ready for commands
// - finishedCommand: Command execution completed
// - error: Error occurred during execution

// Inbound messages from main process:
// - WorkerCommand: Execute specific test operations
// - Configuration updates
// - Shutdown requests

// The runner delegates to @wdio/runner for:
// - Test file discovery and loading
// - Browser session management  
// - Framework-specific test execution
// - Result collection and reporting

// Async exit hooks allow cleanup operations:
// - Close browser sessions
// - Save test artifacts
// - Clean up temporary files
// - Report final status

// Uses SHUTDOWN_TIMEOUT constant (5000ms) for:
// - Graceful shutdown delay after SIGINT
// - Maximum wait time for cleanup operations
// - Preventing hanging worker processes