Test Execution

/**
 * Executes test scripts with specified options and reporter
 * @param scripts - Single script or array of scripts to execute
 * @param options - Execution configuration options
 * @param reporter - Optional reporter for custom output handling
 * @returns Promise resolving to test execution results
 */
function execute(scripts: Script | Script[], options?: ExecutionOptions, reporter?: Reporter): Promise<Notebook>;

const Lab = require('@hapi/lab');

// Execute single script
const script = Lab.script();
const result = await Lab.execute(script, { timeout: 5000 });

// Execute multiple scripts
const results = await Lab.execute([script1, script2], {
    coverage: true,
    reporter: 'json'
});

// Execute with custom reporter
const customReporter = {
    start: (info) => console.log(`Starting ${info.count} tests`),
    test: (test) => console.log(`Test: ${test.title}`)
};
await Lab.execute(script, {}, customReporter);

/**
 * Executes tests and generates comprehensive reports with analysis
 * @param scripts - Single script or array of scripts to execute
 * @param options - Execution and reporting configuration options
 * @returns Promise resolving to detailed test results with optional analysis
 */
function report(scripts: Script | Script[], options?: ExecutionOptions): Promise<Notebook>;

// Basic report with coverage
const report = await Lab.report(script, {
    coverage: true,
    threshold: 80
});

// Full analysis report
const fullReport = await Lab.report(scripts, {
    coverage: true,
    leaks: true,
    types: true,
    reporter: 'html',
    output: 'test-results.html'
});

interface Notebook {
    /** Total execution time in milliseconds */
    ms: number;
    
    /** Array of individual test results */
    tests: TestResult[];
    
    /** Number of failed tests */
    failures: number;
    
    /** Array of execution errors */
    errors: any[];
    
    /** Code coverage analysis results (if coverage enabled) */
    coverage?: CoverageReport;
    
    /** Memory leak detection results (if leaks enabled) */
    leaks?: LeakReport;
    
    /** TypeScript validation results (if types enabled) */
    types?: TypesReport;
    
    /** Random seed used (if shuffle enabled) */
    seed?: number;
    
    /** Whether test order was shuffled */
    shuffle?: boolean;
}

interface TestResult {
    /** Unique test identifier */
    id: number;
    
    /** Full test title including experiment path */
    title: string;
    
    /** Test execution status */
    status: 'pass' | 'fail' | 'skip';
    
    /** Execution time in milliseconds */
    duration: number;
    
    /** Error information for failed tests */
    err?: TestError;
    
    /** Test notes added via flags.note() */
    notes?: string[];
    
    /** Number of planned assertions */
    plan?: number;
    
    /** Actual number of assertions executed */
    assertions?: number;
}

interface TestError {
    /** Error message */
    message: string;
    
    /** Stack trace */
    stack: string;
    
    /** Expected value (for assertion errors) */
    expected?: any;
    
    /** Actual value (for assertion errors) */
    actual?: any;
    
    /** Assertion operator (for assertion errors) */
    operator?: string;
}

interface ExecutionOptions {
    /** Name of assertion library module to require */
    assert?: string;
    
    /** Exit with non-zero code on first test failure */
    bail?: boolean;
    
    /** Enable color output (default: based on terminal capabilities) */
    colors?: boolean;
    
    /** Timeout for setup/teardown hooks in milliseconds */
    'context-timeout'?: number;
    
    /** Enable code coverage analysis */
    coverage?: boolean;
    
    /** Include all files in coverage report */
    'coverage-all'?: boolean;
    
    /** Code coverage file exclusion patterns */
    'coverage-exclude'?: string[];
    
    /** Prevent recursive coverage inclusion */
    'coverage-flat'?: boolean;
    
    /** Set code coverage path */
    'coverage-path'?: string;
    
    /** Code coverage predicates configuration */
    'coverage-predicates'?: { [key: string]: boolean };
    
    /** File pattern for coverage analysis */
    coveragePattern?: RegExp;
    
    /** Minimum plan threshold for tests without explicit plan */
    'default-plan-threshold'?: number;
    
    /** Skip all tests (dry run mode) */
    dry?: boolean;
    
    /** Set NODE_ENV value before tests */
    environment?: string;
    
    /** Number of retries for failing tests */
    retries?: number;
    
    /** Prevent recursive test file collection */
    flat?: boolean;
    
    /** List of globals to ignore for leak detection */
    globals?: string[];
    
    /** Only run tests matching this pattern (RegExp) */
    grep?: string;
    
    /** Range of test IDs to execute */
    id?: number[];
    
    /** Start with Node.js native debugger */
    inspect?: boolean;
    
    /** Enable global variable leak detection */
    leaks?: boolean;
    
    /** Enable code linting */
    lint?: boolean;
    
    /** Linter executable path */
    linter?: string;
    
    /** Apply linter fixes automatically */
    'lint-fix'?: boolean;
    
    /** JSON string of linter options */
    'lint-options'?: string;
    
    /** Maximum absolute linting errors */
    'lint-errors-threshold'?: number;
    
    /** Maximum absolute linting warnings */
    'lint-warnings-threshold'?: number;
    
    /** Output file path(s) for test results */
    output?: string | string[];
    
    /** File paths to load tests from */
    path?: string[];
    
    /** File pattern for locating tests */
    pattern?: RegExp;
    
    /** Reporter type(s) for output formatting */
    reporter?: string | string[];
    
    /** Random seed for test shuffling */
    seed?: string;
    
    /** Shuffle test execution order */
    shuffle?: boolean;
    
    /** Silence skipped tests in output */
    'silent-skips'?: boolean;
    
    /** Enable source map support */
    sourcemaps?: boolean;
    
    /** Code coverage threshold percentage */
    threshold?: number;
    
    /** Test timeout in milliseconds */
    timeout?: number;
    
    /** Source code transformers for non-JS files */
    transform?: Transformer[];
    
    /** Enable TypeScript validation */
    types?: boolean;
    
    /** Location of TypeScript definitions test file */
    'types-test'?: string;
    
    /** Output verbosity level (0: none, 1: normal, 2: verbose) */
    progress?: number;
}

interface Transformer {
    /** File extension to transform */
    readonly ext: string;
    
    /** 
     * Transform file content
     * @param content - Original file content
     * @param filename - File being transformed
     * @returns Transformed content
     */
    transform(content: string, filename: string): string;
}

interface Reporter {
    /** 
     * Called at the start of test execution
     * @param info - Information about the test run
     */
    start?(info: { count: number }): void;
    
    /** 
     * Called for each completed test
     * @param test - Individual test result
     */
    test?(test: TestResult): void;
    
    /** 
     * Called at the end of test execution
     * @param notebook - Complete test results
     */
    end?(notebook: Notebook): void;
}

// Custom console reporter
const customReporter = {
    start: (info) => {
        console.log(`Starting ${info.count} tests`);
    },
    test: (test) => {
        const status = test.status === 'pass' ? '✓' : '✗';
        console.log(`${status} ${test.title} (${test.duration}ms)`);
    },
    end: (notebook) => {
        console.log(`Tests completed in ${notebook.ms}ms`);
        console.log(`Failures: ${notebook.failures}`);
    }
};

await Lab.execute(script, {}, customReporter);

// Single reporter
await Lab.report(script, { reporter: 'json' });

// Multiple reporters
await Lab.report(script, { 
    reporter: ['console', 'html'],
    output: [process.stdout, 'coverage.html']
});