attune/docs/web-ui/web-ui-pack-testing.md

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:

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:

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:

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.

const { data: latestTest } = usePackLatestTest('core');

// Returns: { data: PackTestExecution | null }

usePackTestHistory(packRef: string, params)

Fetches paginated test history for a pack.

const { data: testHistory } = usePackTestHistory('core', {
  page: 1,
  pageSize: 10
});

// Returns: { data: { items: PackTestExecution[], meta: PaginationMeta } }

useExecutePackTests()

Mutation hook for executing pack tests.

const executeTests = useExecutePackTests();

await executeTests.mutateAsync('core');
// Executes tests and invalidates test queries

useRegisterPack()

Mutation hook for registering packs.

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:

{latestTest?.data && <PackTestResult result={latestTest.data.result} />}

Test history not updating

Manually invalidate queries after test execution:

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 - Overall testing design
• Pack Testing User Guide - CLI and API usage
• Pack Testing API - API endpoint reference
• Pack Install Integration - Installation with testing
• Web UI Architecture - 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