veza/apps/web/e2e/README.md

# 🧪 Veza E2E Test Suite

> **Suite de tests End-to-End (E2E) complète et consolidée pour l'application web Veza.**

Cette suite utilise **Playwright** pour tester l'ensemble des flux utilisateurs critiques de la plateforme audio collaborative Veza.

---

## 📁 Architecture

```
apps/web/e2e/
├── fixtures/                  # Fichiers statiques et helpers
│   └── file-helpers.ts        # Création de fichiers MP3 de test
├── utils/                     # Helpers et utilitaires
│   └── test-helpers.ts        # Fonctions communes (login, form submit, etc.)
├── auth.spec.ts               # Tests d'authentification (Login, Register, Logout, Guards)
├── tracks_upload_chunked.spec.ts  # Tests d'upload chunké (TASK-006)
├── track_lifecycle.spec.ts    # Tests CRUD complets sur les tracks
├── upload_flow.spec.ts        # Tests du flux d'upload standard
├── playlists.spec.ts          # Tests CRUD sur les playlists
├── profile.spec.ts            # Tests de gestion du profil utilisateur
├── deep_audit.spec.ts         # Tests d'audit complets (existant)
├── diagnostic.spec.ts         # Tests de diagnostic (existant)
├── qa-audit.spec.ts           # Tests QA (existant)
└── README.md                  # Ce fichier
```

---

## 🚀 Lancement des Tests

### Prérequis

1. **Backend Go** doit être lancé sur `http://localhost:8080`
2. **Frontend React** doit être lancé sur `http://localhost:3000` (ou port configuré)
3. Un **utilisateur de test** doit exister avec les credentials:
   - Email: `user@example.com` (ou via `TEST_EMAIL` env var)
   - Password: `password123` (ou via `TEST_PASSWORD` env var)

### Commandes

```bash
# Lancer tous les tests E2E
cd apps/web
npm run test:e2e

# Lancer un fichier de test spécifique
npx playwright test e2e/auth.spec.ts

# Lancer les tests en mode UI (debug)
npx playwright test --ui

# Lancer les tests en mode headed (voir le navigateur)
npx playwright test --headed

# Générer un rapport HTML
npx playwright show-report
```

### Variables d'Environnement

Créer un fichier `.env` ou les définir dans le shell :

```bash
PLAYWRIGHT_BASE_URL=http://localhost:3000
TEST_EMAIL=user@example.com
TEST_PASSWORD=password123
TEST_ADMIN_EMAIL=admin@example.com
TEST_ADMIN_PASSWORD=admin123
VITE_API_URL=http://localhost:8080
```

---

## 📝 Description des Tests

### 1. **auth.spec.ts** - Authentification

Couvre l'ensemble du cycle d'authentification :

- ✅ Login avec credentials valides
- ✅ Login avec credentials invalides (erreur affichée)
- ✅ Registration (inscription) d'un nouvel utilisateur
- ✅ Registration avec email existant (erreur)
- ✅ Logout (déconnexion)
- ✅ Route Guards (redirection si non authentifié)
- ✅ Persistance de l'authentification après refresh
- ✅ Validation du formulaire de login
- ✅ Validation du formulaire d'inscription (mots de passe différents)

### 2. **tracks_upload_chunked.spec.ts** - Upload Chunké (TASK-006)

Teste le mécanisme d'upload par morceaux pour les gros fichiers :

- ✅ Upload d'un fichier de 15 MB avec chunking
- ✅ Vérification des appels API : `/tracks/initiate`, `/tracks/chunk`, `/tracks/complete`
- ✅ Vérification de la barre de progression
- ✅ Upload d'un fichier de 25 MB (test de performance)
- ✅ Vérification que les petits fichiers (< 10 MB) utilisent l'upload direct

**Note:** Si l'implémentation frontend du chunking n'est pas encore complète, ces tests détecteront l'utilisation de l'upload direct et loggeront des warnings.

### 3. **track_lifecycle.spec.ts** - CRUD Tracks

Teste le cycle de vie complet d'une track :

- ✅ Upload avec métadonnées complètes (titre, artiste, genre)
- ✅ Vérification de l'affichage des métadonnées
- ✅ Suppression d'une track
- ✅ Vérification de la persistance après reload

### 4. **upload_flow.spec.ts** - Flux d'Upload Standard

Teste le "Happy Path" de l'upload :

- ✅ Connexion
- ✅ Navigation vers /library
- ✅ Ouverture de la modal d'upload
- ✅ Sélection d'un fichier MP3 valide
- ✅ Remplissage des métadonnées
- ✅ Vérification du succès
- ✅ Vérification que la track apparaît dans la liste

### 5. **playlists.spec.ts** - CRUD Playlists

Teste la gestion des playlists :

- ✅ Création d'une nouvelle playlist
- ✅ Affichage de la liste des playlists
- ✅ Modification d'une playlist (nom, description)
- ✅ Ajout d'une track à une playlist
- ✅ Suppression d'une playlist
- ✅ Affichage de l'état vide (nouvelle playlist sans tracks)
- ✅ Recherche de playlists par nom

### 6. **profile.spec.ts** - Gestion du Profil

Teste la gestion du profil utilisateur :

- ✅ Affichage du profil utilisateur
- ✅ Modification du username
- ✅ Modification de la bio
- ✅ Changement de mot de passe
- ✅ Upload d'avatar
- ✅ Validation des champs (username trop court)
- ✅ Affichage des informations du compte (email, date de création)
- ✅ Navigation vers les paramètres avancés

---

## 🛠️ Helpers & Utilitaires

### `utils/test-helpers.ts`

Contient des fonctions réutilisables pour simplifier l'écriture des tests :

#### Authentification

- `loginAsUser(page, credentials?)` : Authentifie un utilisateur via l'UI

#### Navigation

- `navigateViaSidebar(page, linkText, expectedUrl)` : Navigue via le sidebar
- `openModal(page, buttonText)` : Ouvre une modal
- `closeModal(page)` : Ferme une modal

#### Formulaires

- `fillField(page, selector, value)` : Remplit un champ de formulaire
- `forceSubmitForm(page, formSelector)` : Force la soumission d'un formulaire via `requestSubmit()`
- `safeClick(page, selector, options)` : Clic robuste avec gestion des interceptions

#### API & Réseau

- `waitForApiCall(page, urlPattern, method, timeout)` : Attend un appel API spécifique
- `waitForToast(page, type, timeout)` : Attend un message de succès/erreur

#### Debugging

- `setupErrorCapture(page)` : Capture les erreurs console et réseau

### `fixtures/file-helpers.ts`

Contient des fonctions pour créer des fichiers de test :

- `createMockMP3File(filePath)` : Crée un fichier MP3 valide sur disque
- `createMockMP3Buffer()` : Crée un buffer MP3 valide (in-memory)
- `createLargeMockMP3Buffer(sizeInMB)` : Crée un gros buffer MP3 pour tester le chunking
- `SUPPORTED_AUDIO_FORMATS` : Liste des formats audio supportés

---

## 💡 Bonnes Pratiques

### 1. Utiliser les Helpers

❌ **Mauvais :**
```typescript
await page.goto('http://localhost:3000/login');
await page.locator('input[type="email"]').fill('user@example.com');
await page.locator('input[type="password"]').fill('password123');
await page.locator('button[type="submit"]').click();
await page.waitForURL('/dashboard');
```

✅ **Bon :**
```typescript
import { loginAsUser } from './utils/test-helpers';

await loginAsUser(page);
```

### 2. Utiliser `forceSubmitForm` au lieu du clic simple

Pour éviter les erreurs "click intercepted", utiliser `requestSubmit()` :

❌ **Mauvais :**
```typescript
await page.locator('button[type="submit"]').click();
```

✅ **Bon :**
```typescript
import { forceSubmitForm } from './utils/test-helpers';

await forceSubmitForm(page, 'form#my-form');
```

### 3. Capturer les Erreurs

Utiliser `setupErrorCapture` pour déboguer les tests qui échouent :

```typescript
const { consoleErrors, networkErrors } = setupErrorCapture(page);

// ... tests ...

test.afterEach(() => {
  if (consoleErrors.length > 0) {
    console.log('Console errors:', consoleErrors);
  }
  if (networkErrors.length > 0) {
    console.log('Network errors:', networkErrors);
  }
});
```

### 4. Nommer les Tests de Manière Descriptive

❌ **Mauvais :**
```typescript
test('test login', async ({ page }) => { ... });
```

✅ **Bon :**
```typescript
test('should login successfully with valid credentials', async ({ page }) => { ... });
```

### 5. Nettoyer après les Tests

Pour les tests qui créent des données (playlists, tracks, etc.), pensez à les supprimer :

```typescript
test('should create playlist', async ({ page }) => {
  // Créer la playlist
  const playlistName = `Test ${Date.now()}`;
  // ... création ...

  // Supprimer la playlist après le test
  // ... suppression ...
});
```

---

## 🐛 Debugging

### Problèmes Courants

#### 1. "Element is not visible"

**Cause :** L'élément est présent dans le DOM mais pas visible (ex: `display: none`, `opacity: 0`).

**Solution :** Vérifier que la modal/page est bien chargée avant d'interagir :

```typescript
await expect(page.locator('[role="dialog"]')).toBeVisible({ timeout: 10000 });
```

#### 2. "Click intercepted"

**Cause :** Un autre élément (modal, overlay) est devant l'élément à cliquer.

**Solution :** Utiliser `forceSubmitForm` ou `safeClick` :

```typescript
await safeClick(page, 'button#my-button', { force: true });
```

#### 3. "Timeout waiting for response"

**Cause :** L'API prend trop de temps ou n'est pas accessible.

**Solution :** Augmenter le timeout ou vérifier que le backend est lancé :

```typescript
await page.waitForResponse(
  (response) => response.url().includes('/api/tracks'),
  { timeout: 60000 } // 60 secondes
);
```

### Mode Debug

Lancer Playwright en mode UI pour déboguer interactivement :

```bash
npx playwright test --ui
```

Ou en mode headed pour voir le navigateur :

```bash
npx playwright test --headed --slowmo=1000
```

### Screenshots

Prendre des screenshots en cas d'échec :

```typescript
test.afterEach(async ({ page }, testInfo) => {
  if (testInfo.status !== 'passed') {
    await page.screenshot({ 
      path: `e2e/screenshots/${testInfo.title}-failure.png`,
      fullPage: true 
    });
  }
});
```

---

## 📊 Coverage des Tests

### Scénarios couverts (selon INTEGRATION_REFERENCE.md)

- ✅ **P0 - Authentification** : Login, Register, Logout, Guards, Token Refresh
- ✅ **P0 - Tracks CRUD** : Create, Read, Update, Delete
- ✅ **P1 - Chunked Upload** : Upload de gros fichiers (> 10 MB)
- ✅ **P1 - Playlists** : Création, modification, suppression
- ✅ **P2 - Profile** : Modification des informations personnelles

### Scénarios manquants (à implémenter)

- ⚠️ **Likes** : Liker/unliker une track
- ⚠️ **Comments** : Ajouter/supprimer des commentaires
- ⚠️ **Shares** : Créer/gérer des liens de partage
- ⚠️ **Search** : Recherche de tracks
- ⚠️ **Social** : Follow/unfollow d'utilisateurs

---

## 🔗 Références

- **Playwright Documentation** : https://playwright.dev/
- **INTEGRATION_REFERENCE.md** : Documentation des API et scénarios à tester
- **veza-backend-api** : Backend Go (API REST)
- **apps/web** : Frontend React (Vite, TypeScript)

---

## 📞 Support

Pour toute question ou problème avec les tests E2E, consulter :

1. Ce README
2. Les fichiers de tests existants (exemples)
3. La documentation Playwright
4. Les logs des tests (`console.log` dans les tests)

---

**Date de dernière mise à jour** : 2025-01-XX  
**Mainteneur** : Équipe QA Veza