refactor: fail fast on invalid pipeline steps (#237)

Author: jackwener

src/execution.ts

@@ -11,7 +11,7 @@
 
 import { type CliCommand, type InternalCliCommand, type Arg, Strategy, getRegistry, fullName } from './registry.js';
 import type { IPage } from './types.js';
-import { executePipeline } from './pipeline.js';
+import { executePipeline } from './pipeline/index.js';
 import { AdapterLoadError } from './errors.js';
 import { shouldUseBrowserSession } from './capabilityRouting.js';
 import { getBrowserFactory, browserSession, runWithTimeout, DEFAULT_BROWSER_COMMAND_TIMEOUT } from './runtime.js';

src/pipeline.ts

@@ -4,6 +4,7 @@
 
 import { describe, it, expect, vi } from 'vitest';
 import { executePipeline } from './index.js';
+import { ConfigError } from '../errors.js';
 import type { IPage } from '../types.js';
 
 /** Create a minimal mock page for testing */
@@ -148,13 +149,13 @@ describe('executePipeline', () => {
     expect(page.wait).toHaveBeenCalledWith(2);
   });
 
-  it('handles unknown steps gracefully in debug mode', async () => {
-    const stderr = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
-    await executePipeline(null, [
+  it('fails fast on unknown steps', async () => {
+    await expect(executePipeline(null, [
       { unknownStep: 'test' },
-    ], { debug: true });
-    expect(stderr).toHaveBeenCalledWith(expect.stringContaining('Unknown step'));
-    stderr.mockRestore();
+    ], { debug: true })).rejects.toBeInstanceOf(ConfigError);
+    await expect(executePipeline(null, [
+      { unknownStep: 'test' },
+    ], { debug: true })).rejects.toThrow('Unknown pipeline step "unknownStep"');
   });
 
   it('passes args through template rendering', async () => {

src/pipeline/executor.test.ts

@@ -6,6 +6,7 @@ import chalk from 'chalk';
 import type { IPage } from '../types.js';
 import { getStep, type StepHandler } from './registry.js';
 import { log } from '../logger.js';
+import { ConfigError } from '../errors.js';
 
 export interface PipelineContext {
   args?: Record<string, unknown>;
@@ -32,7 +33,10 @@ export async function executePipeline(
       if (handler) {
         data = await handler(page, params, data, args);
       } else {
-        if (debug) log.warn(`Unknown step: ${op}`);
+        throw new ConfigError(
+          `Unknown pipeline step "${op}" at index ${i}.`,
+          'Check the YAML pipeline step name or register the custom step before execution.',
+        );
       }
 
       if (debug) debugStepResult(op, data);