elsabro 2.3.0 → 3.7.0

package/references/testing-framework.md

@@ -0,0 +1,1151 @@
+# Testing Framework (v3.4)
+
+Framework de testing para agentes AI con mocking, simulación, fixtures y assertions comportamentales.
+
+## Arquitectura
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                       TESTING FRAMEWORK                                  │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                    TEST RUNNER                                   │    │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │    │
+│  │  │    Unit     │  │ Integration │  │    E2E      │              │    │
+│  │  │   Tests     │  │    Tests    │  │   Tests     │              │    │
+│  │  └─────────────┘  └─────────────┘  └─────────────┘              │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                    │                                     │
+│                                    ▼                                     │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                    MOCK PROVIDERS                                │    │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │    │
+│  │  │ MockLLM     │  │ MockTools   │  │ MockEvents  │              │    │
+│  │  │ (responses) │  │ (behavior)  │  │ (triggers)  │              │    │
+│  │  └─────────────┘  └─────────────┘  └─────────────┘              │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                    │                                     │
+│                                    ▼                                     │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                    SIMULATION ENGINE                             │    │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │    │
+│  │  │  Scenarios  │  │  Personas   │  │ Environment │              │    │
+│  │  │ (workflows) │  │  (users)    │  │  (context)  │              │    │
+│  │  └─────────────┘  └─────────────┘  └─────────────┘              │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                    │                                     │
+│                                    ▼                                     │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                    ASSERTIONS                                    │    │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │    │
+│  │  │ Behavioral  │  │  Property   │  │  Semantic   │              │    │
+│  │  │ (actions)   │  │(invariants) │  │ (meaning)   │              │    │
+│  │  └─────────────┘  └─────────────┘  └─────────────┘              │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## AgentTestRunner
+
+### API Principal
+
+```typescript
+interface TestCase {
+  name: string;
+  description?: string;
+  setup?: () => Promise<void>;
+  teardown?: () => Promise<void>;
+  timeout?: number;
+  retries?: number;
+  tags?: string[];
+}
+
+interface AgentTestCase extends TestCase {
+  agent: string | AgentConfig;
+  input: AgentInput;
+  expected?: ExpectedBehavior;
+  mocks?: MockConfig;
+  assertions: Assertion[];
+}
+
+interface TestResult {
+  name: string;
+  status: 'passed' | 'failed' | 'skipped' | 'error';
+  duration_ms: number;
+  assertions: AssertionResult[];
+  error?: Error;
+  logs?: string[];
+  metrics?: TestMetrics;
+}
+
+interface TestSuite {
+  name: string;
+  tests: AgentTestCase[];
+  beforeAll?: () => Promise<void>;
+  afterAll?: () => Promise<void>;
+  beforeEach?: () => Promise<void>;
+  afterEach?: () => Promise<void>;
+}
+
+class AgentTestRunner {
+  private mockProvider: MockProvider;
+  private assertionEngine: AssertionEngine;
+  private config: TestRunnerConfig;
+
+  constructor(config: TestRunnerConfig) {
+    this.config = config;
+    this.mockProvider = new MockProvider();
+    this.assertionEngine = new AssertionEngine();
+  }
+
+  // Run single test
+  async runTest(test: AgentTestCase): Promise<TestResult> {
+    const startTime = Date.now();
+    const logs: string[] = [];
+    const assertionResults: AssertionResult[] = [];
+
+    try {
+      // Setup
+      if (test.setup) await test.setup();
+
+      // Configure mocks
+      if (test.mocks) {
+        this.mockProvider.configure(test.mocks);
+      }
+
+      // Create agent with mocks injected
+      const agent = await this.createTestAgent(test.agent, test.mocks);
+
+      // Run agent
+      const result = await this.runWithTimeout(
+        agent.run(test.input),
+        test.timeout || this.config.defaultTimeout
+      );
+
+      // Run assertions
+      for (const assertion of test.assertions) {
+        const assertionResult = await this.assertionEngine.check(
+          assertion,
+          result,
+          { input: test.input, agent }
+        );
+        assertionResults.push(assertionResult);
+      }
+
+      // Check if all passed
+      const allPassed = assertionResults.every(r => r.passed);
+
+      return {
+        name: test.name,
+        status: allPassed ? 'passed' : 'failed',
+        duration_ms: Date.now() - startTime,
+        assertions: assertionResults,
+        logs,
+        metrics: this.collectMetrics(result)
+      };
+
+    } catch (error) {
+      return {
+        name: test.name,
+        status: 'error',
+        duration_ms: Date.now() - startTime,
+        assertions: assertionResults,
+        error: error as Error,
+        logs
+      };
+
+    } finally {
+      // Teardown
+      if (test.teardown) await test.teardown();
+      this.mockProvider.reset();
+    }
+  }
+
+  // Run test suite
+  async runSuite(suite: TestSuite): Promise<SuiteResult> {
+    const results: TestResult[] = [];
+
+    // Before all
+    if (suite.beforeAll) await suite.beforeAll();
+
+    for (const test of suite.tests) {
+      // Before each
+      if (suite.beforeEach) await suite.beforeEach();
+
+      // Run with retries
+      let result = await this.runTest(test);
+      let attempts = 1;
+
+      while (result.status === 'failed' && attempts < (test.retries || 1)) {
+        attempts++;
+        result = await this.runTest(test);
+      }
+
+      results.push(result);
+
+      // After each
+      if (suite.afterEach) await suite.afterEach();
+
+      // Stop on first failure if configured
+      if (this.config.stopOnFirstFailure && result.status === 'failed') {
+        break;
+      }
+    }
+
+    // After all
+    if (suite.afterAll) await suite.afterAll();
+
+    return {
+      name: suite.name,
+      results,
+      summary: this.summarize(results)
+    };
+  }
+
+  // Run all tests matching pattern
+  async runAll(pattern?: string): Promise<SuiteResult[]> {
+    const suites = await this.discoverTests(pattern);
+    const results: SuiteResult[] = [];
+
+    for (const suite of suites) {
+      results.push(await this.runSuite(suite));
+    }
+
+    return results;
+  }
+
+  // Watch mode
+  async watch(pattern?: string): Promise<void> {
+    console.log('Watching for changes...');
+
+    // Initial run
+    await this.runAll(pattern);
+
+    // Watch for file changes
+    const watcher = fs.watch(this.config.testDir, { recursive: true });
+
+    watcher.on('change', async (eventType, filename) => {
+      if (filename?.endsWith('.test.ts') || filename?.endsWith('.test.json')) {
+        console.log(`\nFile changed: ${filename}`);
+        await this.runAll(pattern);
+      }
+    });
+  }
+
+  private async createTestAgent(
+    agentConfig: string | AgentConfig,
+    mocks?: MockConfig
+  ): Promise<Agent> {
+    // Create agent with mock providers injected
+    const agent = typeof agentConfig === 'string'
+      ? await AgentFactory.create(agentConfig)
+      : await AgentFactory.createFromConfig(agentConfig);
+
+    if (mocks?.llm) {
+      agent.setLLMProvider(this.mockProvider.getLLM());
+    }
+    if (mocks?.tools) {
+      agent.setToolProvider(this.mockProvider.getTools());
+    }
+
+    return agent;
+  }
+
+  private async runWithTimeout<T>(promise: Promise<T>, timeout: number): Promise<T> {
+    return Promise.race([
+      promise,
+      new Promise<never>((_, reject) =>
+        setTimeout(() => reject(new Error('Test timeout')), timeout)
+      )
+    ]);
+  }
+
+  private summarize(results: TestResult[]): TestSummary {
+    return {
+      total: results.length,
+      passed: results.filter(r => r.status === 'passed').length,
+      failed: results.filter(r => r.status === 'failed').length,
+      skipped: results.filter(r => r.status === 'skipped').length,
+      errors: results.filter(r => r.status === 'error').length,
+      duration_ms: results.reduce((sum, r) => sum + r.duration_ms, 0)
+    };
+  }
+
+  private collectMetrics(result: AgentResult): TestMetrics {
+    return {
+      tokens_used: result.usage?.total_tokens || 0,
+      tool_calls: result.toolCalls?.length || 0,
+      cost: result.cost?.total || 0
+    };
+  }
+
+  private async discoverTests(pattern?: string): Promise<TestSuite[]> {
+    // Discover test files
+    const testFiles = await glob(
+      pattern || `${this.config.testDir}/**/*.test.{ts,json}`
+    );
+
+    const suites: TestSuite[] = [];
+
+    for (const file of testFiles) {
+      const suite = await this.loadTestFile(file);
+      suites.push(suite);
+    }
+
+    return suites;
+  }
+
+  private async loadTestFile(file: string): Promise<TestSuite> {
+    if (file.endsWith('.json')) {
+      const content = await fs.readFile(file, 'utf-8');
+      return JSON.parse(content);
+    }
+
+    // Dynamic import for .ts files
+    const module = await import(file);
+    return module.default || module;
+  }
+}
+```
+
+---
+
+## MockProvider
+
+```typescript
+interface MockLLMConfig {
+  responses?: MockResponse[];
+  defaultResponse?: string;
+  delay?: number;
+  errorRate?: number;
+  tokenUsage?: TokenUsage;
+}
+
+interface MockResponse {
+  match: string | RegExp | ((input: string) => boolean);
+  response: string | (() => string);
+  toolCalls?: ToolCall[];
+}
+
+interface MockToolConfig {
+  tools: Record<string, MockToolBehavior>;
+}
+
+interface MockToolBehavior {
+  response?: unknown;
+  error?: string;
+  delay?: number;
+  sideEffect?: (params: unknown) => void;
+}
+
+class MockProvider {
+  private llmConfig: MockLLMConfig = {};
+  private toolConfig: MockToolConfig = { tools: {} };
+  private callHistory: CallRecord[] = [];
+
+  configure(config: MockConfig): void {
+    if (config.llm) this.llmConfig = config.llm;
+    if (config.tools) this.toolConfig = config.tools;
+  }
+
+  reset(): void {
+    this.llmConfig = {};
+    this.toolConfig = { tools: {} };
+    this.callHistory = [];
+  }
+
+  // Get mock LLM provider
+  getLLM(): MockLLM {
+    return {
+      complete: async (prompt: string) => {
+        // Record call
+        this.callHistory.push({
+          type: 'llm',
+          input: prompt,
+          timestamp: new Date()
+        });
+
+        // Simulate delay
+        if (this.llmConfig.delay) {
+          await this.delay(this.llmConfig.delay);
+        }
+
+        // Simulate errors
+        if (this.llmConfig.errorRate && Math.random() < this.llmConfig.errorRate) {
+          throw new Error('Mock LLM error');
+        }
+
+        // Find matching response
+        const response = this.findMatchingResponse(prompt);
+
+        return {
+          content: response.text,
+          toolCalls: response.toolCalls,
+          usage: this.llmConfig.tokenUsage || {
+            input_tokens: prompt.length / 4,
+            output_tokens: response.text.length / 4,
+            total_tokens: (prompt.length + response.text.length) / 4
+          }
+        };
+      }
+    };
+  }
+
+  // Get mock tool provider
+  getTools(): MockToolProvider {
+    return {
+      call: async (name: string, params: unknown) => {
+        // Record call
+        this.callHistory.push({
+          type: 'tool',
+          name,
+          input: params,
+          timestamp: new Date()
+        });
+
+        const behavior = this.toolConfig.tools[name];
+
+        if (!behavior) {
+          throw new Error(`No mock configured for tool: ${name}`);
+        }
+
+        // Simulate delay
+        if (behavior.delay) {
+          await this.delay(behavior.delay);
+        }
+
+        // Execute side effect
+        if (behavior.sideEffect) {
+          behavior.sideEffect(params);
+        }
+
+        // Simulate error
+        if (behavior.error) {
+          throw new Error(behavior.error);
+        }
+
+        return behavior.response;
+      }
+    };
+  }
+
+  // Get call history for assertions
+  getCallHistory(): CallRecord[] {
+    return [...this.callHistory];
+  }
+
+  // Helpers for setting up mocks
+  mockLLMResponse(match: string | RegExp, response: string): void {
+    if (!this.llmConfig.responses) {
+      this.llmConfig.responses = [];
+    }
+    this.llmConfig.responses.push({ match, response });
+  }
+
+  mockTool(name: string, behavior: MockToolBehavior): void {
+    this.toolConfig.tools[name] = behavior;
+  }
+
+  mockToolSuccess(name: string, response: unknown): void {
+    this.toolConfig.tools[name] = { response };
+  }
+
+  mockToolError(name: string, error: string): void {
+    this.toolConfig.tools[name] = { error };
+  }
+
+  private findMatchingResponse(prompt: string): { text: string; toolCalls?: ToolCall[] } {
+    for (const mock of this.llmConfig.responses || []) {
+      let matches = false;
+
+      if (typeof mock.match === 'string') {
+        matches = prompt.includes(mock.match);
+      } else if (mock.match instanceof RegExp) {
+        matches = mock.match.test(prompt);
+      } else if (typeof mock.match === 'function') {
+        matches = mock.match(prompt);
+      }
+
+      if (matches) {
+        const text = typeof mock.response === 'function'
+          ? mock.response()
+          : mock.response;
+        return { text, toolCalls: mock.toolCalls };
+      }
+    }
+
+    return {
+      text: this.llmConfig.defaultResponse || 'Mock response'
+    };
+  }
+
+  private delay(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+```
+
+---
+
+## SimulationEngine
+
+```typescript
+interface Scenario {
+  name: string;
+  description: string;
+  steps: ScenarioStep[];
+  environment?: EnvironmentConfig;
+  persona?: PersonaConfig;
+}
+
+interface ScenarioStep {
+  action: 'user_input' | 'wait' | 'trigger_event' | 'assert' | 'checkpoint';
+  data?: unknown;
+  timeout?: number;
+}
+
+interface EnvironmentConfig {
+  files?: Record<string, string>;
+  env?: Record<string, string>;
+  time?: string;  // Frozen time
+}
+
+interface PersonaConfig {
+  name: string;
+  behavior: 'cooperative' | 'adversarial' | 'confused' | 'expert';
+  style?: 'verbose' | 'terse' | 'random';
+}
+
+class SimulationEngine {
+  private scenarios: Map<string, Scenario>;
+  private currentSimulation: SimulationState | null = null;
+
+  constructor() {
+    this.scenarios = new Map();
+  }
+
+  // Register scenario
+  registerScenario(scenario: Scenario): void {
+    this.scenarios.set(scenario.name, scenario);
+  }
+
+  // Run simulation
+  async simulate(
+    scenarioName: string,
+    agent: Agent,
+    options?: SimulationOptions
+  ): Promise<SimulationResult> {
+    const scenario = this.scenarios.get(scenarioName);
+    if (!scenario) throw new Error(`Scenario not found: ${scenarioName}`);
+
+    // Setup environment
+    const env = await this.setupEnvironment(scenario.environment);
+
+    // Create simulation state
+    this.currentSimulation = {
+      scenario,
+      agent,
+      env,
+      stepResults: [],
+      startedAt: new Date()
+    };
+
+    try {
+      // Run each step
+      for (let i = 0; i < scenario.steps.length; i++) {
+        const step = scenario.steps[i];
+        const stepResult = await this.runStep(step, i);
+
+        this.currentSimulation.stepResults.push(stepResult);
+
+        // Stop on failure if configured
+        if (!stepResult.success && options?.stopOnFailure) {
+          break;
+        }
+      }
+
+      return this.buildResult();
+
+    } finally {
+      // Cleanup
+      await this.cleanup(env);
+      this.currentSimulation = null;
+    }
+  }
+
+  // Generate test cases from scenario
+  async generateTestCases(scenarioName: string): Promise<AgentTestCase[]> {
+    const scenario = this.scenarios.get(scenarioName);
+    if (!scenario) throw new Error(`Scenario not found: ${scenarioName}`);
+
+    const testCases: AgentTestCase[] = [];
+
+    // Generate test case for each meaningful step
+    for (let i = 0; i < scenario.steps.length; i++) {
+      const step = scenario.steps[i];
+
+      if (step.action === 'user_input') {
+        testCases.push({
+          name: `${scenario.name} - Step ${i + 1}`,
+          description: `Test step: ${step.action}`,
+          agent: 'default',
+          input: { message: step.data as string },
+          assertions: [
+            { type: 'responds', timeout: 30000 },
+            { type: 'no_error' }
+          ]
+        });
+      }
+    }
+
+    return testCases;
+  }
+
+  private async runStep(step: ScenarioStep, index: number): Promise<StepResult> {
+    const startTime = Date.now();
+
+    try {
+      switch (step.action) {
+        case 'user_input':
+          return await this.handleUserInput(step.data as string);
+
+        case 'wait':
+          await this.delay(step.data as number);
+          return { success: true, duration_ms: step.data as number };
+
+        case 'trigger_event':
+          await EventBus.publish(
+            (step.data as any).event,
+            (step.data as any).payload
+          );
+          return { success: true, duration_ms: Date.now() - startTime };
+
+        case 'assert':
+          const assertion = step.data as Assertion;
+          const result = await this.checkAssertion(assertion);
+          return {
+            success: result.passed,
+            duration_ms: Date.now() - startTime,
+            assertion: result
+          };
+
+        case 'checkpoint':
+          // Save simulation state for later analysis
+          return {
+            success: true,
+            duration_ms: Date.now() - startTime,
+            checkpoint: this.captureState()
+          };
+
+        default:
+          throw new Error(`Unknown step action: ${step.action}`);
+      }
+    } catch (error) {
+      return {
+        success: false,
+        duration_ms: Date.now() - startTime,
+        error: error as Error
+      };
+    }
+  }
+
+  private async handleUserInput(input: string): Promise<StepResult> {
+    if (!this.currentSimulation) throw new Error('No simulation running');
+
+    const startTime = Date.now();
+    const result = await this.currentSimulation.agent.run({ message: input });
+
+    return {
+      success: true,
+      duration_ms: Date.now() - startTime,
+      agentResult: result
+    };
+  }
+
+  private async setupEnvironment(config?: EnvironmentConfig): Promise<SimulationEnv> {
+    const env: SimulationEnv = {
+      tempDir: await fs.mkdtemp(path.join(os.tmpdir(), 'elsabro-sim-')),
+      originalEnv: { ...process.env }
+    };
+
+    // Create mock files
+    if (config?.files) {
+      for (const [filePath, content] of Object.entries(config.files)) {
+        const fullPath = path.join(env.tempDir, filePath);
+        await fs.mkdir(path.dirname(fullPath), { recursive: true });
+        await fs.writeFile(fullPath, content);
+      }
+    }
+
+    // Set environment variables
+    if (config?.env) {
+      Object.assign(process.env, config.env);
+    }
+
+    return env;
+  }
+
+  private async cleanup(env: SimulationEnv): Promise<void> {
+    // Restore environment
+    process.env = env.originalEnv;
+
+    // Remove temp directory
+    await fs.rm(env.tempDir, { recursive: true, force: true });
+  }
+
+  private buildResult(): SimulationResult {
+    if (!this.currentSimulation) throw new Error('No simulation');
+
+    const { scenario, stepResults, startedAt } = this.currentSimulation;
+
+    return {
+      scenario: scenario.name,
+      success: stepResults.every(r => r.success),
+      steps: stepResults,
+      duration_ms: Date.now() - startedAt.getTime(),
+      summary: {
+        totalSteps: stepResults.length,
+        passedSteps: stepResults.filter(r => r.success).length,
+        failedSteps: stepResults.filter(r => !r.success).length
+      }
+    };
+  }
+
+  private captureState(): SimulationCheckpoint {
+    return {
+      timestamp: new Date().toISOString(),
+      memory: MemoryManager.export(),
+      tasks: TaskList()
+    };
+  }
+
+  private async checkAssertion(assertion: Assertion): Promise<AssertionResult> {
+    return this.assertionEngine.check(assertion, this.currentSimulation);
+  }
+
+  private delay(ms: number): Promise<void> {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+```
+
+---
+
+## AssertionEngine
+
+```typescript
+type AssertionType =
+  | 'responds'           // Agent responded
+  | 'no_error'           // No errors occurred
+  | 'tool_called'        // Specific tool was called
+  | 'tool_not_called'    // Tool was not called
+  | 'output_contains'    // Output contains text
+  | 'output_matches'     // Output matches regex
+  | 'semantic_match'     // Semantic similarity
+  | 'behavior'           // Custom behavior check
+  | 'property'           // Property-based test
+  | 'cost_under'         // Cost below threshold
+  | 'time_under';        // Time below threshold
+
+interface Assertion {
+  type: AssertionType;
+  value?: unknown;
+  message?: string;
+  timeout?: number;
+}
+
+interface AssertionResult {
+  assertion: Assertion;
+  passed: boolean;
+  actual?: unknown;
+  expected?: unknown;
+  message?: string;
+}
+
+class AssertionEngine {
+  private customAssertions: Map<string, AssertionHandler>;
+
+  constructor() {
+    this.customAssertions = new Map();
+  }
+
+  // Check assertion
+  async check(
+    assertion: Assertion,
+    result: AgentResult,
+    context?: AssertionContext
+  ): Promise<AssertionResult> {
+    switch (assertion.type) {
+      case 'responds':
+        return this.assertResponds(result);
+
+      case 'no_error':
+        return this.assertNoError(result);
+
+      case 'tool_called':
+        return this.assertToolCalled(result, assertion.value as string);
+
+      case 'tool_not_called':
+        return this.assertToolNotCalled(result, assertion.value as string);
+
+      case 'output_contains':
+        return this.assertOutputContains(result, assertion.value as string);
+
+      case 'output_matches':
+        return this.assertOutputMatches(result, assertion.value as string);
+
+      case 'semantic_match':
+        return await this.assertSemanticMatch(result, assertion.value as string);
+
+      case 'behavior':
+        return await this.assertBehavior(result, assertion.value as BehaviorSpec, context);
+
+      case 'property':
+        return this.assertProperty(result, assertion.value as PropertySpec);
+
+      case 'cost_under':
+        return this.assertCostUnder(result, assertion.value as number);
+
+      case 'time_under':
+        return this.assertTimeUnder(result, assertion.value as number);
+
+      default:
+        // Check custom assertions
+        const handler = this.customAssertions.get(assertion.type);
+        if (handler) {
+          return handler(assertion, result, context);
+        }
+        throw new Error(`Unknown assertion type: ${assertion.type}`);
+    }
+  }
+
+  // Register custom assertion
+  registerAssertion(type: string, handler: AssertionHandler): void {
+    this.customAssertions.set(type, handler);
+  }
+
+  // Built-in assertions
+  private assertResponds(result: AgentResult): AssertionResult {
+    const passed = result.output !== undefined && result.output !== null;
+    return {
+      assertion: { type: 'responds' },
+      passed,
+      actual: result.output,
+      message: passed ? 'Agent responded' : 'Agent did not respond'
+    };
+  }
+
+  private assertNoError(result: AgentResult): AssertionResult {
+    const passed = !result.error;
+    return {
+      assertion: { type: 'no_error' },
+      passed,
+      actual: result.error,
+      message: passed ? 'No error' : `Error: ${result.error?.message}`
+    };
+  }
+
+  private assertToolCalled(result: AgentResult, toolName: string): AssertionResult {
+    const called = result.toolCalls?.some(tc => tc.name === toolName) || false;
+    return {
+      assertion: { type: 'tool_called', value: toolName },
+      passed: called,
+      actual: result.toolCalls?.map(tc => tc.name),
+      expected: toolName,
+      message: called ? `Tool ${toolName} was called` : `Tool ${toolName} was not called`
+    };
+  }
+
+  private assertToolNotCalled(result: AgentResult, toolName: string): AssertionResult {
+    const called = result.toolCalls?.some(tc => tc.name === toolName) || false;
+    return {
+      assertion: { type: 'tool_not_called', value: toolName },
+      passed: !called,
+      actual: result.toolCalls?.map(tc => tc.name),
+      message: !called ? `Tool ${toolName} was not called` : `Tool ${toolName} was called`
+    };
+  }
+
+  private assertOutputContains(result: AgentResult, text: string): AssertionResult {
+    const output = String(result.output || '');
+    const contains = output.includes(text);
+    return {
+      assertion: { type: 'output_contains', value: text },
+      passed: contains,
+      actual: output.slice(0, 200),
+      expected: text,
+      message: contains ? 'Output contains expected text' : 'Output does not contain expected text'
+    };
+  }
+
+  private assertOutputMatches(result: AgentResult, pattern: string): AssertionResult {
+    const output = String(result.output || '');
+    const regex = new RegExp(pattern);
+    const matches = regex.test(output);
+    return {
+      assertion: { type: 'output_matches', value: pattern },
+      passed: matches,
+      actual: output.slice(0, 200),
+      expected: pattern,
+      message: matches ? 'Output matches pattern' : 'Output does not match pattern'
+    };
+  }
+
+  private async assertSemanticMatch(result: AgentResult, expected: string): Promise<AssertionResult> {
+    // Use LLM to check semantic similarity
+    const output = String(result.output || '');
+
+    // Simple semantic check (could use embeddings in production)
+    const prompt = `Compare these two texts for semantic similarity.
+Text 1: "${output.slice(0, 500)}"
+Text 2: "${expected}"
+
+Are they semantically similar in meaning? Answer only "yes" or "no".`;
+
+    const response = await this.quickLLMCheck(prompt);
+    const similar = response.toLowerCase().includes('yes');
+
+    return {
+      assertion: { type: 'semantic_match', value: expected },
+      passed: similar,
+      actual: output.slice(0, 200),
+      expected,
+      message: similar ? 'Semantically similar' : 'Not semantically similar'
+    };
+  }
+
+  private async assertBehavior(
+    result: AgentResult,
+    spec: BehaviorSpec,
+    context?: AssertionContext
+  ): Promise<AssertionResult> {
+    // Check behavioral specification
+    let passed = true;
+    const violations: string[] = [];
+
+    if (spec.mustCallTools) {
+      for (const tool of spec.mustCallTools) {
+        if (!result.toolCalls?.some(tc => tc.name === tool)) {
+          passed = false;
+          violations.push(`Did not call required tool: ${tool}`);
+        }
+      }
+    }
+
+    if (spec.mustNotCallTools) {
+      for (const tool of spec.mustNotCallTools) {
+        if (result.toolCalls?.some(tc => tc.name === tool)) {
+          passed = false;
+          violations.push(`Called forbidden tool: ${tool}`);
+        }
+      }
+    }
+
+    if (spec.mustAsk && !result.askedUser) {
+      passed = false;
+      violations.push('Did not ask user when expected');
+    }
+
+    if (spec.customCheck) {
+      const customResult = await spec.customCheck(result, context);
+      if (!customResult.passed) {
+        passed = false;
+        violations.push(customResult.reason || 'Custom check failed');
+      }
+    }
+
+    return {
+      assertion: { type: 'behavior', value: spec },
+      passed,
+      message: passed ? 'Behavior matches spec' : violations.join('; ')
+    };
+  }
+
+  private assertProperty(result: AgentResult, spec: PropertySpec): AssertionResult {
+    // Property-based testing
+    let passed = true;
+    const violations: string[] = [];
+
+    if (spec.invariant) {
+      const holds = spec.invariant(result);
+      if (!holds) {
+        passed = false;
+        violations.push('Invariant violated');
+      }
+    }
+
+    if (spec.postcondition) {
+      const holds = spec.postcondition(result);
+      if (!holds) {
+        passed = false;
+        violations.push('Postcondition not satisfied');
+      }
+    }
+
+    return {
+      assertion: { type: 'property', value: spec },
+      passed,
+      message: passed ? 'Properties satisfied' : violations.join('; ')
+    };
+  }
+
+  private assertCostUnder(result: AgentResult, maxCost: number): AssertionResult {
+    const cost = result.cost?.total || 0;
+    const passed = cost <= maxCost;
+    return {
+      assertion: { type: 'cost_under', value: maxCost },
+      passed,
+      actual: cost,
+      expected: `<= ${maxCost}`,
+      message: passed ? `Cost $${cost} is under $${maxCost}` : `Cost $${cost} exceeds $${maxCost}`
+    };
+  }
+
+  private assertTimeUnder(result: AgentResult, maxTime: number): AssertionResult {
+    const time = result.duration_ms || 0;
+    const passed = time <= maxTime;
+    return {
+      assertion: { type: 'time_under', value: maxTime },
+      passed,
+      actual: time,
+      expected: `<= ${maxTime}ms`,
+      message: passed ? `Time ${time}ms is under ${maxTime}ms` : `Time ${time}ms exceeds ${maxTime}ms`
+    };
+  }
+
+  private async quickLLMCheck(prompt: string): Promise<string> {
+    // Quick LLM check for semantic assertions
+    // In production, use a small/fast model
+    return 'yes'; // Placeholder
+  }
+}
+```
+
+---
+
+## Test Fixtures
+
+```typescript
+class TestFixtures {
+  private fixtures: Map<string, unknown>;
+
+  constructor() {
+    this.fixtures = new Map();
+    this.loadBuiltinFixtures();
+  }
+
+  // Get fixture
+  get<T>(name: string): T {
+    const fixture = this.fixtures.get(name);
+    if (!fixture) throw new Error(`Fixture not found: ${name}`);
+    return fixture as T;
+  }
+
+  // Register fixture
+  register(name: string, value: unknown): void {
+    this.fixtures.set(name, value);
+  }
+
+  // Load fixture from file
+  async loadFile(name: string, path: string): Promise<void> {
+    const content = await fs.readFile(path, 'utf-8');
+    this.fixtures.set(name, content);
+  }
+
+  // Create temporary file fixture
+  async createTempFile(name: string, content: string): Promise<string> {
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'fixture-'));
+    const filePath = path.join(tempDir, name);
+    await fs.writeFile(filePath, content);
+    this.fixtures.set(`file:${name}`, filePath);
+    return filePath;
+  }
+
+  private loadBuiltinFixtures(): void {
+    // Common test fixtures
+    this.fixtures.set('emptyInput', { message: '' });
+    this.fixtures.set('simpleTask', { message: 'Hello, world!' });
+    this.fixtures.set('codeTask', {
+      message: 'Write a function to add two numbers'
+    });
+    this.fixtures.set('errorInput', { message: null });
+  }
+}
+```
+
+---
+
+## Comandos
+
+```bash
+/elsabro:test                     # Ejecutar todos los tests
+/elsabro:test run explore.test    # Ejecutar test específico
+/elsabro:test watch               # Modo watch
+/elsabro:test coverage            # Reporte de cobertura
+/elsabro:test simulate scenario1  # Ejecutar simulación
+```
+
+---
+
+## Ejemplo de Test
+
+```typescript
+// tests/explore-agent.test.ts
+export default {
+  name: 'Explore Agent Tests',
+  tests: [
+    {
+      name: 'should find TypeScript files',
+      agent: 'Explore',
+      input: { message: 'Find all TypeScript files in src/' },
+      mocks: {
+        tools: {
+          Glob: { response: ['src/index.ts', 'src/utils.ts'] }
+        }
+      },
+      assertions: [
+        { type: 'responds' },
+        { type: 'no_error' },
+        { type: 'tool_called', value: 'Glob' },
+        { type: 'output_contains', value: '.ts' }
+      ]
+    }
+  ]
+};
+```
+
+---
+
+## Configuración
+
+```json
+{
+  "testing": {
+    "enabled": true,
+    "testDir": ".elsabro/tests",
+    "defaultTimeout": 30000,
+    "stopOnFirstFailure": false,
+    "retries": 1,
+    "parallel": false,
+    "coverage": {
+      "enabled": true,
+      "threshold": 80
+    }
+  }
+}
+```
+
+---
+
+## Changelog
+
+- **v3.4.0**: Initial Testing Framework
+  - AgentTestRunner with suites
+  - MockProvider for LLM and tools
+  - SimulationEngine for scenarios
+  - AssertionEngine with 12+ assertion types
+  - TestFixtures for reusable data