Statistics Classes

/**
 * Class describing statistics about a single test suite
 * Captures suite metadata, nested suites, tests, and hooks
 */
class SuiteStats extends RunnableStats {
  // Properties
  uid: string;
  cid?: string;
  file: string;
  title: string;
  fullTitle: string;
  tags?: string[] | Tag[];
  tests: TestStats[];
  hooks: HookStats[];
  suites: SuiteStats[];
  parent?: string;
  retries: number;
  hooksAndTests: (HookStats | TestStats)[];
  description?: string;
  rule?: string;

  /**
   * Constructor for SuiteStats
   * @param suite - Suite configuration and metadata
   */
  constructor(suite: Suite);

  /**
   * Mark suite as retried and remove previous history
   * Increments retry count and clears tests, hooks, and hooksAndTests arrays
   */
  retry(): void;
}

interface Suite {
  type?: string;
  title: string;
  parent?: string;
  fullTitle: string;
  pending?: boolean;
  file: string;
  duration?: number;
  cid?: string;
  specs?: string[];
  uid?: string;
  tags?: string[] | Tag[];
  description?: string;
  rule?: string;
  retries?: number;
}

// SuiteStats is typically created internally by WDIOReporter
// but you can access the data in event handlers
onSuiteStart(suiteStats: SuiteStats) {
  console.log(`Suite "${suiteStats.title}" started`);
  console.log(`File: ${suiteStats.file}`);
  console.log(`Parent: ${suiteStats.parent || 'root'}`);
}

/**
 * TestStats class captures data on a test execution
 * Includes state management, error handling, and output capture
 */
class TestStats extends RunnableStats {
  // Properties
  uid: string;
  cid: string;
  title: string;
  currentTest?: string;
  fullTitle: string;
  output: Output[];
  argument?: string | Argument;
  retries?: number;
  parent: string;
  state: 'pending' | 'passed' | 'skipped' | 'failed';
  pendingReason?: string;
  errors?: Error[];
  error?: Error;
  body?: string;

  /**
   * Constructor for TestStats
   * @param test - Test configuration and metadata
   */
  constructor(test: Test);

  /**
   * Mark test as passed and complete execution
   */
  pass(): void;

  /**
   * Mark test as skipped with reason
   * @param reason - Reason for skipping the test
   */
  skip(reason: string): void;

  /**
   * Mark test as failed with optional error information
   * Formats assertion errors with diff visualization
   * @param errors - Array of errors that caused the failure
   */
  fail(errors?: Error[]): void;
}

interface Output {
  command: string;
  params: unknown[];
  method: 'PUT' | 'POST' | 'GET' | 'DELETE';
  endpoint: string;
  body: {};
  result: {
    value: string | null;
  };
  sessionId: string;
  cid: string;
  type: 'command' | 'result';
}

onTestFail(testStats: TestStats) {
  console.log(`Test "${testStats.fullTitle}" failed`);
  console.log(`State: ${testStats.state}`);
  
  if (testStats.errors && testStats.errors.length > 0) {
    testStats.errors.forEach((error, index) => {
      console.log(`Error ${index + 1}: ${error.message}`);
    });
  }
  
  // Access WebDriver command output
  testStats.output.forEach(output => {
    if (output.type === 'command') {
      console.log(`Command: ${output.command}`);
    }
  });
}

/**
 * Class capturing statistics about hook execution
 * Handles hook lifecycle, timing, and error states
 */
class HookStats extends RunnableStats {
  // Properties
  uid: string;
  cid: string;
  title: string;
  parent: string;
  body?: string;
  errors?: Error[];
  error?: Error;
  state?: 'failed' | 'passed';
  currentTest?: string;

  /**
   * Constructor for HookStats
   * @param runner - Hook configuration and metadata
   */
  constructor(runner: Hook);

  /**
   * Complete hook execution with optional error information
   * Sets state to 'failed' if errors are provided
   * @param errors - Array of errors that occurred during hook execution
   */
  complete(errors?: Error[]): void;
}

interface Hook {
  type?: string;
  title: string;
  parent: string;
  fullTitle?: string;
  pending?: boolean;
  file?: string;
  body?: string;
  duration?: number;
  cid: string;
  specs?: string[];
  uid?: string;
  errors?: Error[];
  error?: Error;
  currentTest?: string;
}

/**
 * Class to capture statistics about a test run
 * A test run is a single instance that runs one or more spec files
 */
class RunnerStats extends RunnableStats {
  // Properties
  cid: string;
  capabilities: Capabilities.ResolvedTestrunnerCapabilities;
  sanitizedCapabilities: string;
  config: Options.Testrunner;
  specs: string[];
  sessionId: string;
  isMultiremote: boolean;
  instanceOptions: Record<string, Options.WebdriverIO>;
  retry?: number;
  failures?: number;
  retries?: number;
  error?: string;

  /**
   * Constructor for RunnerStats
   * @param runner - Runner configuration and metadata
   */
  constructor(runner: Options.RunnerStart);
}

onRunnerStart(runnerStats: RunnerStats) {
  console.log(`Runner ${runnerStats.cid} started`);
  console.log(`Specs: ${runnerStats.specs.join(', ')}`);
  console.log(`Capabilities: ${runnerStats.sanitizedCapabilities}`);
  console.log(`Session ID: ${runnerStats.sessionId}`);
  console.log(`Multiremote: ${runnerStats.isMultiremote}`);
}

onRunnerEnd(runnerStats: RunnerStats) {
  console.log(`Runner ${runnerStats.cid} completed`);
  console.log(`Failures: ${runnerStats.failures || 0}`);
  console.log(`Retries: ${runnerStats.retries || 0}`);
  
  if (runnerStats.error) {
    console.log(`Runner error: ${runnerStats.error}`);
  }
}

/**
 * Base class for runnable statistics (test, suite, hook, runner)
 * Provides timing and duration calculation functionality
 */
abstract class RunnableStats {
  // Properties
  start: Date;
  end?: Date;
  type: string;

  /**
   * Constructor for RunnableStats
   * @param type - Type of runnable ('test', 'suite', 'hook', 'runner')
   */
  constructor(type: string);

  /**
   * Mark the runnable as complete and calculate duration
   */
  complete(): void;

  /**
   * Get duration in milliseconds
   * Returns elapsed time if not completed, or total duration if completed
   */
  get duration(): number;

  /**
   * Get unique identifier for the runnable
   * @param runner - Hook, Suite, or Test object
   * @returns Unique identifier (uid or title)
   */
  static getIdentifier(runner: Hook | Suite | Test): string;
}

onTestEnd(testStats: TestStats) {
  console.log(`Test "${testStats.title}" took ${testStats.duration}ms`);
  console.log(`Started: ${testStats.start.toISOString()}`);
  console.log(`Ended: ${testStats.end?.toISOString()}`);
}