@elizaos/cli 1.3.2 → 1.4.2

package/dist/templates/plugin-quick-starter/src/__tests__/plugin.test.ts

@@ -9,6 +9,7 @@ import {
   ModelType,
   logger,
   EventType,
+  Action,
 } from '@elizaos/core';
 import dotenv from 'dotenv';
 import {
@@ -19,6 +20,38 @@ import {
   testFixtures,
 } from './test-utils';
 
+// Define proper interfaces for test mocking
+interface MockLoggerMethod {
+  calls?: any[];
+}
+
+interface MockLogger {
+  info: MockLoggerMethod;
+  error: MockLoggerMethod;
+  debug: MockLoggerMethod;
+  warn: MockLoggerMethod;
+}
+
+interface PluginConfig {
+  EXAMPLE_PLUGIN_VARIABLE?: string | number;
+}
+
+interface TestCallbackContent {
+  text?: string;
+  actions?: string[];
+  source?: string;
+}
+
+interface TestActionResult {
+  text?: string;
+  success: boolean;
+  data?: {
+    actions?: string[];
+    source?: string;
+  };
+  error?: Error;
+}
+
 // Setup environment variables
 dotenv.config();
 
@@ -79,7 +112,7 @@ describe('Plugin Configuration', () => {
     const invalidConfig = { EXAMPLE_PLUGIN_VARIABLE: 123 }; // Should be string
 
     if (starterPlugin.init) {
-      await expect(starterPlugin.init(invalidConfig as any, runtime)).rejects.toThrow(
+      await expect(starterPlugin.init(invalidConfig as PluginConfig, runtime)).rejects.toThrow(
         'Invalid plugin configuration'
       );
     }
@@ -88,21 +121,22 @@ describe('Plugin Configuration', () => {
 
 describe('Hello World Action', () => {
   let runtime: IAgentRuntime;
-  let helloWorldAction: any;
+  let helloWorldAction: Action;
 
   beforeEach(() => {
     runtime = createMockRuntime();
-    helloWorldAction = starterPlugin.actions?.[0];
+    helloWorldAction = starterPlugin?.actions?.[0] as Action;
     // Clear all spies before each test
-    (logger.info as any).calls = [];
-    (logger.error as any).calls = [];
-    (logger.debug as any).calls = [];
-    (logger.warn as any).calls = [];
+    const mockLogger = logger as unknown as MockLogger;
+    mockLogger.info.calls = [];
+    mockLogger.error.calls = [];
+    mockLogger.debug.calls = [];
+    mockLogger.warn.calls = [];
   });
 
   it('should have hello world action', () => {
     expect(helloWorldAction).toBeDefined();
-    expect(helloWorldAction?.name).toBe('HELLO_WORLD');
+    expect(helloWorldAction?.name).toBe('QUICK_ACTION');
   });
 
   it('should always validate messages (current implementation)', async () => {
@@ -180,9 +214,9 @@ describe('Hello World Action', () => {
       content: { text: 'say hello', source: 'test' },
     });
 
-    let callbackContent: any = null;
+    let callbackContent: TestCallbackContent | null = null;
     const callback: HandlerCallback = async (content: Content) => {
-      callbackContent = content;
+      callbackContent = content as TestCallbackContent;
       return [];
     };
 
@@ -191,12 +225,13 @@ describe('Hello World Action', () => {
     expect(result).toHaveProperty('text', 'Hello world!');
     expect(result).toHaveProperty('success', true);
     expect(result).toHaveProperty('data');
-    expect((result as any).data).toHaveProperty('actions', ['HELLO_WORLD']);
-    expect((result as any).data).toHaveProperty('source', 'test');
+    const typedResult = result as TestActionResult;
+    expect(typedResult.data).toHaveProperty('actions', ['QUICK_ACTION']);
+    expect(typedResult.data).toHaveProperty('source', 'test');
 
     expect(callbackContent).toEqual({
       text: 'Hello world!',
-      actions: ['HELLO_WORLD'],
+      actions: ['QUICK_ACTION'],
       source: 'test',
     });
   });
@@ -224,7 +259,8 @@ describe('Hello World Action', () => {
 
     expect(result).toHaveProperty('success', false);
     expect(result).toHaveProperty('error');
-    expect((result as any).error?.message).toBe('Callback error');
+    const typedResult = result as TestActionResult;
+    expect(typedResult.error?.message).toBe('Callback error');
     // Quick-starter plugin doesn't log errors
   });
 
@@ -278,7 +314,7 @@ describe('Hello World Provider', () => {
 
   it('should have hello world provider', () => {
     expect(provider).toBeDefined();
-    expect(provider?.name).toBe('HELLO_WORLD_PROVIDER');
+    expect(provider?.name).toBe('QUICK_PROVIDER');
   });
 
   it('should provide hello world data', async () => {
@@ -310,9 +346,11 @@ describe('Hello World Provider', () => {
     const result2 = await provider.get(runtime, message, state);
 
     // Text and structure should be consistent
+    expect(result1.text).toBeDefined();
+    expect(result2.text).toBeDefined();
     expect(result1.text).toBe(result2.text);
-    expect(result1.values).toEqual(result2.values);
-    expect(result1.data).toEqual(result2.data);
+    expect(result1.values || {}).toEqual(result2.values || {});
+    expect(result1.data || {}).toEqual(result2.data || {});
   });
 });
 

package/dist/templates/plugin-quick-starter/src/plugin.ts

@@ -51,9 +51,9 @@ const configSchema = z.object({
  * @property {Function} handler - Asynchronous function to handle the action and generate a response.
  * @property {Object[]} examples - An array of example inputs and expected outputs for the action.
  */
-const helloWorldAction: Action = {
-  name: 'HELLO_WORLD',
-  similes: ['GREET', 'SAY_HELLO'],
+const quickAction: Action = {
+  name: 'QUICK_ACTION',
+  similes: ['GREET', 'SAY_HELLO', 'HELLO_WORLD'],
   description: 'Responds with a simple hello world message',
 
   validate: async (
@@ -79,7 +79,7 @@ const helloWorldAction: Action = {
       if (callback) {
         await callback({
           text: response,
-          actions: ['HELLO_WORLD'],
+          actions: ['QUICK_ACTION'],
           source: message.content.source,
         });
       }
@@ -88,7 +88,7 @@ const helloWorldAction: Action = {
         text: response,
         success: true,
         data: {
-          actions: ['HELLO_WORLD'],
+          actions: ['QUICK_ACTION'],
           source: message.content.source,
         },
       };
@@ -112,7 +112,7 @@ const helloWorldAction: Action = {
         name: '{{name2}}',
         content: {
           text: 'hello world!',
-          actions: ['HELLO_WORLD'],
+          actions: ['QUICK_ACTION'],
         },
       },
     ],
@@ -123,8 +123,8 @@ const helloWorldAction: Action = {
  * Example Hello World Provider
  * This demonstrates the simplest possible provider implementation
  */
-const helloWorldProvider: Provider = {
-  name: 'HELLO_WORLD_PROVIDER',
+const quickProvider: Provider = {
+  name: 'QUICK_PROVIDER',
   description: 'A simple example provider',
 
   get: async (
@@ -235,31 +235,31 @@ export const starterPlugin: Plugin = {
     [EventType.MESSAGE_RECEIVED]: [
       async (params: MessagePayload) => {
         logger.debug('MESSAGE_RECEIVED event received');
-        logger.debug('Message:', params.message);
+        logger.debug({ message: params.message }, 'Message:');
       },
     ],
     [EventType.VOICE_MESSAGE_RECEIVED]: [
       async (params: MessagePayload) => {
         logger.debug('VOICE_MESSAGE_RECEIVED event received');
-        logger.debug('Message:', params.message);
+        logger.debug({ message: params.message }, 'Message:');
       },
     ],
     [EventType.WORLD_CONNECTED]: [
       async (params: WorldPayload) => {
         logger.debug('WORLD_CONNECTED event received');
-        logger.debug('World:', params.world);
+        logger.debug({ world: params.world }, 'World:');
       },
     ],
     [EventType.WORLD_JOINED]: [
       async (params: WorldPayload) => {
         logger.debug('WORLD_JOINED event received');
-        logger.debug('World:', params.world);
+        logger.debug({ world: params.world }, 'World:');
       },
     ],
   },
   services: [StarterService],
-  actions: [helloWorldAction],
-  providers: [helloWorldProvider],
+  actions: [quickAction],
+  providers: [quickProvider],
   // dependencies: ['@elizaos/plugin-knowledge'], <--- plugin dependencies go here (if requires another plugin)
 };
 

package/dist/templates/plugin-starter/README.md

@@ -34,89 +34,164 @@ elizaos test
 
 ## Testing
 
-ElizaOS provides a comprehensive testing structure for plugins:
+ElizaOS uses a dual testing approach that combines Bun's native test runner for component tests with a custom E2E test runner for integration testing within a live ElizaOS runtime.
 
 ### Test Structure
 
-- **Component Tests** (`__tests__/` directory):
-
-  - **Unit Tests**: Test individual functions/classes in isolation
-  - **Integration Tests**: Test how components work together
-  - Run with: `elizaos test component`
-
-- **End-to-End Tests** (`__tests__/e2e/` directory):
-
-  - Test the plugin within a full ElizaOS runtime
-  - Validate complete user scenarios with a real agent
-  - Run with: `elizaos test e2e`
+```
+src/
+  __tests__/              # All tests live inside src
+    *.test.ts            # Component tests (use Bun test runner)
+    e2e/                 # E2E tests (use ElizaOS test runner)
+      *.ts               # E2E test files
+      README.md          # E2E testing documentation
+```
 
-- **Running All Tests**:
-  - `elizaos test` runs both component and e2e tests
+### Two Types of Tests
 
-### Writing Tests
+#### 1. Component Tests (Bun Test Runner)
 
-Component tests use bun:test:
+- **Purpose**: Test individual functions/classes in isolation
+- **Location**: `src/__tests__/*.test.ts`
+- **Runner**: Bun's built-in test runner
+- **Command**: `bun test`
+- **Features**: Fast, isolated, uses mocks
 
 ```typescript
-// Unit test example (__tests__/plugin.test.ts)
+// Example: src/__tests__/plugin.test.ts
+import { describe, it, expect } from 'bun:test';
+import { starterPlugin } from '../plugin';
+
 describe('Plugin Configuration', () => {
   it('should have correct plugin metadata', () => {
     expect(starterPlugin.name).toBe('plugin-starter');
   });
 });
-
-// Integration test example (__tests__/integration.test.ts)
-describe('Integration: HelloWorld Action with StarterService', () => {
-  it('should handle HelloWorld action with StarterService', async () => {
-    // Test interactions between components
-  });
-});
 ```
 
-E2E tests run in a real ElizaOS runtime:
+#### 2. E2E Tests (ElizaOS Test Runner)
+
+- **Purpose**: Test plugin behavior within a real ElizaOS runtime
+- **Location**: `src/__tests__/e2e/*.ts`
+- **Runner**: ElizaOS custom test runner
+- **Command**: `elizaos test --type e2e`
+- **Features**: Real runtime, real database, full integration
 
 ```typescript
-// E2E test example (__tests__/e2e/starter-plugin.ts)
+// Example: src/__tests__/e2e/starter-plugin.ts
+import { type TestSuite } from '@elizaos/core';
+
 export const StarterPluginTestSuite: TestSuite = {
   name: 'plugin_starter_test_suite',
-  description: 'E2E tests for the starter plugin',
   tests: [
     {
       name: 'hello_world_action_test',
       fn: async (runtime) => {
-        // Simulate user asking agent to say hello
-        const testMessage = {
-          content: { text: 'Can you say hello?' }
-        };
-
-        // Execute action and capture response
-        const response = await helloWorldAction.handler(runtime, testMessage, ...);
-
-        // Verify agent responds with "hello world"
-        if (!response.text.includes('hello world')) {
-          throw new Error('Expected "hello world" in response');
+        // Test with real runtime - no mocks needed!
+        const action = runtime.actions.find((a) => a.name === 'HELLO_WORLD');
+        if (!action) {
+          throw new Error('Action not found');
         }
+        // Test real behavior...
       },
     },
   ],
 };
 ```
 
-#### Key E2E Testing Features:
+### Running Tests
+
+```bash
+# Run all tests (both component and E2E)
+elizaos test
+
+# Run only component tests (fast, for TDD)
+bun test
+# or
+elizaos test --type component
+
+# Run only E2E tests (slower, full integration)
+elizaos test --type e2e
+```
+
+### Key Differences
+
+| Aspect          | Component Tests      | E2E Tests               |
+| --------------- | -------------------- | ----------------------- |
+| **Runner**      | Bun test             | ElizaOS TestRunner      |
+| **Environment** | Mocked               | Real runtime            |
+| **Database**    | Mocked               | Real (PGLite)           |
+| **Speed**       | Fast (ms)            | Slower (seconds)        |
+| **Use Case**    | TDD, component logic | Integration, user flows |
+
+### E2E Test Integration
+
+E2E tests are integrated into your plugin by:
+
+1. **Creating the test suite** in `src/__tests__/e2e/`
+2. **Importing directly** in your plugin definition:
+
+```typescript
+// src/plugin.ts
+import { StarterPluginTestSuite } from './__tests__/e2e/starter-plugin';
+
+export const starterPlugin: Plugin = {
+  name: 'plugin-starter',
+  // ... other properties
+  tests: [StarterPluginTestSuite], // Direct import, no tests.ts needed
+};
+```
+
+### Writing Effective E2E Tests
+
+E2E tests receive a real `IAgentRuntime` instance, allowing you to:
+
+- Access real actions, providers, and services
+- Interact with the actual database
+- Test complete user scenarios
+- Validate plugin behavior in production-like conditions
+
+```typescript
+{
+  name: 'service_lifecycle_test',
+  fn: async (runtime) => {
+    // Get the real service
+    const service = runtime.getService('starter');
+    if (!service) {
+      throw new Error('Service not initialized');
+    }
+
+    // Test real behavior
+    await service.stop();
+    // Verify cleanup happened...
+  },
+}
+```
+
+### Best Practices
+
+1. **Use Component Tests for**:
+
+   - Algorithm logic
+   - Data transformations
+   - Input validation
+   - Error handling
 
-- **Real Runtime Environment**: Tests run with a fully initialized ElizaOS runtime
-- **Plugin Interaction**: Test how your plugin behaves with the actual agent
-- **Scenario Testing**: Validate complete user interactions, not just individual functions
-- **No Mock Required**: Access real services, actions, and providers
+2. **Use E2E Tests for**:
 
-#### Writing New E2E Tests:
+   - User scenarios
+   - Action execution flows
+   - Provider data integration
+   - Service lifecycle
+   - Plugin interactions
 
-1. Add a new test object to the `tests` array in your test suite
-2. Each test receives the runtime instance as a parameter
-3. Throw errors to indicate test failures (no assertion library needed)
-4. See the comprehensive documentation in `__tests__/e2e/starter-plugin.ts` for detailed examples
+3. **Test Organization**:
+   - Keep related tests together
+   - Use descriptive test names
+   - Include failure scenarios
+   - Document complex test setups
 
-The test utilities in `__tests__/test-utils.ts` provide mock objects and setup functions to simplify writing component tests.
+The comprehensive E2E test documentation in `src/__tests__/e2e/README.md` provides detailed examples and patterns for writing effective tests.
 
 ## Publishing & Continuous Development
 

package/dist/templates/plugin-starter/package.json

@@ -41,7 +41,7 @@
     "tsup.config.ts"
   ],
   "dependencies": {
-    "@elizaos/core": "1.3.2",
+    "@elizaos/core": "1.4.2",
     "@tanstack/react-query": "^5.80.7",
     "clsx": "^2.1.1",
     "tailwind-merge": "^3.3.1",
@@ -50,7 +50,7 @@
     "zod": "3.24.2"
   },
   "devDependencies": {
-    "@elizaos/cli": "1.3.2",
+    "@elizaos/cli": "1.4.2",
     "@tailwindcss/vite": "^4.1.10",
     "@vitejs/plugin-react-swc": "^3.10.2",
     "dotenv": "16.4.5",

package/dist/templates/plugin-starter/src/__tests__/e2e/README.md

@@ -2,9 +2,26 @@
 
 This directory contains end-to-end tests for the ElizaOS plugin starter template.
 
+## ElizaOS Testing Philosophy
+
+ElizaOS employs a dual testing strategy:
+
+1. **Component Tests** (`src/__tests__/*.test.ts`)
+
+   - Run with Bun's native test runner
+   - Fast, isolated tests using mocks
+   - Perfect for TDD and component logic
+   - Command: `bun test`
+
+2. **E2E Tests** (`src/__tests__/e2e/*.ts`)
+   - Run with ElizaOS custom test runner
+   - Real runtime with actual database (PGLite)
+   - Test complete user scenarios
+   - Command: `elizaos test --type e2e`
+
 ## Overview
 
-E2E tests run in a real ElizaOS runtime environment, allowing you to test your plugin's behavior as it would work in production.
+E2E tests run in a real ElizaOS runtime environment, allowing you to test your plugin's behavior as it would work in production. Unlike component tests, E2E tests provide access to a fully initialized runtime with all services, actions, and providers available.
 
 ## Test Structure
 
@@ -15,24 +32,42 @@ E2E tests run in a real ElizaOS runtime environment, allowing you to test your p
   - `hello_world_provider_test` - Tests provider functionality
   - `starter_service_test` - Tests service lifecycle
 
+## Integration with Plugin
+
+E2E tests are integrated directly into your plugin without the need for an intermediate export file:
+
+```typescript
+// src/plugin.ts
+import { StarterPluginTestSuite } from './__tests__/e2e/plugin-starter.e2e';
+
+export const myPlugin: Plugin = {
+  name: 'my-plugin',
+  // ... other properties
+  tests: [StarterPluginTestSuite], // Direct import!
+};
+```
+
 ## Running Tests
 
 ```bash
 # Run all tests (component + e2e)
-npm test
+elizaos test
 
-# Run only e2e tests
-npm run test:e2e
+# Run only e2e tests (slower, full integration)
+elizaos test --type e2e
 
-# Run only component tests
-npm run test:component
+# Run only component tests (fast, for TDD)
+bun test
+# or
+elizaos test --type component
 ```
 
 ## Implementation Details
 
-1. **Test Export**: Tests are exported through `src/tests.ts` to be included in the plugin build
+1. **Direct Import**: Tests are imported directly from the e2e test file - no intermediate export file needed
 2. **Plugin Integration**: The test suite is added to the plugin's `tests` array
-3. **Runtime Access**: Each test receives a real runtime instance with full access to:
+3. **Test Discovery**: The ElizaOS test runner automatically finds and executes tests from the plugin's `tests` array
+4. **Runtime Access**: Each test receives a real runtime instance with full access to:
    - Plugin actions, providers, and services
    - Agent character configuration
    - Database and model access
@@ -44,4 +79,4 @@ npm run test:component
 
 ## Writing New Tests
 
-See the comprehensive documentation at the top of `starter-plugin.ts` for detailed instructions on adding new tests.
+See the comprehensive documentation at the top of `plugin-starter.e2e.ts` for detailed instructions on adding new tests.

package/{templates/plugin-starter/src/__tests__/e2e/starter-plugin.ts → dist/templates/plugin-starter/src/__tests__/e2e/plugin-starter.e2e.ts}

@@ -1,4 +1,9 @@
-import { type Content, type HandlerCallback } from '@elizaos/core';
+import {
+  type Content,
+  type HandlerCallback,
+  type IAgentRuntime,
+  type TestSuite,
+} from '@elizaos/core';
 
 /**
  * E2E (End-to-End) Test Suite for ElizaOS Plugins
@@ -31,7 +36,7 @@ import { type Content, type HandlerCallback } from '@elizaos/core';
  * ```typescript
  * {
  *   name: 'my_new_test',
- *   fn: async (runtime) => {
+ *   fn: async (runtime: IAgentRuntime) => {
  *     // Your test logic here
  *     if (someCondition !== expected) {
  *       throw new Error('Test failed: reason');
@@ -60,16 +65,6 @@ import { type Content, type HandlerCallback } from '@elizaos/core';
  * For more details, see the ElizaOS documentation.
  */
 
-// Define a minimal TestSuite interface that matches what's needed
-interface TestSuite {
-  name: string;
-  description?: string;
-  tests: Array<{
-    name: string;
-    fn: (runtime: any) => Promise<any>;
-  }>;
-}
-
 // Define minimal interfaces for the types we need
 type UUID = `${string}-${string}-${string}-${string}-${string}`;
 
@@ -91,8 +86,6 @@ interface State {
 
 export const StarterPluginTestSuite: TestSuite = {
   name: 'plugin_starter_test_suite',
-  description: 'E2E tests for the starter plugin',
-
   tests: [
     /**
      * Basic Plugin Verification Test
@@ -102,7 +95,7 @@ export const StarterPluginTestSuite: TestSuite = {
      */
     {
       name: 'example_test',
-      fn: async (runtime) => {
+      fn: async (runtime: IAgentRuntime) => {
         // Test the character name
         if (runtime.character.name !== 'Eliza') {
           throw new Error(
@@ -125,7 +118,7 @@ export const StarterPluginTestSuite: TestSuite = {
      */
     {
       name: 'should_have_hello_world_action',
-      fn: async (runtime) => {
+      fn: async (runtime: IAgentRuntime) => {
         // Access actions through runtime.actions instead of getPlugin
         const actionExists = runtime.actions?.some((a) => a.name === 'HELLO_WORLD');
         if (!actionExists) {
@@ -147,7 +140,7 @@ export const StarterPluginTestSuite: TestSuite = {
      */
     {
       name: 'hello_world_action_test',
-      fn: async (runtime) => {
+      fn: async (runtime: IAgentRuntime) => {
         // Create a test message asking the agent to say hello
         const testMessage: Memory = {
           entityId: '12345678-1234-1234-1234-123456789012' as UUID,
@@ -215,7 +208,7 @@ export const StarterPluginTestSuite: TestSuite = {
      */
     {
       name: 'hello_world_provider_test',
-      fn: async (runtime) => {
+      fn: async (runtime: IAgentRuntime) => {
         // Create a test message
         const testMessage: Memory = {
           entityId: '12345678-1234-1234-1234-123456789012' as UUID,
@@ -258,7 +251,7 @@ export const StarterPluginTestSuite: TestSuite = {
      */
     {
       name: 'starter_service_test',
-      fn: async (runtime) => {
+      fn: async (runtime: IAgentRuntime) => {
         // Get the service from the runtime
         const service = runtime.getService('starter');
         if (!service) {
@@ -287,7 +280,7 @@ export const StarterPluginTestSuite: TestSuite = {
      * ```typescript
      * {
      *   name: 'your_test_name',
-     *   fn: async (runtime) => {
+     *   fn: async (runtime: IAgentRuntime) => {
      *     // Setup: Create any test data needed
      *
      *     // Action: Perform the operation you want to test