@majkapp/plugin-kit 3.2.1 → 3.3.1

package/docs/TESTING.md

@@ -0,0 +1,593 @@
+# Testing
+
+Test your plugin with `@majkapp/plugin-test`. Write unit tests for functions and UI tests for screens.
+
+## Setup
+
+```bash
+npm install --save-dev @majkapp/plugin-test
+```
+
+```json
+// package.json
+{
+  "scripts": {
+    "test:plugin:functions": "majk-test 'tests/plugin/functions/**/*.test.js'",
+    "test:plugin:ui": "majk-test 'tests/plugin/ui/**/*.test.js'",
+    "test:plugin": "majk-test 'tests/plugin/**/*.test.js'"
+  }
+}
+```
+
+## Function Testing
+
+### Basic Function Test
+
+```typescript
+// tests/plugin/functions/unit/health.test.js
+import { test } from '@majkapp/plugin-test';
+import { invoke, mock } from '@majkapp/plugin-test';
+import assert from 'assert';
+
+test('health check returns ok status', async () => {
+  // Create mock context
+  const context = mock().build();
+
+  // Invoke function
+  const result = await invoke('health', {}, { context });
+
+  // Assert output
+  assert.strictEqual(result.status, 'ok');
+  assert.ok(result.timestamp);
+  assert.ok(new Date(result.timestamp).getTime() > 0);
+});
+```
+
+Run test:
+```bash
+npx majk-test tests/plugin/functions/unit/health.test.js
+```
+
+Output:
+```
+✓ health check returns ok status (3ms)
+```
+
+### Test with Input Parameters
+
+```typescript
+// tests/plugin/functions/unit/analytics.test.js
+import { test, invoke, mock } from '@majkapp/plugin-test';
+import assert from 'assert';
+
+test('getAnalytics returns metrics for 7d period', async () => {
+  const context = mock()
+    .storage({
+      sessions: [
+        { userId: 'user1', duration: 300, timestamp: Date.now() - 86400000 },  // 1 day ago
+        { userId: 'user2', duration: 450, timestamp: Date.now() - 172800000 }, // 2 days ago
+        { userId: 'user1', duration: 600, timestamp: Date.now() - 259200000 }  // 3 days ago
+      ]
+    })
+    .build();
+
+  const result = await invoke('getAnalytics', { period: '7d' }, { context });
+
+  assert.strictEqual(result.period, '7d');
+  assert.strictEqual(result.metrics.activeUsers, 2);  // user1 and user2
+  assert.strictEqual(result.metrics.totalSessions, 3);
+  assert.strictEqual(result.metrics.avgDuration, 450);
+});
+
+test('getAnalytics filters old sessions for 24h period', async () => {
+  const context = mock()
+    .storage({
+      sessions: [
+        { userId: 'user1', duration: 300, timestamp: Date.now() - 86400000 },   // 1 day ago
+        { userId: 'user2', duration: 450, timestamp: Date.now() - 172800000 },  // 2 days ago - filtered out
+      ]
+    })
+    .build();
+
+  const result = await invoke('getAnalytics', { period: '24h' }, { context });
+
+  assert.strictEqual(result.metrics.activeUsers, 1);  // Only user1
+  assert.strictEqual(result.metrics.totalSessions, 1);
+});
+```
+
+### Test with MAJK Data
+
+```typescript
+// tests/plugin/functions/unit/dashboard.test.js
+import { test, invoke, mock } from '@majkapp/plugin-test';
+import assert from 'assert';
+
+test('getDashboardData aggregates MAJK entities', async () => {
+  const context = mock()
+    .withMajkData({
+      conversations: [
+        { id: 'conv1', title: 'Test 1', updatedAt: '2024-01-02T00:00:00Z', messages: [] },
+        { id: 'conv2', title: 'Test 2', updatedAt: '2024-01-01T00:00:00Z', messages: [] }
+      ],
+      todos: [
+        { id: 'todo1', title: 'Task 1', status: 'pending' },
+        { id: 'todo2', title: 'Task 2', status: 'completed' },
+        { id: 'todo3', title: 'Task 3', status: 'pending' }
+      ],
+      projects: [
+        { id: 'proj1', name: 'Project 1' }
+      ]
+    })
+    .build();
+
+  const result = await invoke('getDashboardData', {}, { context });
+
+  assert.strictEqual(result.conversations.total, 2);
+  assert.strictEqual(result.conversations.recent.length, 2);
+  assert.strictEqual(result.conversations.recent[0].id, 'conv1');  // Most recent first
+
+  assert.strictEqual(result.todos.total, 3);
+  assert.strictEqual(result.todos.pending, 2);
+  assert.strictEqual(result.todos.completed, 1);
+
+  assert.strictEqual(result.projects.total, 1);
+  assert.ok(result.timestamp);
+});
+```
+
+### Test Error Handling
+
+```typescript
+// tests/plugin/functions/unit/error-handling.test.js
+import { test, invoke, mock } from '@majkapp/plugin-test';
+import assert from 'assert';
+
+test('function handles missing data gracefully', async () => {
+  const context = mock()
+    .storage({})  // Empty storage
+    .build();
+
+  const result = await invoke('getAnalytics', { period: '7d' }, { context });
+
+  // Should return zero values, not crash
+  assert.strictEqual(result.metrics.activeUsers, 0);
+  assert.strictEqual(result.metrics.totalSessions, 0);
+  assert.strictEqual(result.metrics.avgDuration, 0);
+});
+
+test('function throws error for invalid input', async () => {
+  const context = mock().build();
+
+  try {
+    await invoke('getAnalytics', { period: 'invalid' }, { context });
+    assert.fail('Should have thrown error');
+  } catch (error) {
+    assert.ok(error.message.includes('period'));
+  }
+});
+```
+
+## UI Testing
+
+### Basic UI Test
+
+```typescript
+// tests/plugin/ui/unit/dashboard.test.js
+import { test } from '@majkapp/plugin-test';
+import { bot, mock } from '@majkapp/plugin-test';
+import assert from 'assert';
+
+test('dashboard displays health status', async () => {
+  // Mock function responses
+  const context = mock()
+    .withMockHandler('health', async () => ({
+      status: 'ok',
+      timestamp: new Date().toISOString()
+    }))
+    .withMockHandler('getAnalytics', async () => ({
+      period: '7d',
+      metrics: {
+        activeUsers: 42,
+        totalSessions: 150,
+        avgDuration: 320
+      }
+    }))
+    .build();
+
+  // Start browser bot
+  const b = await bot(context);
+
+  // Navigate to screen
+  await b.goto('/plugin-screens/my-plugin/dashboard');
+
+  // Wait for data to load - check data-majk-state
+  await b.waitForSelector('[data-majk-id="healthStatus"][data-majk-state="populated"]');
+
+  // Verify displayed values using data-majk-id
+  const healthText = await b.getText('[data-majk-id="healthStatus"]');
+  assert.ok(healthText.includes('ok'), `Expected 'ok' in "${healthText}"`);
+
+  const usersText = await b.getText('[data-majk-id="activeUsersCount"]');
+  assert.ok(usersText.includes('42'), `Expected '42' in "${usersText}"`);
+
+  // Take screenshot for visual verification
+  await b.screenshot('dashboard-loaded.png');
+
+  await b.close();
+});
+```
+
+### Test Button Clicks
+
+```typescript
+// tests/plugin/ui/unit/interactions.test.js
+import { test, bot, mock } from '@majkapp/plugin-test';
+import assert from 'assert';
+
+test('clicking refresh button updates health status', async () => {
+  let healthCallCount = 0;
+
+  const context = mock()
+    .withMockHandler('health', async () => {
+      healthCallCount++;
+      return {
+        status: 'ok',
+        timestamp: new Date().toISOString()
+      };
+    })
+    .build();
+
+  const b = await bot(context);
+  await b.goto('/plugin-screens/my-plugin/dashboard');
+
+  // Wait for initial load
+  await b.waitForSelector('[data-majk-id="refreshHealthButton"]');
+  assert.strictEqual(healthCallCount, 1, 'Initial health check should have been called');
+
+  // Click refresh button
+  await b.click('[data-majk-id="refreshHealthButton"]');
+
+  // Wait for loading state
+  await b.waitForSelector('[data-majk-id="refreshHealthButton"][data-majk-state="loading"]');
+
+  // Wait for data to reload
+  await b.waitForSelector('[data-majk-id="healthStatus"][data-majk-state="populated"]');
+
+  // Verify second health check was called
+  assert.strictEqual(healthCallCount, 2, 'Health check should have been called again');
+
+  await b.close();
+});
+```
+
+### Test State Changes
+
+```typescript
+// tests/plugin/ui/unit/toggle.test.js
+import { test, bot, mock } from '@majkapp/plugin-test';
+import assert from 'assert';
+
+test('toggle refresh button changes state', async () => {
+  const context = mock()
+    .withMockHandler('health', async () => ({
+      status: 'ok',
+      timestamp: new Date().toISOString()
+    }))
+    .build();
+
+  const b = await bot(context);
+  await b.goto('/plugin-screens/my-plugin/dashboard');
+
+  // Wait for page load
+  await b.waitForSelector('[data-majk-id="toggleRefreshButton"]');
+
+  // Initial state should be 'refreshing'
+  let state = await b.getAttribute('[data-majk-id="toggleRefreshButton"]', 'data-majk-state');
+  assert.strictEqual(state, 'refreshing');
+
+  // Click to pause
+  await b.click('[data-majk-id="toggleRefreshButton"]');
+
+  // Verify state changed to 'paused'
+  state = await b.getAttribute('[data-majk-id="toggleRefreshButton"]', 'data-majk-state');
+  assert.strictEqual(state, 'paused');
+
+  // Click again to resume
+  await b.click('[data-majk-id="toggleRefreshButton"]');
+
+  // Verify state changed back to 'refreshing'
+  state = await b.getAttribute('[data-majk-id="toggleRefreshButton"]', 'data-majk-state');
+  assert.strictEqual(state, 'refreshing');
+
+  await b.close();
+});
+```
+
+### Test List Rendering
+
+```typescript
+// tests/plugin/ui/unit/events-list.test.js
+import { test, bot, mock } from '@majkapp/plugin-test';
+import assert from 'assert';
+
+test('events list displays events', async () => {
+  const context = mock()
+    .withMockHandler('getEvents', async () => ({
+      events: [
+        {
+          id: 'evt1',
+          timestamp: '2024-01-01T00:00:00Z',
+          entityType: 'conversation',
+          eventType: 'created',
+          entityId: 'conv1',
+          entitySummary: { title: 'Test Conversation' }
+        },
+        {
+          id: 'evt2',
+          timestamp: '2024-01-02T00:00:00Z',
+          entityType: 'todo',
+          eventType: 'updated',
+          entityId: 'todo1',
+          entitySummary: { title: 'Test Todo' }
+        }
+      ],
+      count: 2
+    }))
+    .build();
+
+  const b = await bot(context);
+  await b.goto('/plugin-screens/my-plugin/events');
+
+  // Wait for events to load
+  await b.waitForSelector('[data-majk-id="eventsContainer"][data-majk-state="populated"]');
+
+  // Verify event items are rendered
+  const eventItems = await b.querySelectorAll('[data-majk-id="eventItem"]');
+  assert.strictEqual(eventItems.length, 2);
+
+  // Verify count display
+  const countText = await b.getText('[data-majk-id="displayedEventsCount"]');
+  assert.ok(countText.includes('2'));
+
+  await b.close();
+});
+
+test('events list shows empty state when no events', async () => {
+  const context = mock()
+    .withMockHandler('getEvents', async () => ({
+      events: [],
+      count: 0
+    }))
+    .build();
+
+  const b = await bot(context);
+  await b.goto('/plugin-screens/my-plugin/events');
+
+  // Wait for empty state
+  await b.waitForSelector('[data-majk-id="eventsContainer"][data-majk-state="empty"]');
+
+  // Verify empty message is shown
+  const emptyMessage = await b.isVisible('[data-majk-id="emptyMessage"]');
+  assert.ok(emptyMessage);
+
+  const text = await b.getText('[data-majk-id="emptyMessage"]');
+  assert.ok(text.includes('No events'));
+
+  await b.close();
+});
+```
+
+### Test Error States
+
+```typescript
+// tests/plugin/ui/unit/error-handling.test.js
+import { test, bot, mock } from '@majkapp/plugin-test';
+import assert from 'assert';
+
+test('dashboard displays error when health check fails', async () => {
+  const context = mock()
+    .withMockHandler('health', async () => {
+      throw new Error('Health check failed');
+    })
+    .build();
+
+  const b = await bot(context);
+  await b.goto('/plugin-screens/my-plugin/dashboard');
+
+  // Wait for error state
+  await b.waitForSelector('[data-majk-id="errorMessage"][data-majk-state="error"]');
+
+  // Verify error message is displayed
+  const errorText = await b.getText('[data-majk-id="errorMessage"]');
+  assert.ok(errorText.includes('Health check failed'));
+
+  await b.screenshot('dashboard-error-state.png');
+
+  await b.close();
+});
+```
+
+## Bot API Reference
+
+```typescript
+const b = await bot(context);
+
+// Navigation
+await b.goto('/plugin-screens/my-plugin/dashboard');
+
+// Waiting
+await b.waitForSelector('[data-majk-id="element"]');
+await b.waitForSelector('[data-majk-id="element"][data-majk-state="populated"]');
+
+// Clicking
+await b.click('[data-majk-id="button"]');
+
+// Text content
+const text = await b.getText('[data-majk-id="element"]');
+
+// Attributes
+const state = await b.getAttribute('[data-majk-id="element"]', 'data-majk-state');
+
+// Visibility
+const isVisible = await b.isVisible('[data-majk-id="element"]');
+
+// Query elements
+const elements = await b.querySelectorAll('[data-majk-id="item"]');
+
+// Screenshots
+await b.screenshot('test-result.png');  // Saved to tests/__screenshots__/
+
+// Cleanup
+await b.close();
+```
+
+## Mock API Reference
+
+```typescript
+// Basic mock
+const context = mock().build();
+
+// With storage
+const context = mock()
+  .storage({
+    key1: 'value1',
+    key2: { nested: 'data' }
+  })
+  .build();
+
+// With MAJK data
+const context = mock()
+  .withMajkData({
+    conversations: [{ id: 'conv1', title: 'Test' }],
+    todos: [{ id: 'todo1', status: 'pending' }],
+    projects: [{ id: 'proj1', name: 'Project' }],
+    teammates: [{ id: 'tm1', name: 'Assistant' }],
+    mcpServers: [{ id: 'mcp1', name: 'Server' }]
+  })
+  .build();
+
+// With mock function handlers (for UI tests)
+const context = mock()
+  .withMockHandler('health', async (input) => ({
+    status: 'ok',
+    timestamp: new Date().toISOString()
+  }))
+  .withMockHandler('getAnalytics', async (input) => ({
+    period: input.period,
+    metrics: { activeUsers: 42, totalSessions: 150, avgDuration: 320 }
+  }))
+  .build();
+
+// Combined
+const context = mock()
+  .storage({ sessions: [] })
+  .withMajkData({ conversations: [] })
+  .withMockHandler('health', async () => ({ status: 'ok' }))
+  .build();
+```
+
+## Project Structure
+
+```
+my-plugin/
+├── tests/
+│   └── plugin/
+│       ├── functions/
+│       │   └── unit/
+│       │       ├── health.test.js
+│       │       ├── analytics.test.js
+│       │       └── dashboard-data.test.js
+│       └── ui/
+│           └── unit/
+│               ├── dashboard.test.js
+│               ├── events-list.test.js
+│               └── interactions.test.js
+└── __screenshots__/           # Generated by UI tests
+    ├── dashboard-loaded.png
+    └── error-state.png
+```
+
+## Running Tests
+
+```bash
+# All tests
+npm run test:plugin
+
+# Function tests only
+npm run test:plugin:functions
+
+# UI tests only
+npm run test:plugin:ui
+
+# Single test file
+npx majk-test tests/plugin/functions/unit/health.test.js
+
+# Watch mode (re-run on file change)
+npx majk-test --watch 'tests/plugin/**/*.test.js'
+```
+
+## Best Practices
+
+### 1. Use data-majk-* Attributes
+
+```typescript
+// Good: Testable with data-majk-id
+<button data-majk-id="saveButton">Save</button>
+
+// Bad: Hard to test reliably
+<button className="btn-save">Save</button>
+```
+
+### 2. Test All States
+
+```typescript
+test('component handles loading state', async () => { /* ... */ });
+test('component handles empty state', async () => { /* ... */ });
+test('component handles populated state', async () => { /* ... */ });
+test('component handles error state', async () => { /* ... */ });
+```
+
+### 3. Verify Mock Calls
+
+```typescript
+test('function is called with correct parameters', async () => {
+  let capturedInput;
+
+  const context = mock()
+    .withMockHandler('myFunction', async (input) => {
+      capturedInput = input;  // Capture input for verification
+      return { success: true };
+    })
+    .build();
+
+  const b = await bot(context);
+  await b.goto('/plugin-screens/my-plugin/page');
+  await b.click('[data-majk-id="submitButton"]');
+
+  await b.waitForSelector('[data-majk-id="success"]');
+
+  assert.deepStrictEqual(capturedInput, { expectedData: 'value' });
+
+  await b.close();
+});
+```
+
+### 4. Take Screenshots for Visual Verification
+
+```typescript
+test('dashboard renders correctly', async () => {
+  const b = await bot(context);
+  await b.goto('/plugin-screens/my-plugin/dashboard');
+  await b.waitForSelector('[data-majk-id="dashboardContainer"][data-majk-state="populated"]');
+
+  await b.screenshot('dashboard-populated.png');
+
+  await b.close();
+});
+```
+
+## Next Steps
+
+Run `npx @majkapp/plugin-test` - Complete testing reference
+Run `npx @majkapp/plugin-kit --config` - Set up your project for testing