Report Formatting

/**
 * Print complete test report to stdout
 * Generates formatted output including headers, results, counts, and failures
 * @param runner - Runner statistics containing test results and configuration
 */
printReport(runner: RunnerStats): void;

import SpecReporter from "@wdio/spec-reporter";

// Automatic usage in WebdriverIO
// The reporter automatically calls printReport() when tests complete

// Manual usage
const reporter = new SpecReporter({});
reporter.onRunnerEnd(runnerStats); // Calls printReport internally

// Output format:
// ------------------------------------------------------------------
// [chrome 91 macOS Big Sur #0-0] Running: chrome (v91) on macOS Big Sur  
// [chrome 91 macOS Big Sur #0-0] Session ID: abc123
// [chrome 91 macOS Big Sur #0-0]
// [chrome 91 macOS Big Sur #0-0] » /tests/example.test.js
// [chrome 91 macOS Big Sur #0-0] Example Test Suite
// [chrome 91 macOS Big Sur #0-0]    ✓ should pass
// [chrome 91 macOS Big Sur #0-0]    ✗ should fail
// [chrome 91 macOS Big Sur #0-0]
// [chrome 91 macOS Big Sur #0-0] 1 passing (2s)
// [chrome 91 macOS Big Sur #0-0] 1 failing

/**
 * Apply color formatting to messages based on state
 * @param message - Text message to colorize
 * @param state - Test state determining color (passed, failed, skipped, etc.)
 * @returns Colorized message string
 */
setMessageColor(message: string, state?: State): string;

const reporter = new SpecReporter({ color: true });

// Color by state
const passedMsg = reporter.setMessageColor('Test passed', State.PASSED);
// Returns: 'green Test passed'

const failedMsg = reporter.setMessageColor('Test failed', State.FAILED);  
// Returns: 'red Test failed'

const skippedMsg = reporter.setMessageColor('Test skipped', State.SKIPPED);
// Returns: 'cyan Test skipped'

// Without color
const noColorReporter = new SpecReporter({ color: false });
const plainMsg = noColorReporter.setMessageColor('Test message', State.PASSED);
// Returns: 'Test message'

/**
 * Generate formatted test results display
 * Creates hierarchical output showing suites, tests, and status
 * @param prefaceString - Optional prefix for each output line
 * @returns Array of formatted result lines
 */
getResultDisplay(prefaceString?: string): string[];

const reporter = new SpecReporter({});

// Get formatted results
const results = reporter.getResultDisplay();
// Returns array like:
// [
//   "» /tests/example.test.js",
//   "Example Test Suite", 
//   "   ✓ should pass",
//   "   ✗ should fail",
//   ""
// ]

// With preface
const resultsWithPreface = reporter.getResultDisplay("[chrome #0-0]");
// Each line prefixed: "[chrome #0-0] » /tests/example.test.js"

/**
 * Generate formatted test count summary
 * Shows counts of passed, failed, skipped, pending, and retried tests
 * @param duration - Test execution duration string
 * @returns Array of formatted count summary lines
 */
getCountDisplay(duration: string): string[];

const reporter = new SpecReporter({});

// Generate count summary
const counts = reporter.getCountDisplay('(2.5s)');
// Returns array like:
// [
//   "green 5 passing (2.5s)",
//   "red 2 failing", 
//   "cyan 1 skipped"
// ]

// Only showing relevant counts:
// - If only passing tests: ["green 5 passing (2.5s)"]
// - If only failures: ["red 2 failing (2.5s)"]
// - Mixed results show all non-zero counts

/**
 * Generate detailed failure display with stack traces
 * Shows error messages and stack traces for all failed tests
 * @returns Array of formatted failure detail lines
 */
getFailureDisplay(): string[];

const reporter = new SpecReporter({});

// Generate failure details
const failures = reporter.getFailureDisplay();
// Returns array like:
// [
//   "",
//   "1) Login Suite should authenticate user",
//   "red Expected login to succeed but got error",
//   "gray   at Object.test (/tests/login.test.js:25:5)",
//   "gray   at runTest (/node_modules/...)",
//   "",
//   "2) Login Suite should validate password", 
//   "red Password validation failed",
//   "gray   at Object.validate (/tests/login.test.js:40:10)"
// ]

/**
 * Get formatted header display for the test report
 * Shows browser/environment information and session details
 * @param runner - Runner statistics and configuration
 * @returns Array of formatted header lines
 */
getHeaderDisplay(runner: RunnerStats): string[];

const reporter = new SpecReporter({});

// Generate header information
const header = reporter.getHeaderDisplay(runnerStats);
// Returns array like:
// [
//   "Running: chrome (v91) on macOS Big Sur",
//   "Session ID: abc123def456"
// ]

// For mobile:
// [
//   "Running: iPhone 12 on iOS 14.5 executing Safari"
// ]

// For multiremote:
// [
//   "Running: MultiremoteBrowser on chrome, firefox"
// ]

/**
 * Get symbol for a specific test state
 * @param state - Test state (passed, failed, skipped, etc.)
 * @returns Symbol string for the state
 */
getSymbol(state?: keyof Symbols): string;

/**
 * Get color name for a specific test state  
 * @param state - Test state string
 * @returns Color name for terminal formatting
 */
getColor(state?: string): ChalkColors;

const reporter = new SpecReporter({
  symbols: {
    passed: '✅',
    failed: '❌', 
    skipped: '⏭️'
  }
});

// Get symbols
const passSymbol = reporter.getSymbol('passed'); // '✅'
const failSymbol = reporter.getSymbol('failed'); // '❌'
const unknownSymbol = reporter.getSymbol(); // '?'

// Get colors
const passColor = reporter.getColor('passed'); // 'green'
const failColor = reporter.getColor('failed'); // 'red'
const skipColor = reporter.getColor('skipped'); // 'cyan'

/**
 * Format browser and environment combination information
 * @param capability - Browser capabilities object
 * @param verbose - Whether to use verbose formatting (default: true)
 * @param isMultiremote - Whether using multiremote setup (default: false)
 * @returns Formatted environment string
 */
getEnviromentCombo(
  capability: Capabilities.ResolvedTestrunnerCapabilities,
  verbose?: boolean,
  isMultiremote?: boolean
): string;

const reporter = new SpecReporter({});

// Desktop browser - verbose
const desktop = reporter.getEnviromentCombo({
  browserName: 'chrome',
  browserVersion: '91',
  platformName: 'macOS'
});
// Returns: "chrome (v91) on macOS"

// Desktop browser - compact  
const desktopCompact = reporter.getEnviromentCombo({
  browserName: 'chrome',
  browserVersion: '91', 
  platformName: 'macOS'
}, false);
// Returns: "chrome 91 macOS"

// Mobile device
const mobile = reporter.getEnviromentCombo({
  'appium:deviceName': 'iPhone 12',
  'appium:platformVersion': '14.5',
  'appium:platformName': 'iOS',
  browserName: 'Safari'
});
// Returns: "iPhone 12 on iOS 14.5 executing Safari"

// Multiremote
const multiremote = reporter.getEnviromentCombo({
  browserA: { browserName: 'chrome' },
  browserB: { browserName: 'firefox' }
}, true, true);
// Returns: "MultiremoteBrowser on chrome and firefox"

/**
 * Print current test status in real-time
 * Called automatically during test execution if realtimeReporting is enabled
 * @param stat - Current test, hook, or suite statistics
 */
printCurrentStats(stat: TestStats | HookStats | SuiteStats): void;

const reporter = new SpecReporter({
  realtimeReporting: true
});

// Automatically called during test execution:
// [chrome 91 macOS #0-0] ------------------------------------------------------------------
// [chrome 91 macOS #0-0] Suite started: 
// [chrome 91 macOS #0-0]   » /tests/login.test.js
// [chrome 91 macOS #0-0]    ✓ should display login form » [ /tests/login.test.js ]

/**
 * Get events to report from a suite
 * Filters tests and hooks to determine what should be included in output
 * @param suite - Suite statistics containing tests and hooks
 * @returns Array of events (tests and hooks) to report
 */
getEventsToReport(suite: SuiteStats): (HookStats | TestStats)[];

/**
 * Get suites in execution order
 * Returns suites ordered by their execution sequence
 * @returns Array of suites in execution order
 */
getOrderedSuites(): SuiteStats[];

/**
 * Calculate indentation for nested suites
 * @param uid - Unique suite identifier
 * @returns Indentation string (spaces)
 */
indent(uid: string): string;

// Internal usage for nested suite output:
// Suite Level 0: "Login Tests"
// Suite Level 1: "    Valid Credentials"  
// Suite Level 2: "        Admin User"
// Test Level:    "           ✓ should login successfully"

const reporter = new SpecReporter({});
// Indentation is managed automatically based on suite nesting