TESTING_GUIDE.md

Testing the Authentication System Locally

Prerequisites

You need both:

1. Next.js Frontend (this project) - port 3000
2. FastAPI Backend - port 8000 (or configured URL)

The backend must have:

• POST /admin/login endpoint
• GET /admin/me endpoint

Quick Start

1. Configure Backend URL

Edit .env.local:

# For local backend
NEXT_PUBLIC_API_URL=http://localhost:8000

# Or your backend URL
NEXT_PUBLIC_API_URL=https://your-backend-url.com

2. Start the Frontend

npm run dev

Should see:

▲ Next.js 16.1.6
  - Local:        http://localhost:3000
...
ready - started server and apps

3. Try Login

Open browser: http://localhost:3000

Should redirect to: http://localhost:3000/login

Test Cases

Test 1: Authentication Required

Step 1: Clear browser cookies

• DevTools → Application → Cookies → Delete auth_token

Step 2: Try accessing /recruitment

• URL: http://localhost:3000/recruitment
• Should redirect to /login

Result: ✅ Pass if redirected to login page

---

Test 2: Successful Login

Step 1: Go to login page

• URL: http://localhost:3000/login

Step 2: Enter credentials

• Username: admin (or your test user)
• Password: Your test password

Step 3: Click "Sign In"

Expected:

• Form shows loading spinner
• Redirects to /recruitment on success

Check Success:

• DevTools → Application → Cookies
• Should see auth_token cookie with httpOnly flag ✅
• Cookie value should NOT be visible (httpOnly protection)

Result: ✅ Pass if redirected and cookie set

---

Test 3: Session Persistence

Step 1: After successful login, reload page

• Press F5 or Ctrl+R

Expected:

• Page stays on /recruitment
• User info still visible in header

Check:

• DevTools → Application → Cookies
• auth_token should still exist
• Header shows user name and role

Result: ✅ Pass if session persists across reload

---

Test 4: Cookie Security

Step 1: After login, open DevTools

• F12 → Application → Cookies

Step 2: Check auth_token properties

Expected:

Name:       auth_token
Value:      [cannot see due to httpOnly]
Domain:     localhost
Path:       /
Expires:    7 days from now
HttpOnly:   ✅ (checked)
Secure:     ❌ (not in dev, ✅ in prod)
SameSite:   Lax

Result: ✅ Pass if httpOnly is checked

---

Test 5: Token Not in JavaScript

Step 1: After login, open DevTools Console

• F12 → Console

Step 2: Try accessing token from JavaScript

document.cookie
// Should NOT show auth_token (httpOnly protection)

localStorage.getItem('auth_token')
// Should return null (we don't store in localStorage)

sessionStorage.getItem('auth_token')
// Should return null (we don't store in sessionStorage)

Expected:

• All return empty or null
• Token is completely inaccessible to JavaScript

Result: ✅ Pass if no token visible to JS

---

Test 6: Logout

Step 1: Click logout button

• Header → User dropdown → Logout

Step 2: Observe behavior

Expected:

• Redirects to /login page
• Cookie deleted (disappears from DevTools)
• Can't access /recruitment anymore

Check:

• DevTools → Cookies
• auth_token should be gone
• Try accessing /recruitment → redirected to /login

Result: ✅ Pass if redirected and cookie cleared

---

Test 7: Invalid Credentials

Step 1: Go to /login page

Step 2: Enter wrong password

• Username: admin
• Password: wrongpassword

Step 3: Click "Sign In"

Expected:

• Form shows error message
• Does NOT redirect
• Shows Something like "Invalid credentials"

Check:

• DevTools → Network → /api/auth/login request
• Response status should be 401

Result: ✅ Pass if error shown and no redirect

---

Test 8: Form Validation

Step 1: Go to /login page

Step 2: Try submitting empty form

• Click "Sign In" without entering anything

Expected:

• "Username is required" error
• "Password is required" error
• Form does NOT submit

Step 3: Enter short password (less than 6 chars)

• Username: admin
• Password: pass

Expected:

• "Password must be at least 6 characters" error

Result: ✅ Pass if validation works

---

Test 9: User Info Display

Step 1: Login successfully

Step 2: Check header

• Look at top-right corner

Expected:

• Shows user avatar (initials in circle)
• Shows full username
• Shows user role

Check:

• Avatar color should match gradient
• Click dropdown shows "Logout" option

Result: ✅ Pass if user info displayed

---

Test 10: Role-Based Access

Step 1: Check /admin/me response

• DevTools → Network → Find request to /api/auth/me
• Look at response body

Expected Response:

{
  "user_id": "...",
  "username": "admin",
  "role": "admin",
  "tenant_id": "...",
  ...
}

Step 2: Verify role in AuthContext

• Open DevTools → Console
• Run: const { useAuth } = require('@/lib/auth-context'); console.log(user.role)
• Or just check header displays correct role

Result: ✅ Pass if role is correctly retrieved from backend

---

Troubleshooting

Problem: "Could not connect to backend"

Symptoms:

• Error after entering credentials
• Network tab shows failed request to /admin/login
• Error message like "Failed to connect"

Solution:

1. Check backend is running (python main.py or fastapi run)
2. Check backend URL in .env.local
3. Check CORS headers if on different domain
4. Try accessing backend directly: curl http://localhost:8000/docs

---

Problem: "Stays on login after entering correct credentials"

Symptoms:

• Form submits but doesn't redirect
• No error message

Solution:

1. Check DevTools → Network tab
2. Look at /api/auth/login request/response
3. Check response status (should be 200)
4. Check response body has user data
5. Verify backend /admin/me returns correct format

---

Problem: "Cookie not being set"

Symptoms:

• Login redirects but auth_token cookie missing
• Reload page → back to login

Solution:

1. Check /api/auth/login response includes Set-Cookie header
2. Check response status is 200
3. Verify cookie name is auth_token (case-sensitive)
4. For development, remove secure: true requirement
5. Check browser cookie settings allow cookies

---

Problem: "User info not showing in header"

Symptoms:

• Header shows "Loading..." or "?"
• User role shows as empty

Solution:

1. Check DevTools → Network → /api/auth/me response
2. Verify response includes full_name, role, username
3. Check /admin/me endpoint returns these fields
4. Check user context logs: console.log(user)
5. Wait for initial auth load (might be loading state)

---

Problem: "Can't logout"

Symptoms:

• Clicking logout does nothing
• Or shows error

Solution:

1. Check DevTools → Network → /api/auth/logout response
2. Should be 200 status
3. Check cookie gets deleted manually
4. Try hard refresh after logout
5. Clear cookies manually and try again

---

Advanced Testing

Testing with curl

Test login endpoint directly:

curl -X POST http://localhost:8000/admin/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=yourpassword" \
  -v

Should return:

{
  "access_token": "eyJ...",
  "token_type": "bearer"
}

Test /admin/me endpoint:

curl http://localhost:8000/admin/me \
  -H "Authorization: Bearer <your_token>" \
  -v

Should return user object with role, tenant_id, etc.

---

Testing with Postman

1. Create POST request to /api/auth/login

   • Method: POST
   • URL: http://localhost:3000/api/auth/login
   • Body (JSON):

     {
       "username": "admin",
       "password": "yourpassword"
     }
     

   • Send
   • Check cookie in response headers

2. Get user with token cookie

   • Method: GET
   • URL: http://localhost:3000/api/auth/me
   • Cookies: auth_token=<value_from_previous_response>
   • Send
   • Should return user object

---

Performance Testing

Check Auth Performance

Time to login:

1. Start timer when clicking "Sign In"
2. Stop timer when redirected to /recruitment
3. Should be < 2 seconds (typical: 0.5-1 second)

Time to load protected page:

1. After login, reload page
2. Check time until content appears
3. Should be < 1 second (cached session)

---

Checklist - All Tests Passed ✅

• Can access /login without auth
• Can't access /recruitment without auth (redirects to login)
• Successful login redirects to /recruitment
• Session persists across page reloads
• Auth token cookie is httpOnly
• Auth token NOT accessible via JavaScript
• Logout clears cookie and redirects to /login
• Invalid credentials show error
• Form validation works (required fields, min length)
• User info displays in header
• User role displays correctly

If all ✅, your authentication system is ready for production!

---

Production Checklist

Before deploying to production:

• HTTPS enabled (secure: true in cookies)
• Backend CORS configured for frontend domain
• Rate limiting on login endpoint
• Database backups configured
• Error logging set up (Sentry, LogRocket, etc.)
• Monitoring alerts for auth failures
• Session timeout configured
• Password policy enforced
• Multi-tenant isolation verified
• Load testing performed (concurrent logins)

---

Need Help?

• Check AUTH_IMPLEMENTATION.md for detailed docs
• Check AUTH_QUICK_REFERENCE.md for code examples
• Review logs in vs code terminal for errors
• Check browser DevTools for request/response details
• Verify backend endpoints match specification