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)

sudo ./scripts/install-requirements.sh

Option 2: Install Node.js manually

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Verify installation:

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:

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

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:

npm run build

This should complete successfully and create a dist/ directory.

Step 3: Start Development Server

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:

./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

# 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