@elizaos/cli 1.0.8 → 1.0.10

package/templates/project-starter/src/__tests__/cypress/component/Accessibility.cy.tsx

@@ -0,0 +1,271 @@
+import React from 'react';
+import '../../../frontend/index.css';
+
+/**
+ * Example accessible form component
+ */
+const AccessibleForm: React.FC<{ onSubmit: (data: any) => void }> = ({ onSubmit }) => {
+  const [formData, setFormData] = React.useState({
+    name: '',
+    email: '',
+    message: '',
+  });
+  const [errors, setErrors] = React.useState<Record<string, string>>({});
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    const newErrors: Record<string, string> = {};
+
+    if (!formData.name) newErrors.name = 'Name is required';
+    if (!formData.email) newErrors.email = 'Email is required';
+    if (formData.email && !formData.email.includes('@')) {
+      newErrors.email = 'Please enter a valid email';
+    }
+
+    if (Object.keys(newErrors).length > 0) {
+      setErrors(newErrors);
+      return;
+    }
+
+    onSubmit(formData);
+  };
+
+  return (
+    <form onSubmit={handleSubmit} className="space-y-4 p-4">
+      <h1 className="text-2xl font-bold">Contact Agent</h1>
+
+      <div>
+        <label htmlFor="name" className="block text-sm font-medium mb-1">
+          Name{' '}
+          <span className="text-red-500" aria-label="required">
+            *
+          </span>
+        </label>
+        <input
+          id="name"
+          type="text"
+          value={formData.name}
+          onChange={(e) => setFormData({ ...formData, name: e.target.value })}
+          aria-invalid={!!errors.name}
+          aria-describedby={errors.name ? 'name-error' : undefined}
+          className="w-full px-3 py-2 border rounded-md"
+        />
+        {errors.name && (
+          <p id="name-error" role="alert" className="text-red-500 text-sm mt-1">
+            {errors.name}
+          </p>
+        )}
+      </div>
+
+      <div>
+        <label htmlFor="email" className="block text-sm font-medium mb-1">
+          Email{' '}
+          <span className="text-red-500" aria-label="required">
+            *
+          </span>
+        </label>
+        <input
+          id="email"
+          type="email"
+          value={formData.email}
+          onChange={(e) => setFormData({ ...formData, email: e.target.value })}
+          aria-invalid={!!errors.email}
+          aria-describedby={errors.email ? 'email-error' : undefined}
+          className="w-full px-3 py-2 border rounded-md"
+        />
+        {errors.email && (
+          <p id="email-error" role="alert" className="text-red-500 text-sm mt-1">
+            {errors.email}
+          </p>
+        )}
+      </div>
+
+      <div>
+        <label htmlFor="message" className="block text-sm font-medium mb-1">
+          Message
+        </label>
+        <textarea
+          id="message"
+          value={formData.message}
+          onChange={(e) => setFormData({ ...formData, message: e.target.value })}
+          rows={4}
+          className="w-full px-3 py-2 border rounded-md"
+        />
+      </div>
+
+      <button
+        type="submit"
+        className="px-4 py-2 bg-blue-500 text-white rounded-md hover:bg-blue-600 focus:outline-none focus:ring-2 focus:ring-blue-500"
+      >
+        Send Message
+      </button>
+    </form>
+  );
+};
+
+describe('Accessibility Tests', () => {
+  describe('Form Accessibility', () => {
+    it('should have proper labels for all form fields', () => {
+      cy.mount(<AccessibleForm onSubmit={cy.stub()} />);
+
+      // Check that labels are properly associated
+      cy.get('label[for="name"]').should('exist');
+      cy.get('label[for="email"]').should('exist');
+      cy.get('label[for="message"]').should('exist');
+
+      // Check that inputs have matching IDs
+      cy.get('input#name').should('exist');
+      cy.get('input#email').should('exist');
+      cy.get('textarea#message').should('exist');
+    });
+
+    it('should indicate required fields', () => {
+      cy.mount(<AccessibleForm onSubmit={cy.stub()} />);
+
+      // Check for required field indicators
+      cy.get('label[for="name"]').within(() => {
+        cy.get('[aria-label="required"]').should('exist');
+      });
+      cy.get('label[for="email"]').within(() => {
+        cy.get('[aria-label="required"]').should('exist');
+      });
+    });
+
+    it('should show accessible error messages', () => {
+      cy.mount(<AccessibleForm onSubmit={cy.stub()} />);
+
+      // Submit empty form
+      cy.get('button[type="submit"]').click();
+
+      // Check error messages have proper ARIA attributes
+      cy.get('#name-error').should('have.attr', 'role', 'alert');
+      cy.get('#email-error').should('have.attr', 'role', 'alert');
+
+      // Check inputs are marked as invalid
+      cy.get('input#name').should('have.attr', 'aria-invalid', 'true');
+      cy.get('input#email').should('have.attr', 'aria-invalid', 'true');
+
+      // Check aria-describedby links errors to inputs
+      cy.get('input#name').should('have.attr', 'aria-describedby', 'name-error');
+      cy.get('input#email').should('have.attr', 'aria-describedby', 'email-error');
+    });
+
+    it('should be keyboard navigable', () => {
+      cy.mount(<AccessibleForm onSubmit={cy.stub()} />);
+
+      // Verify all form elements can receive focus
+      cy.get('input#name').focus();
+      cy.focused().should('have.attr', 'id', 'name');
+
+      cy.get('input#email').focus();
+      cy.focused().should('have.attr', 'id', 'email');
+
+      cy.get('textarea#message').focus();
+      cy.focused().should('have.attr', 'id', 'message');
+
+      cy.get('button[type="submit"]').focus();
+      cy.focused().should('contain', 'Send Message');
+
+      // Verify tabindex is not preventing keyboard access
+      cy.get('input, textarea, button').should('not.have.attr', 'tabindex', '-1');
+    });
+
+    it('should have proper focus indicators', () => {
+      cy.mount(<AccessibleForm onSubmit={cy.stub()} />);
+
+      // Check focus ring on button
+      cy.get('button[type="submit"]').focus();
+      cy.get('button[type="submit"]').should('have.class', 'focus:ring-2');
+    });
+  });
+
+  describe('Color Contrast', () => {
+    it('should maintain readable contrast in dark mode', () => {
+      cy.mount(
+        <div className="dark bg-gray-900 p-4">
+          <h1 className="text-white">High Contrast Title</h1>
+          <p className="text-gray-300">Body text with good contrast</p>
+          <button className="bg-blue-600 text-white px-4 py-2">Action Button</button>
+        </div>
+      );
+
+      // Visual check - in real tests you might use cypress-axe
+      cy.get('h1').should('have.class', 'text-white');
+      cy.get('p').should('have.class', 'text-gray-300');
+    });
+  });
+
+  describe('Screen Reader Support', () => {
+    it('should have proper heading hierarchy', () => {
+      cy.mount(
+        <article>
+          <h1>Main Title</h1>
+          <section>
+            <h2>Section Title</h2>
+            <p>Content</p>
+            <h3>Subsection</h3>
+            <p>More content</p>
+          </section>
+        </article>
+      );
+
+      // Check heading hierarchy
+      cy.get('h1').should('have.length', 1);
+      cy.get('h2').should('exist');
+      cy.get('h3').should('exist');
+    });
+
+    it('should use semantic HTML elements', () => {
+      cy.mount(
+        <nav aria-label="Main navigation">
+          <ul>
+            <li>
+              <a href="#home">Home</a>
+            </li>
+            <li>
+              <a href="#about">About</a>
+            </li>
+          </ul>
+        </nav>
+      );
+
+      cy.get('nav').should('have.attr', 'aria-label', 'Main navigation');
+      cy.get('nav ul').should('exist');
+      cy.get('nav a').should('have.length', 2);
+    });
+  });
+});
+
+/**
+ * ACCESSIBILITY TESTING PATTERNS
+ *
+ * 1. ARIA ATTRIBUTES
+ *    - Test aria-label, aria-describedby, aria-invalid
+ *    - Verify role attributes for dynamic content
+ *    - Check live regions for updates
+ *
+ * 2. KEYBOARD NAVIGATION
+ *    - Test tab order
+ *    - Verify all interactive elements are reachable
+ *    - Check focus indicators
+ *
+ * 3. FORM ACCESSIBILITY
+ *    - Labels properly associated with inputs
+ *    - Error messages linked to fields
+ *    - Required fields indicated
+ *
+ * 4. COLOR CONTRAST
+ *    - Test in both light and dark modes
+ *    - Ensure text is readable
+ *    - Check focus indicators visibility
+ *
+ * 5. SCREEN READER SUPPORT
+ *    - Proper heading hierarchy
+ *    - Semantic HTML usage
+ *    - Alternative text for images
+ *
+ * TOOLS TO CONSIDER:
+ * - cypress-axe: Automated accessibility testing
+ * - cypress-tab: Better keyboard navigation testing
+ * - cypress-real-events: Test with real browser events
+ */

package/templates/project-starter/src/__tests__/cypress/component/ApiIntegration.cy.tsx

@@ -0,0 +1,220 @@
+import React from 'react';
+import '../../../frontend/index.css';
+
+/**
+ * Example component that fetches data from an API using React state
+ */
+const DataFetchingComponent: React.FC<{ agentId: string }> = ({ agentId }) => {
+  const [data, setData] = React.useState<any>(null);
+  const [isLoading, setIsLoading] = React.useState(true);
+  const [error, setError] = React.useState<Error | null>(null);
+
+  React.useEffect(() => {
+    const fetchData = async () => {
+      try {
+        setIsLoading(true);
+        setError(null);
+        const response = await fetch(`/api/agent/${agentId}/data`);
+        if (!response.ok) {
+          throw new Error('Failed to fetch data');
+        }
+        const result = await response.json();
+        setData(result);
+      } catch (err) {
+        setError(err as Error);
+      } finally {
+        setIsLoading(false);
+      }
+    };
+
+    fetchData();
+  }, [agentId]);
+
+  if (isLoading) return <div data-testid="loading">Loading agent data...</div>;
+  if (error)
+    return (
+      <div data-testid="error" className="text-red-500">
+        Error: {error.message}
+      </div>
+    );
+
+  return (
+    <div data-testid="data-display">
+      <h2>Agent: {agentId}</h2>
+      <ul>{data?.items?.map((item: string, index: number) => <li key={index}>{item}</li>)}</ul>
+    </div>
+  );
+};
+
+describe('API Integration Tests', () => {
+  describe('Data Fetching', () => {
+    it('should display loading state initially', () => {
+      cy.intercept('GET', '/api/agent/*/data', {
+        delay: 1000,
+        body: { items: [] },
+      });
+
+      cy.mount(<DataFetchingComponent agentId="test-123" />);
+      cy.get('[data-testid="loading"]').should('be.visible');
+      cy.get('[data-testid="loading"]').should('contain', 'Loading agent data...');
+    });
+
+    it('should fetch and display data successfully', () => {
+      const mockData = {
+        items: ['Action 1', 'Action 2', 'Action 3'],
+      };
+
+      cy.intercept('GET', '/api/agent/test-123/data', {
+        statusCode: 200,
+        body: mockData,
+      }).as('getAgentData');
+
+      cy.mount(<DataFetchingComponent agentId="test-123" />);
+
+      // Wait for the API call
+      cy.wait('@getAgentData');
+
+      // Check data is displayed
+      cy.get('[data-testid="data-display"]').should('be.visible');
+      cy.contains('Agent: test-123').should('be.visible');
+      cy.contains('Action 1').should('be.visible');
+      cy.contains('Action 2').should('be.visible');
+      cy.contains('Action 3').should('be.visible');
+    });
+
+    it('should handle API errors gracefully', () => {
+      cy.intercept('GET', '/api/agent/test-123/data', {
+        statusCode: 500,
+        body: { error: 'Internal Server Error' },
+      }).as('getAgentDataError');
+
+      cy.mount(<DataFetchingComponent agentId="test-123" />);
+
+      // Wait for the failed API call
+      cy.wait('@getAgentDataError');
+
+      // Check error is displayed
+      cy.get('[data-testid="error"]').should('be.visible');
+      cy.get('[data-testid="error"]').should('contain', 'Failed to fetch data');
+      cy.get('[data-testid="error"]').should('have.class', 'text-red-500');
+    });
+
+    it('should handle network errors', () => {
+      cy.intercept('GET', '/api/agent/test-123/data', {
+        forceNetworkError: true,
+      }).as('networkError');
+
+      cy.mount(<DataFetchingComponent agentId="test-123" />);
+
+      // Network errors might not trigger the wait, so we check for error directly
+      cy.get('[data-testid="error"]', { timeout: 10000 }).should('be.visible');
+    });
+
+    it('should refetch data when agent ID changes', () => {
+      const firstMockData = { items: ['First Agent Action'] };
+      const secondMockData = { items: ['Second Agent Action'] };
+
+      cy.intercept('GET', '/api/agent/agent-1/data', {
+        body: firstMockData,
+      }).as('getFirstAgent');
+
+      cy.intercept('GET', '/api/agent/agent-2/data', {
+        body: secondMockData,
+      }).as('getSecondAgent');
+
+      // Create a component that can change agent ID
+      const TestWrapper = () => {
+        const [agentId, setAgentId] = React.useState('agent-1');
+
+        return (
+          <>
+            <button onClick={() => setAgentId('agent-2')} data-testid="change-agent">
+              Change Agent
+            </button>
+            <DataFetchingComponent agentId={agentId} />
+          </>
+        );
+      };
+
+      cy.mount(<TestWrapper />);
+      cy.wait('@getFirstAgent');
+      cy.contains('First Agent Action').should('be.visible');
+
+      // Click to change agent
+      cy.get('[data-testid="change-agent"]').click();
+      cy.wait('@getSecondAgent');
+      cy.contains('Second Agent Action').should('be.visible');
+      cy.contains('First Agent Action').should('not.exist');
+    });
+  });
+
+  describe('Request Validation', () => {
+    it('should send correct headers', () => {
+      cy.intercept('GET', '/api/agent/*/data', (req) => {
+        expect(req.headers).to.have.property('accept');
+        req.reply({ items: [] });
+      }).as('checkHeaders');
+
+      cy.mount(<DataFetchingComponent agentId="test-123" />);
+      cy.wait('@checkHeaders');
+    });
+
+    it('should handle different response formats', () => {
+      // Test empty response
+      cy.intercept('GET', '/api/agent/empty/data', {
+        body: {},
+      }).as('emptyResponse');
+      cy.mount(<DataFetchingComponent agentId="empty" />);
+      cy.wait('@emptyResponse');
+      cy.get('[data-testid="data-display"]').should('be.visible');
+
+      // Test null items
+      cy.intercept('GET', '/api/agent/null/data', {
+        body: { items: null },
+      }).as('nullResponse');
+      // Create a new mount point for the second test
+      cy.then(() => {
+        cy.mount(<DataFetchingComponent agentId="null" />);
+        cy.wait('@nullResponse');
+        cy.get('[data-testid="data-display"]').should('be.visible');
+      });
+    });
+  });
+});
+
+/**
+ * API TESTING PATTERNS IN CYPRESS
+ *
+ * 1. INTERCEPTING REQUESTS
+ *    cy.intercept() allows you to:
+ *    - Mock responses
+ *    - Delay responses
+ *    - Force errors
+ *    - Validate request data
+ *
+ * 2. WAITING FOR REQUESTS
+ *    Use aliases with .as() and cy.wait() to ensure
+ *    requests complete before making assertions
+ *
+ * 3. ERROR SCENARIOS
+ *    Test all error cases:
+ *    - Server errors (4xx, 5xx)
+ *    - Network failures
+ *    - Timeout scenarios
+ *    - Invalid responses
+ *
+ * 4. LOADING STATES
+ *    Always test loading indicators
+ *    Use delays to ensure they appear
+ *
+ * 5. DATA UPDATES
+ *    Test how components handle:
+ *    - Prop changes
+ *    - Refetching
+ *    - Cache invalidation
+ *
+ * NOTE: This example uses plain React state instead of React Query
+ * to avoid dependency optimization issues in the test environment.
+ * In production, you would typically use React Query or similar
+ * libraries for better caching and request management.
+ */

package/templates/project-starter/src/__tests__/cypress/component/ExampleRoute.cy.tsx

@@ -0,0 +1,146 @@
+import React from 'react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import '../../../frontend/index.css';
+
+// We need to import the component directly since it's not exported
+// In a real scenario, you'd export the component from index.tsx
+const ExampleRoute = () => {
+  const [config, setConfig] = React.useState(window.ELIZA_CONFIG);
+
+  React.useEffect(() => {
+    document.documentElement.classList.add('dark');
+  }, []);
+
+  if (!config?.agentId) {
+    return (
+      <div className="p-4 text-center">
+        <div className="text-red-600 font-medium">Error: Agent ID not found</div>
+        <div className="text-sm text-gray-600 mt-2">
+          The server should inject the agent ID configuration.
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <QueryClientProvider client={new QueryClient()}>
+      <div>Hello {config.agentId}</div>
+    </QueryClientProvider>
+  );
+};
+
+describe('ExampleRoute Component Tests', () => {
+  describe('Component Rendering', () => {
+    it('should apply dark mode on mount', () => {
+      cy.mount(<ExampleRoute />);
+      cy.shouldBeDarkMode();
+    });
+
+    it('should show error when agent ID is missing', () => {
+      // Clear the config before mounting
+      cy.window().then((win) => {
+        win.ELIZA_CONFIG = undefined;
+      });
+
+      cy.mount(<ExampleRoute />);
+
+      // Check error message is displayed
+      cy.contains('Error: Agent ID not found').should('be.visible');
+      cy.contains('The server should inject the agent ID configuration.').should('be.visible');
+    });
+
+    it('should render correctly with agent ID', () => {
+      const testAgentId = '12345678-1234-1234-1234-123456789abc';
+
+      // Set config before mounting
+      cy.window().then((win) => {
+        win.ELIZA_CONFIG = {
+          agentId: testAgentId,
+          apiBase: 'http://localhost:3000',
+        };
+      });
+
+      cy.mount(<ExampleRoute />);
+
+      // Check that the agent ID is displayed
+      cy.contains(`Hello ${testAgentId}`).should('be.visible');
+    });
+  });
+
+  describe('Configuration Handling', () => {
+    it('should handle ELIZA_CONFIG changes', () => {
+      const initialAgentId = 'initial-agent-id';
+      const updatedAgentId = 'updated-agent-id';
+
+      // Set initial config
+      cy.window().then((win) => {
+        win.ELIZA_CONFIG = {
+          agentId: initialAgentId,
+          apiBase: 'http://localhost:3000',
+        };
+      });
+
+      cy.mount(<ExampleRoute />);
+      cy.contains(`Hello ${initialAgentId}`).should('be.visible');
+    });
+  });
+});
+
+/**
+ * TESTING PATTERNS FOR FRONTEND COMPONENTS IN ELIZAOS
+ *
+ * 1. COMPONENT ISOLATION
+ *    - Test components in isolation using cy.mount()
+ *    - Mock external dependencies (like API calls)
+ *    - Use data-testid attributes for reliable element selection
+ *
+ * 2. CONFIGURATION TESTING
+ *    - Always test with and without ELIZA_CONFIG
+ *    - Test with invalid/malformed configurations
+ *    - Verify error states and fallbacks
+ *
+ * 3. DARK MODE SUPPORT
+ *    - Ensure components work in both light and dark modes
+ *    - Use the custom shouldBeDarkMode() command
+ *
+ * 4. QUERY CLIENT TESTING
+ *    - Mock API responses for react-query
+ *    - Test loading, error, and success states
+ *    - Verify cache behavior
+ *
+ * 5. ACCESSIBILITY
+ *    - Use Testing Library queries (findByRole, findByText)
+ *    - Test keyboard navigation
+ *    - Verify ARIA attributes
+ *
+ * EXAMPLE TEST STRUCTURE:
+ *
+ * describe('Component Name', () => {
+ *   beforeEach(() => {
+ *     // Set up common test data
+ *     cy.setElizaConfig({ agentId: 'test-id', apiBase: 'http://localhost:3000' });
+ *   });
+ *
+ *   describe('Rendering', () => {
+ *     it('should render correctly', () => {
+ *       cy.mount(<Component />);
+ *       // Assertions
+ *     });
+ *   });
+ *
+ *   describe('User Interactions', () => {
+ *     it('should handle click events', () => {
+ *       cy.mount(<Component />);
+ *       cy.findByRole('button').click();
+ *       // Assertions
+ *     });
+ *   });
+ *
+ *   describe('API Integration', () => {
+ *     it('should fetch and display data', () => {
+ *       cy.intercept('GET', '/api/data', { fixture: 'mockData.json' });
+ *       cy.mount(<Component />);
+ *       // Assertions
+ *     });
+ *   });
+ * }); */

package/templates/project-starter/src/__tests__/cypress/component/PanelComponent.cy.tsx

@@ -0,0 +1,51 @@
+import React from 'react';
+import { panels } from '../../../frontend/index';
+
+describe('PanelComponent Tests', () => {
+  // Get the Panel component from the exported panels
+  const PanelComponent = panels[0]?.component;
+
+  describe('Panel Registration', () => {
+    it('should export panels array with correct structure', () => {
+      expect(panels).to.be.an('array');
+      expect(panels).to.have.length.greaterThan(0);
+
+      const panel = panels[0];
+      expect(panel).to.have.property('name', 'Example');
+      expect(panel).to.have.property('path', 'example');
+      expect(panel).to.have.property('component');
+      expect(panel).to.have.property('icon', 'Book');
+      expect(panel).to.have.property('public', false);
+      expect(panel).to.have.property('shortLabel', 'Example');
+    });
+  });
+
+  describe('Component Rendering', () => {
+    it('should render with agent ID', () => {
+      const testAgentId = 'test-agent-12345';
+
+      if (!PanelComponent) {
+        throw new Error('PanelComponent not found in panels export');
+      }
+
+      cy.mount(<PanelComponent agentId={testAgentId} />);
+
+      // Note: The component has a typo "Helllo" instead of "Hello"
+      cy.contains(`Helllo ${testAgentId}!`).should('be.visible');
+    });
+
+    it('should handle different agent IDs', () => {
+      const agentIds = ['agent-1', 'agent-2', '12345678-1234-1234-1234-123456789abc', 'test-agent'];
+
+      agentIds.forEach((agentId) => {
+        cy.mount(<PanelComponent agentId={agentId} />);
+        cy.contains(`Helllo ${agentId}!`).should('be.visible');
+      });
+    });
+
+    it('should render without crashing with empty agent ID', () => {
+      cy.mount(<PanelComponent agentId="" />);
+      cy.contains('Helllo !').should('be.visible');
+    });
+  });
+});