Testing Guide

Purpose and Scope

This document provides guidance on testing the TalentSync platform, including manual testing procedures, API endpoint validation, and recommended testing strategies. For information about local development setup, see Local Development Setup. For API endpoint specifications, see API Documentation.

Current Testing Infrastructure

Testing Framework Status

The TalentSync codebase currently relies primarily on manual testing and validation rather than automated test suites. This section documents the available testing mechanisms and recommended practices.

Frontend Testing:

• No automated test framework currently configured in frontend/package.json1-98
• ESLint configured for code quality checks via npm run lint
• TypeScript provides compile-time type checking

Backend Testing:

• No automated test framework currently configured in backend/app/main.py1-149
• FastAPI's built-in interactive documentation (/docs and /redoc) provides manual API testing

Available Validation Tools:

Manual Testing Procedures

Backend API Testing

Using FastAPI Interactive Documentation

The FastAPI backend provides automatic interactive API documentation accessible at two endpoints:

1. Swagger UI: http://localhost:8000/docs
2. ReDoc: http://localhost:8000/redoc

Testing Workflow:

1. Start the backend server (see Local Development Setup)
2. Navigate to http://localhost:8000/docs
3. Expand any endpoint to view parameters and request/response schemas
4. Click "Try it out" to execute requests
5. Review response status codes and JSON payloads

Testing Individual API Routes

Resume Analysis Service:

• Endpoint: POST /api/v1/analyze_resume
• Router: backend/app/main.py102-108
• Test with: PDF, DOCX, or TXT resume files
• Expected: JSON response with comprehensive analysis data

Cold Mail Generator:

• v1 Endpoint: POST /api/v1/cold_mail (file-based)
• v2 Endpoint: POST /api/v2/cold_mail (text-based)
• Routers: backend/app/main.py62-84
• Test with: Resume text/file + recipient details
• Expected: Generated email content

ATS Evaluation:

• v1 Endpoint: POST /api/v1/ats (file-based)
• v2 Endpoint: POST /api/v2/ats (text-based)
• Routers: backend/app/main.py118-132
• Test with: Resume + job description
• Expected: ATS score and improvement suggestions

Hiring Assistant:

• v1 Endpoint: POST /api/v1/hiring_assistant (file-based)
• v2 Endpoint: POST /api/v2/hiring_assistant (text-based)
• Routers: backend/app/main.py86-100
• Test with: Resume + interview question
• Expected: Generated answer framework

Frontend Testing

Browser-Based Manual Testing

Development Environment Testing:

Production Build Testing:

Key User Flows to Test

Authentication Flow:

1. Navigate to /auth
2. Test registration with email verification
3. Test login with credentials
4. Test OAuth (Google/GitHub)
5. Test password reset flow
6. Verify role selection after first login

Resume Analysis Flow:

1. Login as job seeker
2. Navigate to /dashboard/seeker
3. Upload resume (PDF/DOCX/TXT)
4. Enter custom name
5. Verify analysis appears in 4-8 seconds
6. Check detailed analysis page
7. Verify data persists in localStorage

Cold Mail Generation Flow:

1. Complete resume analysis first
2. Navigate to /dashboard/cold-mail
3. Select analyzed resume
4. Enter recipient details
5. Verify email generation
6. Test edit functionality

Database Testing

Prisma Schema Validation

Check schema integrity:

Generate Prisma Client:

Run migrations:

Seed database with test data:

The seed script is defined in frontend/package.json14-16 and executes the seeding logic defined in the Prisma seed configuration.

Database State Inspection

Access Prisma Studio:

This opens a web-based GUI at http://localhost:5555 for inspecting and manipulating database records.

PWA Testing

Service Worker Validation

Testing in Development: PWA features are disabled in development mode as configured in frontend/next.config.js5:

Testing in Production:

1. Build production bundle: bun run build
2. Serve production build: bun run start
3. Open browser DevTools → Application tab
4. Verify service worker registration under "Service Workers"
5. Check manifest.json under "Manifest"

Offline Functionality Testing:

1. Load application in browser
2. Open DevTools → Network tab
3. Check "Offline" checkbox
4. Navigate between pages
5. Verify cached resources load successfully

Cache Strategy Validation:

API Endpoint Testing Reference

Endpoint Testing Matrix

Testing with cURL

Resume Analysis:

Cold Mail Generation (v2):

ATS Evaluation:

Integration Testing Strategies

Testing Data Flow Between Components

Integration Test Scenarios:

1. End-to-End Resume Analysis:

   • Upload file through frontend
   • Verify backend processing
   • Check database persistence
   • Confirm localStorage caching
   • Validate UI display

2. Cross-Feature Integration:

   • Complete resume analysis
   • Use analysis ID in cold mail generation
   • Verify data consistency
   • Test navigation between features

3. Authentication Flow:

   • Register new user
   • Verify email
   • Select role
   • Access protected routes
   • Test middleware enforcement

Environment-Specific Testing

Development Environment

Configuration:

• Frontend: http://localhost:3000
• Backend: http://localhost:8000
• Database: Local PostgreSQL
• PWA: Disabled (frontend/next.config.js5)

Testing Focus:

• Rapid iteration
• Hot module reloading
• Debug logging enabled
• CORS configured for local development

Production Environment

Configuration:

• Frontend: Production Next.js build
• Backend: Uvicorn with production settings
• Database: Production PostgreSQL
• PWA: Enabled (frontend/next.config.js2-6)

Testing Focus:

• Performance under load
• Service worker caching
• Build optimization
• Error handling

Build Validation:

Recommended Testing Approach

For Future Test Implementation

Given the current state of the codebase, the following testing frameworks and strategies are recommended:

Frontend Testing:

• Framework: Vitest + React Testing Library
• E2E: Playwright or Cypress
• Component Testing: Storybook

Backend Testing:

• Framework: pytest + pytest-asyncio
• API Testing: FastAPI TestClient
• Integration: pytest with test database

Suggested Test Structure:

frontend/
├── __tests__/
│   ├── components/
│   ├── pages/
│   └── integration/
└── vitest.config.ts

backend/
├── tests/
│   ├── unit/
│   ├── integration/
│   └── conftest.py
└── pytest.ini

Priority Testing Areas

1. Authentication & Authorization (High)

   • User registration and email verification
   • OAuth provider integration
   • Role-based access control
   • Session management

2. Resume Analysis Pipeline (High)

   • File upload and parsing
   • ML classification accuracy
   • LLM response validation
   • Database persistence

3. AI Service Integrations (Medium)

   • Google Gemini API calls
   • Tavily search results
   • Jina AI web content extraction
   • Error handling for API failures

4. Data Integrity (High)

   • Database schema constraints
   • Data validation (Pydantic/Zod)
   • Foreign key relationships
   • Cascade deletions

Error Testing & Validation

Common Error Scenarios

Backend Errors:

Frontend Errors:

Error Handling Validation

Test with Invalid Inputs:

Performance Testing

Load Testing Considerations

Backend Performance Metrics:

• Resume analysis: Target < 8 seconds
• Cold mail generation: Target < 5 seconds
• ATS evaluation: Target < 10 seconds (with web search)
• Database queries: Target < 100ms

Monitoring Points:

1. FastAPI request duration
2. LLM API response time (Gemini)
3. Database query performance
4. File upload/processing time

Basic Load Test (using Apache Bench):

Browser Performance Testing

Lighthouse Audits:

1. Open Chrome DevTools
2. Navigate to Lighthouse tab
3. Select categories (Performance, PWA, Accessibility)
4. Generate report
5. Review metrics:
   • First Contentful Paint
   • Time to Interactive
   • Total Blocking Time
   • PWA score

Debugging and Troubleshooting

Backend Debugging

Enable Debug Logging:

Check API Health:

Inspect Database Connection:

Frontend Debugging

Next.js Debug Mode:

Check Build Issues:

Inspect Network Requests:

1. Open Browser DevTools → Network tab
2. Filter by API calls (/api/)
3. Check request/response payloads
4. Verify CORS headers

Testing Checklist

Pre-Deployment Validation

Backend:

• All API endpoints return expected status codes
• File upload limits enforced (check backend/app/main.py1-16)
• CORS headers configured correctly
• Database migrations applied
• Environment variables loaded
• External API keys valid (Gemini, Tavily, Jina)
• Error responses include helpful messages

Frontend:

• Production build completes without errors
• All pages render correctly
• Authentication flow works end-to-end
• Protected routes redirect properly
• PWA manifest generated
• Service worker registers successfully
• Images optimized (check frontend/next.config.js13-16)
• PostHog analytics tracking
• Toast notifications display correctly

Database:

• Schema matches Prisma models
• Migrations applied successfully
• Foreign key constraints enforced
• Indexes created for performance
• Seed data populated (if applicable)

Integration:

• Frontend can reach backend API
• Database connections stable
• File uploads complete successfully
• localStorage persistence works
• Cross-feature data flow validated