my2/docs/TESTING.md

# Testing Guide

This document provides testing credentials, test data, and guidelines for automated testing.

---

## Test User Credentials (Staging)

**⚠️ Important:** These credentials are **ONLY** for the **staging environment**. **NEVER** use them in production!

### Cidaas Staging Test User

- **Email:** `bm@noxware.de`
- **Password:** `%654321qQ!`
- **Environment:** `https://experimenta-staging.cidaas.de`
- **User ID (experimenta_id):** `97dcde33-d12e-4275-a0d5-e01cfbea37c2`

**Usage:**
- Used by automated tests (Playwright E2E, Vitest integration tests)
- Manual testing during development
- Authentication flow validation

**User Profile:**
- First Name: Bastian
- Last Name: Masanek
- Email verified: Yes

---

## Setting Up Automated Tests

### 1. Environment Variables

Add these to your `.env` file for automated testing:

```bash
# Test Credentials (Staging only - for automated testing)
TEST_USER_EMAIL=bm@noxware.de
TEST_USER_PASSWORD=%654321qQ!
```

### 2. Playwright E2E Tests

Playwright tests use these credentials to test the complete authentication flow.

**Example test:**
```typescript
// tests/e2e/auth.spec.ts
import { test, expect } from '@playwright/test'

test('user can login with valid credentials', async ({ page }) => {
  const email = process.env.TEST_USER_EMAIL!
  const password = process.env.TEST_USER_PASSWORD!

  await page.goto('http://localhost:3000/auth')
  await page.fill('input[type="email"]', email)
  await page.fill('input[type="password"]', password)
  await page.click('button[type="submit"]')

  // Verify successful login
  await expect(page).toHaveURL('http://localhost:3000/')
  await expect(page.locator('text=Willkommen zurück')).toBeVisible()
})
```

**Run Playwright tests:**
```bash
pnpm test:e2e
```

### 3. Vitest Integration Tests

Vitest tests use these credentials for API endpoint testing.

**Example test:**
```typescript
// tests/integration/auth.test.ts
import { describe, it, expect } from 'vitest'
import { setup, $fetch } from '@nuxt/test-utils'

describe('Authentication API', async () => {
  await setup()

  it('POST /api/auth/login - successful login', async () => {
    const response = await $fetch('/api/auth/login', {
      method: 'POST',
      body: {
        email: process.env.TEST_USER_EMAIL,
        password: process.env.TEST_USER_PASSWORD,
      },
    })

    expect(response.success).toBe(true)
  })
})
```

**Run Vitest tests:**
```bash
pnpm test
```

---

## Test Data

### Test Products (Mock Data for Development)

For local development and testing, you can use these mock product IDs:

```typescript
// Mock Makerspace Annual Pass
{
  navProductId: 'MAK-001',
  name: 'Makerspace Jahreskarte',
  description: 'Unbegrenzter Zugang zum Makerspace für 1 Jahr',
  price: 120.00,
  category: 'annual-pass',
  stock: 100,
}
```

### Test Orders (Mock Data)

```typescript
// Mock completed order
{
  orderNumber: 'TEST-2025-0001',
  userId: '...',
  status: 'completed',
  totalAmount: 120.00,
  paymentMethod: 'paypal',
  paymentId: 'PAYPAL-TEST-12345',
}
```

---

## Testing Workflows

### Complete Checkout Flow (E2E)

1. **Login** with test credentials
2. **Browse products** and add to cart
3. **Proceed to checkout**
4. **Fill billing address** (pre-filled from test user profile)
5. **Complete PayPal payment** (sandbox)
6. **Verify order creation** in database
7. **Verify order submission** to X-API (staging)

### Authentication Flow (Integration)

1. **Register new user** via Cidaas API (staging)
2. **Verify email** (manual step in staging)
3. **Login** with new credentials
4. **Create session** and verify JWT token
5. **Access protected endpoints** with session
6. **Logout** and verify session cleared

---

## CI/CD Integration

### GitLab CI Environment Variables

Add these secrets to GitLab CI/CD settings:

- `TEST_USER_EMAIL` (Protected, Masked)
- `TEST_USER_PASSWORD` (Protected, Masked)

**GitLab CI configuration:**
```yaml
test:
  stage: test
  script:
    - pnpm install
    - pnpm test
    - pnpm test:e2e
  variables:
    TEST_USER_EMAIL: $TEST_USER_EMAIL
    TEST_USER_PASSWORD: $TEST_USER_PASSWORD
```

---

## Security Best Practices

### ✅ Do's
- Use test credentials **only** in staging environment
- Store credentials in environment variables (`.env`), never hardcode
- Use separate test user accounts (not real user accounts)
- Rotate test credentials regularly
- Add test credentials to GitLab CI/CD as protected, masked variables

### ❌ Don'ts
- **Never** commit `.env` file to git (already in `.gitignore`)
- **Never** use test credentials in production environment
- **Never** use real user credentials for automated testing
- **Never** hardcode credentials in test files
- **Never** share test credentials publicly (GitHub, Slack, etc.)

---

## Troubleshooting

### Test User Login Fails

**Problem:** Automated tests fail with "Invalid credentials" error

**Solutions:**
1. Verify `TEST_USER_EMAIL` and `TEST_USER_PASSWORD` are set in `.env`
2. Check Cidaas staging environment is accessible
3. Verify test user account still exists in Cidaas
4. Check if password was changed in Cidaas Admin Panel

### Session Tests Fail

**Problem:** Session-related tests fail unexpectedly

**Solutions:**
1. Verify `NUXT_SESSION_PASSWORD` is set in `.env`
2. Clear Redis cache: `docker-compose -f docker-compose.dev.yml restart redis`
3. Check session expiration settings in `nuxt.config.ts`

### E2E Tests Time Out

**Problem:** Playwright tests time out waiting for elements

**Solutions:**
1. Increase timeout in `playwright.config.ts`
2. Check if dev server is running (`pnpm dev`)
3. Verify network connectivity to staging environment
4. Check browser console for JavaScript errors

---

## Related Documentation

- [CIDAAS_INTEGRATION.md](./CIDAAS_INTEGRATION.md) - Authentication implementation details
- [ARCHITECTURE.md](./ARCHITECTURE.md) - System architecture and data flows
- [PRD.md](./PRD.md) - Product requirements and user stories
- Main README: [../tests/README.md](../tests/README.md) - Test suite overview

---

**Last Updated:** 2025-11-01