@stratix/testing 0.4.0 → 0.4.4

package/README.md

@@ -1,365 +1,105 @@
-# @stratix/testing
+<div align="center">
+  <img src="https://raw.githubusercontent.com/stratix-dev/stratix/main/public/logo-no-bg.png" alt="Stratix Logo" width="200"/>
 
-Comprehensive testing utilities for Stratix applications, with specialized support for AI agents.
+# @stratix/testing
 
-## Installation
+**Testing utilities and mocks for Stratix applications**
 
-```bash
-pnpm add -D @stratix/testing
-```
+[![npm version](https://img.shields.io/npm/v/@stratix/testing.svg)](https://www.npmjs.com/package/@stratix/testing)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-## Features
+[Documentation](https://stratix-dev.github.io/stratix/) | [Getting Started](https://stratix-dev.github.io/stratix/docs/getting-started/quick-start)
 
-### AI Agent Testing
+</div>
 
-- **MockLLMProvider** - Mock LLM provider for deterministic agent testing
-- **AgentTester** - High-level testing utility with timeout support
-- **Agent Assertions** - Specialized assertions for agent results
-- **Test Helpers** - Utilities for creating test contexts and IDs
+-
 
-### General Testing
+> Part of **[Stratix Framework](https://stratix-dev.github.io/stratix/)** - A TypeScript framework for building scalable applications with Domain-Driven Design, Hexagonal Architecture, and CQRS patterns.
+>
+> **New to Stratix?** Start with the [Getting Started Guide](https://stratix-dev.github.io/stratix/docs/getting-started/quick-start)
 
-- **TestApplication** - Simplified test application builder
-- **Result Assertions** - Assertions for Result pattern
-- **EntityBuilder** - Fluent API for building test entities
-- **DataFactory** - Generate test data (emails, IDs, dates, etc.)
+-
 
-## Quick Examples
+## About This Package
 
-### Testing AI Agents
+`@stratix/testing` provides testing utilities, mocks, and helpers for testing Stratix applications and AI agents.
 
-```typescript
-import { AgentTester, expectSuccess } from '@stratix/testing';
+**This package includes:**
+- MockLLMProvider for deterministic AI agent testing
+- In-memory repository implementations
+- Test data builders
+- CQRS testing utilities
 
-describe('CustomerSupportAgent', () => {
-  let tester: AgentTester;
+## About Stratix
 
-  beforeEach(() => {
-    tester = new AgentTester();
-  });
+Stratix is an AI-first TypeScript framework combining Domain-Driven Design, Hexagonal Architecture, and CQRS. It provides production-ready patterns for building scalable, maintainable applications with AI agents as first-class citizens.
 
-  it('should respond to greetings', async () => {
-    const agent = new CustomerSupportAgent(...);
+**Key Resources:**
+- [Documentation](https://stratix-dev.github.io/stratix/)
+- [Quick Start](https://stratix-dev.github.io/stratix/docs/getting-started/quick-start)
+- [Report Issues](https://github.com/stratix-dev/stratix/issues)
 
-    // Set deterministic mock response
-    tester.setMockResponse({
-      content: 'Hello! How can I help you today?',
-      usage: { promptTokens: 10, completionTokens: 20, totalTokens: 30 }
-    });
+## Installation
 
-    const result = await tester.test(agent, { message: 'Hi' });
+**Prerequisites:**
+- Node.js 18.0.0 or higher
+- `@stratix/core` installed
 
-    expect(result.passed).toBe(true);
-    expectSuccess(result.result);
-    expect(result.duration).toBeLessThan(1000);
-  });
-});
+```bash
+npm install --save-dev @stratix/testing
 ```
 
-### Using MockLLMProvider Directly
+## Quick Start
 
 ```typescript
 import { MockLLMProvider } from '@stratix/testing';
+import { MyAgent } from './my-agent';
 
-const mockProvider = new MockLLMProvider();
-mockProvider.setResponse({
-  content: '{"result": "success"}',
-  usage: { promptTokens: 10, completionTokens: 20, totalTokens: 30 }
-});
-
-const agent = new MyAgent({ provider: mockProvider });
-const result = await agent.execute(input);
-
-// Verify calls
-expect(mockProvider.getCallCount()).toBe(1);
-expect(mockProvider.getLastCall()).toBeDefined();
-```
-
-### Testing with TestApplication
-
-```typescript
-import { TestApplication } from '@stratix/testing';
-
-describe('Integration Tests', () => {
-  let app: Application;
-
-  beforeEach(async () => {
-    app = await TestApplication.create()
-      .useInMemoryDefaults()
-      .usePlugin(myPlugin)
-      .build();
-
-    await app.start();
-  });
-
-  afterEach(async () => {
-    await app.stop();
-  });
-
-  it('should process commands', async () => {
-    // Test with fully configured app
+describe('MyAgent', () => {
+  it('should process input correctly', async () => {
+    const mockProvider = new MockLLMProvider({
+      responses: [{ content: 'Expected response', usage: { totalTokens: 10, cost: 0.001 } }]
+    });
+    
+    const agent = new MyAgent(mockProvider);
+    const result = await agent.run('test input');
+    
+    expect(result.isSuccess).toBe(true);
+    expect(result.value).toBe('Expected response');
   });
 });
 ```
 
-### Using Result Assertions
-
-```typescript
-import { assertSuccess, unwrapSuccess } from '@stratix/testing';
-
-const result = await commandHandler.execute(command);
-
-// Assert success and throw if failed
-assertSuccess(result);
-
-// Or unwrap value directly
-const value = unwrapSuccess(result);
-expect(value.id).toBeDefined();
-```
-
-### Building Test Entities
-
-```typescript
-import { EntityBuilder } from '@stratix/testing';
-
-const user = new EntityBuilder(User)
-  .withProps({ email: 'test@example.com', name: 'Test User' })
-  .withId(testUserId)
-  .build();
-
-// Build multiple
-const users = new EntityBuilder(User)
-  .withProps({ role: 'admin' })
-  .buildMany(5);
-```
-
-### Generating Test Data
-
-```typescript
-import { DataFactory } from '@stratix/testing';
-
-const email = DataFactory.email('user'); // user1@example.com
-const id = DataFactory.entityId<'User'>();
-const date = DataFactory.date(7); // 7 days ago
-const status = DataFactory.pick(['active', 'inactive']);
-```
+## Related Packages
 
-## API Reference
+**Essential:**
+- [`@stratix/core`](https://www.npmjs.com/package/@stratix/core) - Core primitives and abstractions
+- [`@stratix/runtime`](https://www.npmjs.com/package/@stratix/runtime) - Application runtime
 
-### AgentTester
+**AI Testing:**
+- [`@stratix/ai-openai`](https://www.npmjs.com/package/@stratix/ai-openai) - OpenAI LLM provider
+- [`@stratix/ai-anthropic`](https://www.npmjs.com/package/@stratix/ai-anthropic) - Anthropic Claude provider
 
-High-level testing utility for AI agents.
+## Documentation
 
-```typescript
-class AgentTester {
-  constructor(options?: TestOptions)
-
-  // Mock configuration
-  setMockResponse(response: MockResponse): void
-  setMockResponses(responses: MockResponse[]): void
-  getMockProvider(): MockLLMProvider
-
-  // Testing
-  test<TInput, TOutput>(
-    agent: AIAgent<TInput, TOutput>,
-    input: TInput,
-    context?: AgentContext
-  ): Promise<TestResult<TOutput>>
-
-  // Assertions
-  assertSuccess<TOutput>(result: TestResult<TOutput>): void
-  assertFailure<TOutput>(result: TestResult<TOutput>): void
-  assertDuration<TOutput>(result: TestResult<TOutput>, maxDuration: number): void
-  assertCallCount(expectedCount: number): void
-
-  // Utilities
-  reset(): void
-}
-```
+- [Getting Started](https://stratix-dev.github.io/stratix/docs/getting-started/quick-start)
+- [Core Concepts](https://stratix-dev.github.io/stratix/docs/core-concepts/architecture-overview)
+- [Plugin Architecture](https://stratix-dev.github.io/stratix/docs/plugins/plugin-architecture)
+- [Complete Documentation](https://stratix-dev.github.io/stratix/)
 
-### MockLLMProvider
+## Support
 
-Mock LLM provider implementing the `LLMProvider` interface.
+- [GitHub Issues](https://github.com/stratix-dev/stratix/issues)
+- [Documentation](https://stratix-dev.github.io/stratix/)
 
-```typescript
-class MockLLMProvider implements LLMProvider {
-  // Configuration
-  setResponse(response: MockResponse): void
-  setResponses(responses: MockResponse[]): void
-  addResponse(response: MockResponse): void
-
-  // Inspection
-  getCallHistory(): ReadonlyArray<ChatParams>
-  getLastCall(): ChatParams | undefined
-  getCallCount(): number
-
-  // Utilities
-  reset(): void
-
-  // LLMProvider implementation
-  chat(params: ChatParams): Promise<ChatResponse>
-  streamChat(params: ChatParams): AsyncIterable<ChatChunk>
-  embeddings(params: EmbeddingParams): Promise<EmbeddingResponse>
-}
-```
-
-### Agent Assertions
-
-Specialized assertions for agent results.
-
-```typescript
-// Success/Failure
-expectSuccess<T>(result: AgentResult<T>): void
-expectFailure<T>(result: AgentResult<T>): void
-
-// Data validation
-expectData<T>(result: AgentResult<T>, expected: T): void
-expectDataContains<T>(result: AgentResult<T>, expected: Partial<T>): void
-
-// Performance
-expectCostWithinBudget<T>(result: AgentResult<T>, budget: number): void
-expectDurationWithinLimit<T>(result: AgentResult<T>, maxDuration: number): void
-
-// Error validation
-expectErrorContains<T>(result: AgentResult<T>, expectedText: string): void
-
-// Model validation
-expectModel<T>(result: AgentResult<T>, expectedModel: string): void
-```
-
-### Test Helpers
-
-Utilities for creating test data and running tests.
-
-```typescript
-// Context creation
-createTestContext(overrides?: Partial<{
-  userId: string;
-  sessionId: string;
-  environment: 'development' | 'staging' | 'production';
-  metadata: Record<string, unknown>;
-  budget: number;
-}>): AgentContext
-
-// ID creation
-createTestAgentId(): AgentId
-createDeterministicAgentId(seed: string): AgentId
-
-// Timing utilities
-wait(ms: number): Promise<void>
-createTimeout(ms: number, message?: string): Promise<never>
-measureTime<T>(fn: () => Promise<T>): Promise<{ result: T; duration: number }>
-
-// Test execution
-repeatTest<T>(times: number, testFn: (iteration: number) => Promise<T>): Promise<T[]>
-runInParallel<T>(testFns: Array<() => Promise<T>>): Promise<T[]>
-
-// Assertions
-expectToReject(promise: Promise<unknown>, expectedError?: string | RegExp): Promise<void>
-```
-
-### Result Assertions
-
-Assertions for the Result pattern.
-
-```typescript
-// Assertions
-assertSuccess<T>(result: Result<T>): void
-assertFailure<T>(result: Result<T>): void
-
-// Unwrapping
-unwrapSuccess<T>(result: Result<T>): T
-unwrapFailure<T>(result: Result<T>): Error
-```
-
-### TestApplication
-
-Simplified application builder for integration tests.
-
-```typescript
-class TestApplication {
-  static create(): TestApplication
-
-  useInMemoryDefaults(): this
-  useContainer(container: Container): this
-  useLogger(logger: Logger): this
-  usePlugin(plugin: Plugin, config?: unknown): this
-
-  build(): Promise<Application>
-}
-
-// Helper function
-createTestApp(): Promise<Application>
-```
-
-### EntityBuilder
-
-Fluent API for building test entities.
-
-```typescript
-class EntityBuilder<E extends Entity<any>> {
-  constructor(EntityClass: new (props: any, id: any) => E)
-
-  withProps(props: Partial<any>): this
-  withId(id: any): this
-  build(): E
-  buildMany(count: number): E[]
-}
-
-// Helper function
-entityBuilder<E extends Entity<any>>(
-  EntityClass: new (props: any, id: any) => E
-): EntityBuilder<E>
-```
-
-### DataFactory
-
-Factory for generating test data.
-
-```typescript
-class DataFactory {
-  static email(prefix?: string): Email
-  static string(prefix?: string): string
-  static number(min?: number, max?: number): number
-  static entityId<T extends string>(): EntityId<T>
-  static boolean(): boolean
-  static date(daysAgo?: number): Date
-  static pick<T>(array: T[]): T
-  static reset(): void
-}
-```
-
-## Best Practices
-
-### AI Agent Testing
-
-1. **Use MockLLMProvider for unit tests** - Avoid real API calls, keep tests fast and deterministic
-2. **Test multiple conversation turns** - Use `setResponses()` to test multi-turn interactions
-3. **Verify token usage** - Ensure cost tracking works correctly
-4. **Test error scenarios** - Use mock responses with errors to test error handling
-5. **Check call history** - Verify the agent calls the LLM with correct parameters
-
-### Result Pattern Testing
-
-1. **Always assert before accessing values** - Use `assertSuccess()` or `unwrapSuccess()`
-2. **Test both success and failure paths** - Ensure error handling works
-3. **Use type-safe assertions** - TypeScript narrows types after assertions
-
-### Integration Testing
-
-1. **Use TestApplication for full stack tests** - Test with real implementations
-2. **Clean up after tests** - Always call `app.stop()` in afterEach
-3. **Use in-memory defaults** - Faster tests without external dependencies
-4. **Test plugin integration** - Verify plugins work together correctly
+## License
 
-## Examples
+MIT - See [LICENSE](https://github.com/stratix-dev/stratix/blob/main/LICENSE) for details.
 
-See the `examples/` directory in the repository for complete examples:
+-
 
-- `examples/ai-agents/echo-agent/` - Simple agent testing
-- `examples/ai-agents/customer-support/` - Production agent with comprehensive tests
-- `examples/rest-api/` - Integration testing with TestApplication
+<div align="center">
 
-## License
+**[Stratix Framework](https://stratix-dev.github.io/stratix/)** - Build better software with proven patterns
 
-MIT
+</div>

package/dist/TestApplication.js

@@ -1,6 +1,6 @@
 import { ApplicationBuilder } from '@stratix/runtime';
 import { AwilixContainer } from '@stratix/di-awilix';
-import { ConsoleLogger } from '@stratix/core';
+import { ConsoleLogger } from '@stratix/runtime';
 import { LogLevel } from '@stratix/core';
 /**
  * Test Application Builder

package/dist/TestApplication.js.map

@@ -1 +1 @@
-{"version":3,"file":"TestApplication.js","sourceRoot":"","sources":["../src/TestApplication.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,eAAe;IAClB,OAAO,CAAqB;IAC5B,aAAa,CAAa;IAC1B,UAAU,CAAU;IAE5B;QACE,IAAI,CAAC,OAAO,GAAG,kBAAkB,CAAC,MAAM,EAAE,CAAC;IAC7C,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,MAAM;QACX,OAAO,IAAI,eAAe,EAAE,CAAC;IAC/B,CAAC;IAED;;;;;;OAMG;IACH,mBAAmB;QACjB,IAAI,CAAC,aAAa,GAAG,IAAI,eAAe,EAAE,CAAC;QAC3C,IAAI,CAAC,UAAU,GAAG,IAAI,aAAa,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;QAE/D,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAEzE,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,SAAoB;QAC/B,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC;QACrC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,MAAc;QACtB,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAC/B,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,MAAc,EAAE,MAAgB;QACxC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACvC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK;QACT,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACpC,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa;IACjC,MAAM,GAAG,GAAG,MAAM,eAAe,CAAC,MAAM,EAAE,CAAC,mBAAmB,EAAE,CAAC,KAAK,EAAE,CAAC;IAEzE,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC;IAElB,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"TestApplication.js","sourceRoot":"","sources":["../src/TestApplication.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,eAAe;IAClB,OAAO,CAAqB;IAC5B,aAAa,CAAa;IAC1B,UAAU,CAAU;IAE5B;QACE,IAAI,CAAC,OAAO,GAAG,kBAAkB,CAAC,MAAM,EAAE,CAAC;IAC7C,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,MAAM;QACX,OAAO,IAAI,eAAe,EAAE,CAAC;IAC/B,CAAC;IAED;;;;;;OAMG;IACH,mBAAmB;QACjB,IAAI,CAAC,aAAa,GAAG,IAAI,eAAe,EAAE,CAAC;QAC3C,IAAI,CAAC,UAAU,GAAG,IAAI,aAAa,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;QAE/D,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAEzE,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,SAAoB;QAC/B,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC;QACrC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,MAAc;QACtB,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAC/B,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,MAAc,EAAE,MAAgB;QACxC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACvC,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK;QACT,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACpC,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa;IACjC,MAAM,GAAG,GAAG,MAAM,eAAe,CAAC,MAAM,EAAE,CAAC,mBAAmB,EAAE,CAAC,KAAK,EAAE,CAAC;IAEzE,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC;IAElB,OAAO,GAAG,CAAC;AACb,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stratix/testing",
-  "version": "0.4.0",
+  "version": "0.4.4",
   "description": "Testing utilities for Stratix AI agents",
   "type": "module",
   "main": "./dist/index.js",
@@ -11,6 +11,12 @@
       "default": "./dist/index.js"
     }
   },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run || exit 0",
+    "test:watch": "vitest"
+  },
   "keywords": [
     "stratix",
     "ai",
@@ -19,9 +25,9 @@
     "mock"
   ],
   "dependencies": {
-    "@stratix/runtime": "0.4.0",
-    "@stratix/core": "0.4.0",
-    "@stratix/di-awilix": "0.4.0"
+    "@stratix/runtime": "workspace:*",
+    "@stratix/di-awilix": "workspace:*",
+    "@stratix/core": "workspace:*"
   },
   "devDependencies": {
     "@types/node": "^20.10.0",
@@ -35,7 +41,7 @@
     "url": "https://github.com/stratix-dev/stratix.git",
     "directory": "packages/testing"
   },
-  "homepage": "https://github.com/stratix-dev/stratix#readme",
+  "homepage": "https://stratix-dev.github.io/stratix/",
   "bugs": {
     "url": "https://github.com/stratix-dev/stratix/issues"
   },
@@ -48,11 +54,5 @@
   ],
   "engines": {
     "node": ">=18.0.0"
-  },
-  "scripts": {
-    "build": "tsc",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run || exit 0",
-    "test:watch": "vitest"
   }
-}
+}