re-uploading work

2026-02-04 17:46:30 -06:00
commit 3b14c65998
1388 changed files with 381262 additions and 0 deletions
--- a/docs/web-ui/web-ui-pack-testing.md
+++ b/docs/web-ui/web-ui-pack-testing.md
@@ -0,0 +1,440 @@
+# Web UI Pack Testing Integration
+
+## Overview
+
+The Attune web UI now includes comprehensive pack testing capabilities, allowing users to view test results, execute tests, and monitor pack quality through a visual interface.
+
+## Features
+
+### 1. Pack Detail Page - Test Results
+
+The pack detail page displays the latest test results and provides quick access to test history.
+
+**Location**: `/packs/{ref}`
+
+**Features**:
+- Latest test status badge (passed/failed/skipped)
+- Test summary (total, passed, failed, skipped)
+- Pass rate percentage
+- Test execution timestamp
+- "Run Tests" button for manual test execution
+- Toggle between latest results and test history
+
+### 2. Test Result Display Component
+
+**Component**: `PackTestResult`
+
+Displays detailed test execution results with:
+- Overall status indicator (passed/failed)
+- Test statistics (total, passed, failed, skipped)
+- Pass rate and duration
+- Expandable test suites
+- Individual test case results with error messages
+- stdout/stderr output for failed tests
+
+**Usage**:
+```tsx
+import PackTestResult from '@/components/packs/PackTestResult';
+
+<PackTestResult 
+  result={testResultData} 
+  showDetails={true} 
+/>
+```
+
+### 3. Test History Component
+
+**Component**: `PackTestHistory`
+
+Displays a paginated list of all test executions for a pack.
+
+**Features**:
+- Chronological list of test executions
+- Status badges for each execution
+- Trigger reason indicators (register, manual, ci, schedule)
+- Expandable details for each execution
+- Load more pagination
+- Date/time formatting
+- Duration display
+
+**Usage**:
+```tsx
+import PackTestHistory from '@/components/packs/PackTestHistory';
+
+<PackTestHistory
+  executions={testExecutions}
+  isLoading={false}
+  onLoadMore={() => loadNextPage()}
+  hasMore={hasMorePages}
+/>
+```
+
+### 4. Test Status Badge
+
+**Component**: `PackTestBadge`
+
+Compact status indicator showing test results.
+
+**Variants**:
+- `passed` - Green with checkmark
+- `failed` - Red with X
+- `skipped` - Gray with clock
+- Size options: `sm`, `md`, `lg`
+
+**Usage**:
+```tsx
+import PackTestBadge from '@/components/packs/PackTestBadge';
+
+<PackTestBadge
+  status="passed"
+  passed={76}
+  total={76}
+  size="md"
+  showCounts={true}
+/>
+```
+
+### 5. Pack Registration Page
+
+**Location**: `/packs/register`
+
+Form for registering packs from local filesystem with test control options.
+
+**Form Fields**:
+- **Pack Directory Path** (required) - Absolute path to pack directory
+- **Skip Tests** (checkbox) - Skip test execution during registration
+- **Force Registration** (checkbox) - Proceed even if tests fail or pack exists
+
+**Features**:
+- Real-time validation
+- Loading state during registration
+- Success/error messages
+- Automatic redirect to pack details on success
+- Info panel explaining registration process
+- Help section with guidance
+
+## API Integration
+
+### React Query Hooks
+
+#### `usePackLatestTest(packRef: string)`
+
+Fetches the latest test result for a pack.
+
+```tsx
+const { data: latestTest } = usePackLatestTest('core');
+
+// Returns: { data: PackTestExecution | null }
+```
+
+#### `usePackTestHistory(packRef: string, params)`
+
+Fetches paginated test history for a pack.
+
+```tsx
+const { data: testHistory } = usePackTestHistory('core', {
+  page: 1,
+  pageSize: 10
+});
+
+// Returns: { data: { items: PackTestExecution[], meta: PaginationMeta } }
+```
+
+#### `useExecutePackTests()`
+
+Mutation hook for executing pack tests.
+
+```tsx
+const executeTests = useExecutePackTests();
+
+await executeTests.mutateAsync('core');
+// Executes tests and invalidates test queries
+```
+
+#### `useRegisterPack()`
+
+Mutation hook for registering packs.
+
+```tsx
+const registerPack = useRegisterPack();
+
+await registerPack.mutateAsync({
+  path: '/path/to/pack',
+  force: false,
+  skipTests: false
+});
+```
+
+## User Workflows
+
+### View Test Results
+
+1. Navigate to `/packs`
+2. Click on a pack name
+3. View latest test results in the main section
+4. Click "View History" to see all test executions
+5. Click on any execution to expand details
+
+### Run Tests Manually
+
+1. Navigate to pack detail page
+2. Click "Run Tests" button in sidebar (or main section)
+3. Wait for test execution (button shows "Running Tests...")
+4. Results update automatically on completion
+5. View detailed results in the expanded test result component
+
+### Register a New Pack
+
+1. Navigate to `/packs`
+2. Click "+ Register Pack" button
+3. Fill in the pack directory path (e.g., `/home/user/packs/mypack`)
+4. Optionally check "Skip Tests" to bypass test execution
+5. Optionally check "Force Registration" to override conflicts
+6. Click "Register Pack"
+7. Wait for registration to complete
+8. View results and test outcomes
+9. Automatically redirected to pack details page
+
+### Register Pack with Tests Disabled
+
+Use this workflow during development:
+
+1. Navigate to `/packs/register`
+2. Enter pack path
+3. **Check "Skip Tests"**
+4. Click "Register Pack"
+5. Pack is registered without validation
+6. Later, manually run tests from pack detail page
+
+### Force Re-registration
+
+Use this to replace an existing pack:
+
+1. Navigate to `/packs/register`
+2. Enter pack path (same as existing pack)
+3. **Check "Force Registration"**
+4. Optionally check "Skip Tests" for faster iteration
+5. Click "Register Pack"
+6. Existing pack is deleted and replaced
+7. Tests run (unless skipped)
+
+## Visual Design
+
+### Color Scheme
+
+- **Passed Tests**: Green (`green-600`, `green-50`)
+- **Failed Tests**: Red (`red-600`, `red-50`)
+- **Skipped Tests**: Gray (`gray-600`, `gray-50`)
+- **Trigger Types**:
+  - Register: Blue
+  - Manual: Purple
+  - CI: Green
+  - Schedule: Yellow
+
+### Icons
+
+- **CheckCircle** - Passed tests
+- **XCircle** - Failed tests
+- **Clock** - Skipped tests
+- **AlertCircle** - Unknown/error state
+- **Play** - Run tests button
+- **Calendar** - Test execution date
+- **Clock** - Test duration
+- **ChevronDown/ChevronRight** - Expandable sections
+
+## Error Handling
+
+### Test Execution Failures
+
+When tests fail:
+- Error message displayed at top of page
+- Red alert banner with error details
+- Test results still stored (if execution completed)
+- User can retry by clicking "Run Tests" again
+
+### Registration Failures
+
+When registration fails:
+- Red alert box with error message
+- Form remains filled for corrections
+- Common errors:
+  - "Pack directory does not exist"
+  - "pack.yaml not found"
+  - "Pack already exists" (suggest using force)
+  - "Tests failed" (suggest using force or fixing tests)
+
+### Network Errors
+
+When API calls fail:
+- Error toast/alert
+- Retry button available
+- State preserved for manual retry
+
+## Accessibility
+
+- All interactive elements keyboard accessible
+- ARIA labels on icon buttons
+- Color is not the only indicator (icons + text)
+- Focus states clearly visible
+- Proper heading hierarchy
+- Screen reader friendly status messages
+
+## Performance Considerations
+
+### Data Fetching
+
+- `staleTime: 30000` (30 seconds) on test queries
+- Automatic refetch on window focus
+- Pagination for test history (10 items per page)
+- Query invalidation after test execution
+
+### Optimizations
+
+- Expandable sections to reduce initial render
+- Lazy loading of test details
+- Memoized components for large lists
+- Efficient re-renders with React Query
+
+## Responsive Design
+
+- Mobile-friendly layouts
+- Stacked columns on small screens
+- Touch-friendly tap targets (min 44x44px)
+- Horizontal scroll for wide tables
+- Collapsible sections for mobile
+
+## Future Enhancements
+
+### Planned Features
+
+1. **Real-time Test Execution**
+   - WebSocket updates during test runs
+   - Progress bar showing test completion
+   - Live stdout/stderr streaming
+
+2. **Test Comparison**
+   - Compare test results across versions
+   - Show performance regressions
+   - Highlight newly failing tests
+
+3. **Test Filtering**
+   - Filter by status (passed/failed/skipped)
+   - Filter by trigger type
+   - Date range filtering
+   - Search by test name
+
+4. **Test Analytics**
+   - Trend charts (pass rate over time)
+   - Flaky test detection
+   - Duration trends
+   - Test coverage metrics
+
+5. **Bulk Actions**
+   - Run tests for multiple packs
+   - Batch pack registration
+   - Export test results (CSV, JSON)
+
+6. **Notifications**
+   - Browser notifications for test completion
+   - Email alerts for test failures
+   - Slack/webhook integrations
+
+## Development Notes
+
+### File Structure
+
+```
+web/src/
+├── components/
+│   └── packs/
+│       ├── PackTestResult.tsx      # Detailed test result display
+│       ├── PackTestBadge.tsx       # Status badge component
+│       └── PackTestHistory.tsx     # Test history list
+├── hooks/
+│   └── usePackTests.ts             # React Query hooks
+└── pages/
+    └── packs/
+        ├── PackDetailPage.tsx      # Shows latest test results
+        └── PackRegisterPage.tsx    # Pack registration form
+```
+
+### Adding New Components
+
+1. Create component in `components/packs/`
+2. Export from component file
+3. Add to relevant pages
+4. Update types if needed
+5. Test build: `npm run build`
+
+### API Client Updates
+
+When backend API changes:
+
+1. Start API server: `cargo run --bin attune-api`
+2. Regenerate client: `cd web && npm run generate:api`
+3. Update hook imports if service names changed
+4. Update TypeScript types in hooks
+5. Test and update components
+
+### Testing
+
+Manual testing checklist:
+
+- [ ] Pack list page loads
+- [ ] Pack detail page shows test results
+- [ ] Test history displays correctly
+- [ ] Run tests button works
+- [ ] Pack registration form submits
+- [ ] Success/error messages display
+- [ ] Redirects work correctly
+- [ ] Test details expand/collapse
+- [ ] Status badges show correct colors
+- [ ] Mobile layout works
+
+## Troubleshooting
+
+### "Cannot read property 'result' of undefined"
+
+Test data not loaded yet. Add loading check:
+```tsx
+{latestTest?.data && <PackTestResult result={latestTest.data.result} />}
+```
+
+### Test history not updating
+
+Manually invalidate queries after test execution:
+```tsx
+queryClient.invalidateQueries({ queryKey: ['pack-tests', packRef] });
+```
+
+### Styling not applied
+
+- Check Tailwind classes are valid
+- Verify `lucide-react` is installed
+- Run `npm install` to ensure dependencies
+- Clear build cache: `rm -rf dist && npm run build`
+
+### API calls failing (401/403)
+
+- Check access token in localStorage
+- Verify token not expired
+- Log in again to refresh token
+- Check CORS configuration
+
+## Related Documentation
+
+- [Pack Testing Framework](./pack-testing-framework.md) - Overall testing design
+- [Pack Testing User Guide](./PACK_TESTING.md) - CLI and API usage
+- [Pack Testing API](./api-pack-testing.md) - API endpoint reference
+- [Pack Install Integration](./pack-install-testing.md) - Installation with testing
+- [Web UI Architecture](./web-ui-architecture.md) - Frontend architecture
+
+## Changelog
+
+- **2026-01-22**: Initial web UI integration
+  - Pack test result display component
+  - Test history component
+  - Status badge component
+  - Pack registration page
+  - React Query hooks for test data
+  - Integration with pack detail page