calypso/docs/FRONTEND-TESTING-GUIDE.md

# Frontend Testing Guide

## Prerequisites

### 1. Install Node.js

The frontend requires Node.js 18+ and npm. Install it using one of these methods:

**Option 1: Use the install script (Recommended)**
```bash
sudo ./scripts/install-requirements.sh
```

**Option 2: Install Node.js manually**
```bash
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
```

**Verify installation:**
```bash
node --version  # Should show v20.x or higher
npm --version   # Should show 10.x or higher
```

### 2. Start Backend API

The frontend needs the backend API running:

```bash
cd backend
export CALYPSO_DB_PASSWORD="calypso123"
export CALYPSO_JWT_SECRET="test-jwt-secret-key-minimum-32-characters-long"
go run ./cmd/calypso-api -config config.yaml.example
```

The backend should be running on `http://localhost:8080`

---

## Testing Steps

### Step 1: Install Frontend Dependencies

```bash
cd frontend
npm install
```

This will install all required packages (React, Vite, TypeScript, etc.)

### Step 2: Verify Build

Test that the project compiles without errors:

```bash
npm run build
```

This should complete successfully and create a `dist/` directory.

### Step 3: Start Development Server

```bash
npm run dev
```

The frontend will start on `http://localhost:3000`

### Step 4: Test in Browser

1. **Open Browser**: Navigate to `http://localhost:3000`

2. **Login Page**:
   - Should see the login form
   - Try logging in with test credentials:
     - Username: `admin`
     - Password: `admin123` (or whatever password you set)

3. **Dashboard**:
   - After login, should see the dashboard
   - Check system health status
   - Verify overview cards show data
   - Check quick actions work

4. **Storage Page**:
   - Navigate to Storage from sidebar
   - Should see repositories, disks, and volume groups
   - Verify data displays correctly
   - Check capacity bars render

5. **Alerts Page**:
   - Navigate to Alerts from sidebar
   - Should see alert list
   - Test filtering (All / Unacknowledged)
   - Try acknowledge/resolve actions

---

## Automated Testing Script

Use the provided test script:

```bash
./scripts/test-frontend.sh
```

This script will:
- ✅ Check Node.js installation
- ✅ Verify backend API is running
- ✅ Install dependencies (if needed)
- ✅ Test build
- ✅ Provide instructions for starting dev server

---

## Expected Behavior

### Login Flow
1. User enters credentials
2. On success: Redirects to dashboard, token stored
3. On failure: Shows error message

### Dashboard
- System health indicator (green/yellow/red)
- Overview cards with real data:
  - Storage repositories count
  - Active alerts count
  - iSCSI targets count
  - Running tasks count
- Quick action buttons
- Recent alerts preview

### Storage Page
- Repository list with:
  - Name and description
  - Capacity usage bars
  - Status indicators
- Physical disks list
- Volume groups list

### Alerts Page
- Alert cards with severity colors
- Filter buttons (All / Unacknowledged)
- Acknowledge and Resolve buttons
- Relative time display

---

## Troubleshooting

### Issue: "Node.js not found"
**Solution**: Install Node.js using the install script or manually (see Prerequisites)

### Issue: "Cannot connect to API"
**Solution**: 
- Ensure backend is running on `http://localhost:8080`
- Check backend logs for errors
- Verify database is running and accessible

### Issue: "401 Unauthorized" errors
**Solution**:
- Check if user exists in database
- Verify password is correct (may need to update with Argon2id hash)
- Check JWT secret is set correctly

### Issue: "Build fails with TypeScript errors"
**Solution**:
- Check TypeScript version: `npm list typescript`
- Verify all imports are correct
- Check for missing dependencies

### Issue: "Blank page after login"
**Solution**:
- Check browser console for errors
- Verify API responses are correct
- Check network tab for failed requests

---

## Manual Testing Checklist

- [ ] Login page displays correctly
- [ ] Login with valid credentials works
- [ ] Login with invalid credentials shows error
- [ ] Dashboard loads after login
- [ ] System health status displays
- [ ] Overview cards show data
- [ ] Navigation sidebar works
- [ ] Storage page displays repositories
- [ ] Storage page displays disks
- [ ] Storage page displays volume groups
- [ ] Alerts page displays alerts
- [ ] Alert filtering works
- [ ] Alert acknowledge works
- [ ] Alert resolve works
- [ ] Logout works
- [ ] Protected routes redirect to login when not authenticated

---

## Next Steps After Testing

Once basic functionality is verified:
1. Continue building remaining pages (Tape Libraries, iSCSI, Tasks, System, IAM)
2. Add WebSocket integration for real-time updates
3. Enhance UI with more components
4. Add error boundaries
5. Implement loading states
6. Add toast notifications

---

## Quick Test Commands

```bash
# Check Node.js
node --version && npm --version

# Install dependencies
cd frontend && npm install

# Test build
npm run build

# Start dev server
npm run dev

# In another terminal, check backend
curl http://localhost:8080/api/v1/health
```

---

## Notes

- The frontend dev server proxies API requests to `http://localhost:8080`
- WebSocket connections will use `ws://localhost:8080/ws`
- Authentication tokens are stored in localStorage
- The frontend will automatically redirect to login on 401 errors