@elizaos/cli 1.0.9 → 1.0.10

package/templates/plugin-starter/src/__tests__/e2e/starter-plugin.ts

@@ -0,0 +1,320 @@
+import { type Content, type HandlerCallback } from '@elizaos/core';
+
+/**
+ * E2E (End-to-End) Test Suite for ElizaOS Plugins
+ * ================================================
+ *
+ * This file contains end-to-end tests that run within a real ElizaOS runtime environment.
+ * Unlike unit tests that test individual components in isolation, e2e tests validate
+ * the entire plugin behavior in a production-like environment.
+ *
+ * NOTE: The tests are properly structured and included in the plugin build.
+ * If the test runner is not detecting these tests, it may be looking at the wrong
+ * plugin name or there may be a test runner configuration issue. The tests are
+ * exported correctly through src/tests.ts and included in the plugin's tests array.
+ *
+ * HOW E2E TESTS WORK:
+ * -------------------
+ * 1. Tests are executed by the ElizaOS test runner using `elizaos test e2e`
+ * 2. Each test receives a real runtime instance with the plugin loaded
+ * 3. Tests can interact with the runtime just like in production
+ * 4. Tests throw errors to indicate failure (no assertion library needed)
+ *
+ * WRITING NEW E2E TESTS:
+ * ----------------------
+ * 1. Add a new test object to the `tests` array below
+ * 2. Each test must have:
+ *    - `name`: A unique identifier for the test
+ *    - `fn`: An async function that receives the runtime and performs the test
+ *
+ * Example structure:
+ * ```typescript
+ * {
+ *   name: 'my_new_test',
+ *   fn: async (runtime) => {
+ *     // Your test logic here
+ *     if (someCondition !== expected) {
+ *       throw new Error('Test failed: reason');
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * BEST PRACTICES:
+ * ---------------
+ * - Test real user scenarios, not implementation details
+ * - Use descriptive test names that explain what's being tested
+ * - Include clear error messages that help diagnose failures
+ * - Test both success and failure paths
+ * - Clean up any resources created during tests
+ *
+ * AVAILABLE RUNTIME METHODS:
+ * --------------------------
+ * - runtime.getService(type): Get a service instance
+ * - runtime.character: Access character configuration
+ * - runtime.models: Access AI models
+ * - runtime.db: Access database methods
+ * - runtime.actions: Access registered actions
+ * - runtime.providers: Access registered providers
+ *
+ * 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}`;
+
+interface Memory {
+  entityId: UUID;
+  roomId: UUID;
+  content: {
+    text: string;
+    source: string;
+    actions?: string[];
+  };
+}
+
+interface State {
+  values: Record<string, any>;
+  data: Record<string, any>;
+  text: string;
+}
+
+export const StarterPluginTestSuite: TestSuite = {
+  name: 'plugin_starter_test_suite',
+  description: 'E2E tests for the starter plugin',
+
+  tests: [
+    /**
+     * Basic Plugin Verification Test
+     * ------------------------------
+     * This test verifies that the plugin is properly loaded and initialized
+     * within the runtime environment.
+     */
+    {
+      name: 'example_test',
+      fn: async (runtime) => {
+        // Test the character name
+        if (runtime.character.name !== 'Eliza') {
+          throw new Error(
+            `Expected character name to be "Eliza" but got "${runtime.character.name}"`
+          );
+        }
+        // Verify the plugin is loaded properly
+        const service = runtime.getService('starter');
+        if (!service) {
+          throw new Error('Starter service not found');
+        }
+      },
+    },
+
+    /**
+     * Action Registration Test
+     * ------------------------
+     * Verifies that custom actions are properly registered with the runtime.
+     * This is important to ensure actions are available for the agent to use.
+     */
+    {
+      name: 'should_have_hello_world_action',
+      fn: async (runtime) => {
+        // Access actions through runtime.actions instead of getPlugin
+        const actionExists = runtime.actions?.some((a) => a.name === 'HELLO_WORLD');
+        if (!actionExists) {
+          throw new Error('Hello world action not found in runtime actions');
+        }
+      },
+    },
+
+    /**
+     * Hello World Action Response Test
+     * ---------------------------------
+     * This test demonstrates a complete scenario where:
+     * 1. The agent is asked to say "hello"
+     * 2. The HELLO_WORLD action is triggered
+     * 3. The agent responds with text containing "hello world"
+     *
+     * This is a key pattern for testing agent behaviors - you simulate
+     * a user message and verify the agent's response.
+     */
+    {
+      name: 'hello_world_action_test',
+      fn: async (runtime) => {
+        // Create a test message asking the agent to say hello
+        const testMessage: Memory = {
+          entityId: '12345678-1234-1234-1234-123456789012' as UUID,
+          roomId: '12345678-1234-1234-1234-123456789012' as UUID,
+          content: {
+            text: 'Can you say hello?',
+            source: 'test',
+            actions: ['HELLO_WORLD'], // Specify which action we expect to trigger
+          },
+        };
+
+        // Create a test state (can include context if needed)
+        const testState: State = {
+          values: {},
+          data: {},
+          text: '',
+        };
+
+        let responseText = '';
+        let responseReceived = false;
+
+        // Find the hello world action in runtime.actions
+        const helloWorldAction = runtime.actions?.find((a) => a.name === 'HELLO_WORLD');
+        if (!helloWorldAction) {
+          throw new Error('Hello world action not found in runtime actions');
+        }
+
+        // Create a callback that captures the agent's response
+        // This simulates how the runtime would handle the action's response
+        const callback: HandlerCallback = async (response: Content) => {
+          responseReceived = true;
+          responseText = response.text || '';
+
+          // Verify the response includes the expected action
+          if (!response.actions?.includes('HELLO_WORLD')) {
+            throw new Error('Response did not include HELLO_WORLD action');
+          }
+
+          // Return Promise<Memory[]> as required by the HandlerCallback interface
+          return Promise.resolve([]);
+        };
+
+        // Execute the action - this simulates the runtime calling the action
+        await helloWorldAction.handler(runtime, testMessage, testState, {}, callback);
+
+        // Verify we received a response
+        if (!responseReceived) {
+          throw new Error('Hello world action did not produce a response');
+        }
+
+        // Verify the response contains "hello world" (case-insensitive)
+        if (!responseText.toLowerCase().includes('hello world')) {
+          throw new Error(`Expected response to contain "hello world" but got: "${responseText}"`);
+        }
+
+        // Success! The agent responded with "hello world" as expected
+      },
+    },
+
+    /**
+     * Provider Functionality Test
+     * ---------------------------
+     * Tests that providers can supply data to the agent when needed.
+     * Providers are used to fetch external data or compute values.
+     */
+    {
+      name: 'hello_world_provider_test',
+      fn: async (runtime) => {
+        // Create a test message
+        const testMessage: Memory = {
+          entityId: '12345678-1234-1234-1234-123456789012' as UUID,
+          roomId: '12345678-1234-1234-1234-123456789012' as UUID,
+          content: {
+            text: 'What can you provide?',
+            source: 'test',
+          },
+        };
+
+        // Create a test state
+        const testState: State = {
+          values: {},
+          data: {},
+          text: '',
+        };
+
+        // Find the hello world provider in runtime.providers
+        const helloWorldProvider = runtime.providers?.find(
+          (p) => p.name === 'HELLO_WORLD_PROVIDER'
+        );
+        if (!helloWorldProvider) {
+          throw new Error('Hello world provider not found in runtime providers');
+        }
+
+        // Test the provider
+        const result = await helloWorldProvider.get(runtime, testMessage, testState);
+
+        if (result.text !== 'I am a provider') {
+          throw new Error(`Expected provider to return "I am a provider", got "${result.text}"`);
+        }
+      },
+    },
+
+    /**
+     * Service Lifecycle Test
+     * ----------------------
+     * Verifies that services can be started, accessed, and stopped properly.
+     * Services run background tasks or manage long-lived resources.
+     */
+    {
+      name: 'starter_service_test',
+      fn: async (runtime) => {
+        // Get the service from the runtime
+        const service = runtime.getService('starter');
+        if (!service) {
+          throw new Error('Starter service not found');
+        }
+
+        // Check service capability description
+        if (
+          service.capabilityDescription !==
+          'This is a starter service which is attached to the agent through the starter plugin.'
+        ) {
+          throw new Error('Incorrect service capability description');
+        }
+
+        // Test service stop method
+        await service.stop();
+      },
+    },
+
+    /**
+     * ADD YOUR CUSTOM TESTS HERE
+     * --------------------------
+     * To add a new test:
+     *
+     * 1. Copy this template:
+     * ```typescript
+     * {
+     *   name: 'your_test_name',
+     *   fn: async (runtime) => {
+     *     // Setup: Create any test data needed
+     *
+     *     // Action: Perform the operation you want to test
+     *
+     *     // Assert: Check the results
+     *     if (result !== expected) {
+     *       throw new Error(`Expected ${expected} but got ${result}`);
+     *     }
+     *   }
+     * }
+     * ```
+     *
+     * 2. Common test patterns:
+     *    - Test action responses to specific prompts
+     *    - Verify provider data under different conditions
+     *    - Check service behavior during lifecycle events
+     *    - Validate plugin configuration handling
+     *    - Test error cases and edge conditions
+     *
+     * 3. Tips:
+     *    - Use meaningful variable names
+     *    - Include helpful error messages
+     *    - Test one thing per test
+     *    - Consider both success and failure scenarios
+     */
+  ],
+};
+
+// Export a default instance of the test suite for the E2E test runner
+export default StarterPluginTestSuite;

package/templates/plugin-starter/src/__tests__/integration.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, it, spyOn, beforeEach, afterAll, beforeAll } from 'bun:test';
+import { starterPlugin, StarterService } from '../index';
+import { createMockRuntime, setupLoggerSpies, MockRuntime } from './test-utils';
+import { HandlerCallback, IAgentRuntime, Memory, State, UUID, logger } from '@elizaos/core';
+
+/**
+ * Integration tests demonstrate how multiple components of the plugin work together.
+ * Unlike unit tests that test individual functions in isolation, integration tests
+ * examine how components interact with each other.
+ *
+ * For example, this file shows how the HelloWorld action and HelloWorld provider
+ * interact with the StarterService and the plugin's core functionality.
+ */
+
+// Set up spies on logger
+beforeAll(() => {
+  setupLoggerSpies();
+});
+
+afterAll(() => {
+  // No global restore needed in bun:test
+});
+
+describe('Integration: HelloWorld Action with StarterService', () => {
+  let mockRuntime: MockRuntime;
+
+  beforeEach(() => {
+    // Create a service mock that will be returned by getService
+    const mockService = {
+      capabilityDescription:
+        'This is a starter service which is attached to the agent through the starter plugin.',
+      stop: () => Promise.resolve(),
+    };
+
+    // Create a mock runtime with a spied getService method
+    const getServiceImpl = (serviceType) => {
+      if (serviceType === 'starter') {
+        return mockService;
+      }
+      return null;
+    };
+
+    mockRuntime = createMockRuntime({
+      getService: getServiceImpl,
+    });
+  });
+
+  it('should handle HelloWorld action with StarterService available', async () => {
+    // Find the HelloWorld action
+    const helloWorldAction = starterPlugin.actions?.find((action) => action.name === 'HELLO_WORLD');
+    expect(helloWorldAction).toBeDefined();
+
+    // Create a mock message and state
+    const mockMessage: Memory = {
+      id: '12345678-1234-1234-1234-123456789012' as UUID,
+      roomId: '12345678-1234-1234-1234-123456789012' as UUID,
+      entityId: '12345678-1234-1234-1234-123456789012' as UUID,
+      agentId: '12345678-1234-1234-1234-123456789012' as UUID,
+      content: {
+        text: 'Hello world',
+        source: 'test',
+      },
+      createdAt: Date.now(),
+    };
+
+    const mockState: State = {
+      values: {},
+      data: {},
+      text: '',
+    };
+
+    // Create a mock callback to capture the response
+    const callbackCalls = [];
+    const callbackFn = (...args) => {
+      callbackCalls.push(args);
+    };
+
+    // Execute the action
+    await helloWorldAction?.handler(
+      mockRuntime as unknown as IAgentRuntime,
+      mockMessage,
+      mockState,
+      {},
+      callbackFn as HandlerCallback,
+      []
+    );
+
+    // Verify the callback was called with expected response
+    expect(callbackCalls.length).toBeGreaterThan(0);
+    if (callbackCalls.length > 0) {
+      expect(callbackCalls[0][0]).toMatchObject({
+        text: 'hello world!',
+        actions: ['HELLO_WORLD'],
+      });
+    }
+
+    // Get the service to ensure integration
+    const service = mockRuntime.getService('starter');
+    expect(service).toBeDefined();
+    expect(service?.capabilityDescription).toContain('starter service');
+  });
+});
+
+describe('Integration: Plugin initialization and service registration', () => {
+  it('should initialize the plugin and register the service', async () => {
+    // Create a fresh mock runtime with mocked registerService for testing initialization flow
+    const mockRuntime = createMockRuntime();
+
+    // Create and install a mock registerService
+    const registerServiceCalls = [];
+    mockRuntime.registerService = (type, service) => {
+      registerServiceCalls.push({ type, service });
+    };
+
+    // Run a minimal simulation of the plugin initialization process
+    if (starterPlugin.init) {
+      await starterPlugin.init(
+        { EXAMPLE_PLUGIN_VARIABLE: 'test-value' },
+        mockRuntime as unknown as IAgentRuntime
+      );
+
+      // Directly mock the service registration that happens during initialization
+      // because unit tests don't run the full agent initialization flow
+      if (starterPlugin.services) {
+        const StarterServiceClass = starterPlugin.services[0];
+        const serviceInstance = await StarterServiceClass.start(
+          mockRuntime as unknown as IAgentRuntime
+        );
+
+        // Register the Service class to match the core API
+        mockRuntime.registerService(StarterServiceClass);
+      }
+
+      // Now verify the service was registered with the runtime
+      expect(registerServiceCalls.length).toBeGreaterThan(0);
+    }
+  });
+});

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

@@ -0,0 +1,182 @@
+import { describe, expect, it, spyOn, beforeEach, afterEach, beforeAll, afterAll } from 'bun:test';
+import { starterPlugin, StarterService } from '../index';
+import { ModelType, logger } from '@elizaos/core';
+import dotenv from 'dotenv';
+
+// Setup environment variables
+dotenv.config();
+
+// Need to spy on logger for documentation
+beforeAll(() => {
+  spyOn(logger, 'info');
+  spyOn(logger, 'error');
+  spyOn(logger, 'warn');
+  spyOn(logger, 'debug');
+});
+
+afterAll(() => {
+  // No global restore needed in bun:test
+});
+
+// Create a real runtime for testing
+function createRealRuntime() {
+  const services = new Map();
+
+  // Create a real service instance if needed
+  const createService = (serviceType: string) => {
+    if (serviceType === StarterService.serviceType) {
+      return new StarterService({
+        character: {
+          name: 'Test Character',
+          system: 'You are a helpful assistant for testing.',
+        },
+      } as any);
+    }
+    return null;
+  };
+
+  return {
+    character: {
+      name: 'Test Character',
+      system: 'You are a helpful assistant for testing.',
+      plugins: [],
+      settings: {},
+    },
+    getSetting: (key: string) => null,
+    models: starterPlugin.models,
+    db: {
+      get: async (key: string) => null,
+      set: async (key: string, value: any) => true,
+      delete: async (key: string) => true,
+      getKeys: async (pattern: string) => [],
+    },
+    getService: (serviceType: string) => {
+      // Log the service request for debugging
+      logger.debug(`Requesting service: ${serviceType}`);
+
+      // Get from cache or create new
+      if (!services.has(serviceType)) {
+        logger.debug(`Creating new service: ${serviceType}`);
+        services.set(serviceType, createService(serviceType));
+      }
+
+      return services.get(serviceType);
+    },
+    registerService: (serviceType: string, service: any) => {
+      logger.debug(`Registering service: ${serviceType}`);
+      services.set(serviceType, service);
+    },
+  };
+}
+
+describe('Plugin Configuration', () => {
+  it('should have correct plugin metadata', () => {
+    expect(starterPlugin.name).toBe('plugin-starter');
+    expect(starterPlugin.description).toBe('Plugin starter for elizaOS');
+    expect(starterPlugin.config).toBeDefined();
+  });
+
+  it('should include the EXAMPLE_PLUGIN_VARIABLE in config', () => {
+    expect(starterPlugin.config).toHaveProperty('EXAMPLE_PLUGIN_VARIABLE');
+  });
+
+  it('should initialize properly', async () => {
+    const originalEnv = process.env.EXAMPLE_PLUGIN_VARIABLE;
+
+    try {
+      process.env.EXAMPLE_PLUGIN_VARIABLE = 'test-value';
+
+      // Initialize with config - using real runtime
+      const runtime = createRealRuntime();
+
+      if (starterPlugin.init) {
+        await starterPlugin.init({ EXAMPLE_PLUGIN_VARIABLE: 'test-value' }, runtime as any);
+        expect(true).toBe(true); // If we got here, init succeeded
+      }
+    } finally {
+      process.env.EXAMPLE_PLUGIN_VARIABLE = originalEnv;
+    }
+  });
+
+  it('should have a valid config', () => {
+    expect(starterPlugin.config).toBeDefined();
+    if (starterPlugin.config) {
+      // Check if the config has expected EXAMPLE_PLUGIN_VARIABLE property
+      expect(Object.keys(starterPlugin.config)).toContain('EXAMPLE_PLUGIN_VARIABLE');
+    }
+  });
+});
+
+describe('Plugin Models', () => {
+  it('should have TEXT_SMALL model defined', () => {
+    expect(starterPlugin.models?.[ModelType.TEXT_SMALL]).toBeDefined();
+    if (starterPlugin.models) {
+      expect(typeof starterPlugin.models[ModelType.TEXT_SMALL]).toBe('function');
+    }
+  });
+
+  it('should have TEXT_LARGE model defined', () => {
+    expect(starterPlugin.models?.[ModelType.TEXT_LARGE]).toBeDefined();
+    if (starterPlugin.models) {
+      expect(typeof starterPlugin.models[ModelType.TEXT_LARGE]).toBe('function');
+    }
+  });
+
+  it('should return a response from TEXT_SMALL model', async () => {
+    if (starterPlugin.models?.[ModelType.TEXT_SMALL]) {
+      const runtime = createRealRuntime();
+      const result = await starterPlugin.models[ModelType.TEXT_SMALL](runtime as any, {
+        prompt: 'test',
+      });
+
+      // Check that we get a non-empty string response
+      expect(result).toBeTruthy();
+      expect(typeof result).toBe('string');
+      expect(result.length).toBeGreaterThan(10);
+    }
+  });
+});
+
+describe('StarterService', () => {
+  it('should start the service', async () => {
+    const runtime = createRealRuntime();
+    const startResult = await StarterService.start(runtime as any);
+
+    expect(startResult).toBeDefined();
+    expect(startResult.constructor.name).toBe('StarterService');
+
+    // Test real functionality - check stop method is available
+    expect(typeof startResult.stop).toBe('function');
+  });
+
+  it('should stop the service', async () => {
+    const runtime = createRealRuntime();
+
+    // Register a real service first
+    const service = new StarterService(runtime as any);
+    runtime.registerService(StarterService.serviceType, service);
+
+    // Spy on the real service's stop method
+    const stopSpy = spyOn(service, 'stop');
+
+    // Call the static stop method
+    await StarterService.stop(runtime as any);
+
+    // Verify the service's stop method was called
+    expect(stopSpy).toHaveBeenCalled();
+  });
+
+  it('should throw an error when stopping a non-existent service', async () => {
+    const runtime = createRealRuntime();
+    // Don't register a service, so getService will return null
+
+    // We'll patch the getService function to ensure it returns null
+    const originalGetService = runtime.getService;
+    runtime.getService = () => null;
+
+    await expect(StarterService.stop(runtime as any)).rejects.toThrow('Starter service not found');
+
+    // Restore original getService function
+    runtime.getService = originalGetService;
+  });
+});