@playwright-test-runner/core 1.0.9 → 1.0.11

package/README.md

@@ -1,43 +1,64 @@
 # Playwright Test Runner Library
 
-Libreria agnostica per eseguire test Playwright con server Express e UI report. Può essere installata in qualsiasi progetto TypeScript/JavaScript per eseguire test E2E.
+> Libreria completa e agnostica per eseguire test Playwright con server Express, UI report e daemon server integrato.
 
-## Caratteristiche
+[![npm version](https://img.shields.io/npm/v/@playwright-test-runner/core.svg)](https://www.npmjs.com/package/@playwright-test-runner/core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-- Server Express con API REST per eseguire test Playwright
-- Lettura automatica dei file `.spec.ts` dalla cartella `tests`
-- Report UI integrato di Playwright
-- Completamente agnostico dal contesto del progetto
-- Facile integrazione in progetti esistenti
+## ✨ Caratteristiche Principali
 
-## Installazione
+- 🎭 **Playwright Integrato** - Include già Playwright e tutti i browser
+- 🚀 **Daemon Server Automatico** - Report sempre disponibili su porta fissa (9324)
+- 🎨 **Web UI Completa** - Interfaccia grafica per gestire i test
+- 📊 **Report Interattivi** - Visualizzazione avanzata dei risultati
+- 🔌 **REST API** - Controllo completo via HTTP
+- 🛠️ **CLI Potenti** - 4 comandi per ogni esigenza
+- ⚙️ **Zero Config** - Funziona subito, nessuna configurazione richiesta
+- 🔄 **Port Management** - Gestione intelligente delle porte occupate
+
+## 📦 Installazione
 
 ```bash
 npm install @playwright-test-runner/core
 ```
 
-**IMPORTANTE:** La libreria include già Playwright e tutti i browser necessari. **NON serve installare** `@playwright/test` o eseguire `npx playwright install` nel tuo progetto!
+### Installazione Automatica del Daemon
 
-## Utilizzo
+Dopo l'installazione, il **daemon server** si avvia automaticamente e serve i report su `http://localhost:9324`!
 
-### 1. Setup (Solo 2 Passi!)
+```
+╔════════════════════════════════════════════════════════════╗
+║   🎭 Playwright Test Runner - Post Install                ║
+╚════════════════════════════════════════════════════════════╝
 
-**Passo 1:** Crea una cartella `tests` nel tuo progetto
+✅ Report Server avviato in background!
 
-**Passo 2:** Aggiungi i tuoi file di test con estensione `.spec.ts`
+📊 Report disponibile su:
+   → http://localhost:9324
 
+📋 Dashboard:
+   → http://localhost:9324/dashboard
 ```
-your-project/
-├── tests/              # ← Crea solo questa cartella!
-│   ├── example.spec.ts
-│   ├── login.spec.ts
-│   └── checkout.spec.ts
-└── package.json
+
+**Controllo del daemon tramite variabili d'ambiente:**
+
+```bash
+# Disabilita daemon completamente
+PLAYWRIGHT_SKIP_DAEMON=true npm install
+
+# Daemon non si avvia automaticamente (manuale)
+PLAYWRIGHT_DAEMON_AUTO=false npm install
+
+# Automaticamente disabilitato in produzione
+NODE_ENV=production npm install
+
+# Automaticamente disabilitato in CI/CD
+CI=true npm install
 ```
 
-**NOTA:** NON serve creare `playwright.config.ts` - la libreria include già la configurazione!
+## 🚀 Utilizzo Rapido
 
-### 2. Web UI (Interfaccia Grafica - NUOVO!) 🎨
+### Metodo 1: Web UI (Interfaccia Grafica) 🎨
 
 **Il modo più semplice - interfaccia web completa:**
 
@@ -45,15 +66,38 @@ your-project/
 npx playwright-ui
 ```
 
-Poi apri il browser su **http://localhost:3001**
+Apri il browser su **http://localhost:3001**
 
-Interfaccia grafica che permette di:
+**Funzionalità:**
 - 📋 Vedere tutti i test disponibili
 - ▶️ Eseguire i test con un click
 - 📊 Visualizzare il report interattivo
 - ⚙️ Configurare reporter e opzioni
 
-### 3. Uso tramite CLI (Metodo Rapido)
+### Metodo 2: Daemon Server (Report Persistente) 🔄
+
+Il daemon si avvia automaticamente all'installazione, ma puoi gestirlo manualmente:
+
+```bash
+# Avvia il daemon (se non è già attivo)
+npx playwright-daemon
+
+# Controlla lo stato
+npx playwright-daemon status
+
+# Ferma il daemon
+npx playwright-daemon stop
+
+# Avvia su porta custom
+npx playwright-daemon --port 9000
+```
+
+**Accesso al daemon:**
+- Report: `http://localhost:9324`
+- Dashboard: `http://localhost:9324/dashboard`
+- Health Check: `http://localhost:9324/health`
+
+### Metodo 3: CLI Esegui & Mostra ⚡
 
 **Esegui test e visualizza report automaticamente:**
 
@@ -61,243 +105,434 @@ Interfaccia grafica che permette di:
 npx playwright-test
 ```
 
-Questo comando:
-1. ✅ Legge automaticamente i test dalla cartella `tests` del tuo progetto
+**Questo comando:**
+1. ✅ Legge automaticamente i test dalla cartella `tests`
 2. ✅ Esegue tutti i test Playwright
 3. ✅ Apre automaticamente il report UI nel browser
 
-Opzioni disponibili:
+**Opzioni disponibili:**
 
 ```bash
-npx playwright-test --tests-dir e2e           # Usa cartella 'e2e' invece di 'tests'
-npx playwright-test --project /path/to/dir    # Specifica root del progetto
+npx playwright-test --tests-dir e2e           # Usa cartella 'e2e'
+npx playwright-test --project /path/to/dir    # Specifica root
 npx playwright-test --help                    # Mostra help
 ```
 
-### 4. Uso tramite Server API
+### Metodo 4: Server API REST 🔌
 
-Avvia il server dalla root del tuo progetto:
+**Avvia server con API REST complete:**
 
 ```bash
 npx playwright-runner
 ```
 
-Opzioni disponibili:
+**Opzioni disponibili:**
 
 ```bash
 npx playwright-runner --port 4000                    # Usa porta 4000
-npx playwright-runner --project /path/to/project     # Specifica root del progetto
-npx playwright-runner --tests-dir e2e               # Usa cartella 'e2e' invece di 'tests'
+npx playwright-runner --project /path/to/project     # Specifica root
+npx playwright-runner --tests-dir e2e               # Usa cartella 'e2e'
+```
+
+## 📁 Setup Progetto
+
+### Passo 1: Crea la cartella tests
+
+**IMPORTANTE:** La libreria include già Playwright. **NON serve** installare `@playwright/test` o creare `playwright.config.ts`!
+
+```
+your-project/
+├── tests/              # ← Crea solo questa cartella!
+│   ├── example.spec.ts
+│   ├── login.spec.ts
+│   └── checkout.spec.ts
+└── package.json
 ```
 
-### 5. Uso programmatico
+### Passo 2: Scrivi i tuoi test
 
-Crea un file `test-server.ts` nel tuo progetto:
+File `tests/example.spec.ts`:
 
 ```typescript
-import { createServer } from '@playwright-test-runner/core';
+import { test, expect } from '@playwright/test';
 
-const server = createServer({
-  port: 3000,
+test('homepage has title', async ({ page }) => {
+  await page.goto('https://playwright.dev/');
+  await expect(page).toHaveTitle(/Playwright/);
+});
+
+test('get started link', async ({ page }) => {
+  await page.goto('https://playwright.dev/');
+  await page.getByRole('link', { name: 'Get started' }).click();
+  await expect(page).toHaveURL(/.*intro/);
+});
+```
+
+## 🎯 Comandi CLI Disponibili
+
+La libreria fornisce **4 comandi CLI** principali:
+
+| Comando | Descrizione | Porta |
+|---------|-------------|-------|
+| `playwright-daemon` | Daemon server persistente per report | 9324 |
+| `playwright-ui` | Interfaccia web per gestire test | 3001 |
+| `playwright-test` | Esegui test e mostra report | 9323 |
+| `playwright-runner` | Server API REST completo | 3000 |
+
+## 🔌 API Endpoints
+
+### Daemon Server (porta 9324)
+
+```bash
+# Health check
+GET http://localhost:9324/health
+
+# Dashboard interattiva
+GET http://localhost:9324/dashboard
+
+# Report HTML
+GET http://localhost:9324/
+
+# Esegui test via API
+POST http://localhost:9324/api/run
+Content-Type: application/json
+{
+  "reporter": "html",
+  "headed": false
+}
+
+# Lista test disponibili
+GET http://localhost:9324/api/tests
+```
+
+### API Server (porta 3000)
+
+```bash
+# Health check
+GET http://localhost:3000/health
+
+# Lista test
+GET http://localhost:3000/tests
+
+# Esegui test
+POST http://localhost:3000/run
+Content-Type: application/json
+{
+  "reporter": "html",
+  "headed": false
+}
+
+# Mostra report UI
+POST http://localhost:3000/report/show
+
+# Ferma report UI
+POST http://localhost:3000/report/stop
+```
+
+## 💻 Uso Programmatico
+
+### Daemon Server
+
+```typescript
+import { createDaemon } from '@playwright-test-runner/core';
+
+const daemon = createDaemon({
+  port: 9324,
   projectRoot: process.cwd(),
-  testsDir: 'tests'
+  testsDir: 'tests',
 });
 
-server.start();
+await daemon.start();
+// Daemon attivo su http://localhost:9324
+
+// Ferma il daemon
+daemon.stop();
 ```
 
-### 4. Uso come modulo
+### Test Runner
 
 ```typescript
 import { PlaywrightTestRunner } from '@playwright-test-runner/core';
 
-async function runMyTests() {
-  const runner = new PlaywrightTestRunner({
-    projectRoot: process.cwd(),
-    testsDir: 'tests'
-  });
+const runner = new PlaywrightTestRunner({
+  projectRoot: process.cwd(),
+  testsDir: 'tests'
+});
 
-  // Ottieni lista dei test
-  const testFiles = await runner.getTestFiles();
-  console.log('Test trovati:', testFiles);
+// Ottieni lista dei test
+const testFiles = await runner.getTestFiles();
+console.log('Test trovati:', testFiles);
 
-  // Esegui i test
-  const result = await runner.runTests({
-    reporter: 'html',
-    headed: false
-  });
+// Esegui i test
+const result = await runner.runTests({
+  reporter: 'html',
+  headed: false
+});
 
-  console.log('Risultato:', result);
-}
+// Mostra report
+const { url } = await runner.showReport();
+console.log('Report disponibile su:', url);
 
-runMyTests();
+// Cleanup
+runner.stopReportServer();
 ```
 
-## API Endpoints
+### API Server
+
+```typescript
+import { createServer } from '@playwright-test-runner/core';
 
-Una volta avviato il server, saranno disponibili i seguenti endpoint:
+const server = createServer({
+  port: 3000,
+  projectRoot: process.cwd(),
+  testsDir: 'tests'
+});
 
-### GET /health
+server.start();
+// Server attivo su http://localhost:3000
+```
 
-Health check del server.
+## 📋 Script package.json Consigliati
+
+Aggiungi questi script al tuo `package.json`:
 
-**Response:**
 ```json
 {
-  "status": "ok",
-  "service": "playwright-test-runner"
+  "scripts": {
+    "test:ui": "playwright-ui",
+    "test:run": "playwright-test",
+    "test:daemon": "playwright-daemon",
+    "test:daemon:stop": "playwright-daemon stop",
+    "test:daemon:status": "playwright-daemon status",
+    "test:server": "playwright-runner"
+  }
 }
 ```
 
-### GET /tests
+## 🔄 Workflow Completi
 
-Ottieni la lista dei file di test disponibili.
+### Sviluppo Locale
 
-**Response:**
-```json
-{
-  "success": true,
-  "count": 3,
-  "files": [
-    "/path/to/project/tests/example.spec.ts",
-    "/path/to/project/tests/login.spec.ts",
-    "/path/to/project/tests/checkout.spec.ts"
-  ]
-}
+```bash
+# 1. Installa il package (daemon si avvia automaticamente)
+npm install @playwright-test-runner/core
+
+# 2. Crea i tuoi test nella cartella tests/
+mkdir tests
+# Aggiungi file .spec.ts
+
+# 3. Esegui i test
+npx playwright-test
+
+# 4. I report sono automaticamente disponibili su:
+# - http://localhost:9324 (daemon - sempre attivo)
+# - Oppure il browser si apre automaticamente con il report
 ```
 
-### POST /run
+### Produzione
+
+```bash
+# Il daemon NON si avvia in produzione
+NODE_ENV=production npm install
 
-Esegui i test Playwright.
+# Esegui i test (se necessario)
+npx playwright-test
 
-**Request Body:**
-```json
-{
-  "reporter": "html",
-  "headed": false
-}
+# Il report sarà in playwright-report/ ma il daemon non sarà attivo
 ```
 
-**Response:**
-```json
-{
-  "success": true,
-  "output": "Running 3 tests...\n...",
-  "reportPath": "/path/to/project/playwright-report"
-}
+### CI/CD (GitHub Actions)
+
+```yaml
+name: E2E Tests
+on: [push]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+
+      - name: Install
+        run: npm install
+        env:
+          CI: true  # Daemon automaticamente skippato
+
+      - name: Install browsers
+        run: npx playwright install --with-deps chromium
+
+      - name: Run tests
+        run: npx playwright-test
+
+      - name: Upload report
+        if: always()
+        uses: actions/upload-artifact@v3
+        with:
+          name: playwright-report
+          path: playwright-report/
 ```
 
-### POST /report/show
+## 🛠️ Gestione Daemon
 
-Avvia il server del report UI di Playwright.
+### Comandi Daemon
 
-**Response:**
-```json
-{
-  "success": true,
-  "message": "Report UI avviato",
-  "url": "http://localhost:9323"
-}
+```bash
+# Stato del daemon
+npx playwright-daemon status
+
+# Output:
+# ✅ Daemon ATTIVO
+# 📊 Informazioni:
+#    • PID: 12345
+#    • Porta: 9324
+#    • Status: ok
+# 🌐 URLs:
+#    • Report: http://localhost:9324
+#    • Dashboard: http://localhost:9324/dashboard
+
+# Fermare il daemon
+npx playwright-daemon stop
+
+# Avviare il daemon manualmente
+npx playwright-daemon
+
+# Avvio su porta custom
+npx playwright-daemon --port 9000
 ```
 
-### POST /report/stop
+### Troubleshooting Daemon
 
-Ferma il server del report UI.
+```bash
+# Processo zombie sulla porta 9324
+lsof -ti:9324 | xargs kill -9
 
-**Response:**
-```json
-{
-  "success": true,
-  "message": "Report UI fermato"
-}
+# Riavvia il daemon
+npx playwright-daemon
 ```
 
-## Esempio di Test
+## 📚 Guide Complete
 
-Crea un file `tests/example.spec.ts`:
+- 📖 **[QUICKSTART.md](QUICKSTART.md)** - Guida rapida per iniziare
+- 🔧 **[SETUP_SEMPLIFICATO.md](SETUP_SEMPLIFICATO.md)** - Setup zero-config
+- 🌐 **[WEB_UI_GUIDE.md](WEB_UI_GUIDE.md)** - Guida all'interfaccia Web
+- 🔄 **[DAEMON_GUIDE.md](DAEMON_GUIDE.md)** - Guida completa al Daemon Server
+- 🔗 **[INTEGRATION.md](INTEGRATION.md)** - Integrazione con framework (React, Vue, Angular)
+- 🧪 **[LOCAL_TESTING_GUIDE.md](LOCAL_TESTING_GUIDE.md)** - Testing locale con npm link
+- ❌ **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Risoluzione problemi comuni
 
-```typescript
-import { test, expect } from '@playwright/test';
+## 🚨 Troubleshooting Rapido
 
-test('homepage has title', async ({ page }) => {
-  await page.goto('https://playwright.dev/');
-  await expect(page).toHaveTitle(/Playwright/);
-});
+### Errore: "porta 9324 già in uso"
 
-test('get started link', async ({ page }) => {
-  await page.goto('https://playwright.dev/');
-  await page.getByRole('link', { name: 'Get started' }).click();
-  await expect(page).toHaveURL(/.*intro/);
-});
+```bash
+# Verifica stato daemon
+npx playwright-daemon status
+
+# Se appeso, killalo
+lsof -ti:9324 | xargs kill -9
+
+# Riavvia
+npx playwright-daemon
 ```
 
-## Workflow Completo
+### Errore: "cartella tests non trovata"
 
-1. Installa la libreria nel tuo progetto
-2. Crea la cartella `tests` con i tuoi file `.spec.ts`
-3. Avvia il server: `npx playwright-runner`
-4. Esegui i test via API: `POST http://localhost:3000/run`
-5. Visualizza il report: `POST http://localhost:3000/report/show`
-6. Apri il browser su `http://localhost:9323` per vedere il report UI
+```bash
+# Crea la cartella tests
+mkdir tests
 
-## Esempio con cURL
+# Aggiungi un file di test
+echo 'import { test } from "@playwright/test";
+test("example", async () => {});' > tests/example.spec.ts
+```
+
+### Daemon non si avvia in produzione
+
+È normale! Il daemon è disabilitato automaticamente in:
+- `NODE_ENV=production`
+- `CI=true`
 
+Per forzare l'avvio:
 ```bash
-# Health check
-curl http://localhost:3000/health
+PLAYWRIGHT_DAEMON_AUTO=true npm install
+```
 
-# Lista test
-curl http://localhost:3000/tests
+Consulta la [Guida Troubleshooting](TROUBLESHOOTING.md) completa per altri problemi.
 
-# Esegui test
-curl -X POST http://localhost:3000/run \
-  -H "Content-Type: application/json" \
-  -d '{"reporter":"html","headed":false}'
+## 🔧 Port Management Avanzato
 
-# Mostra report UI
-curl -X POST http://localhost:3000/report/show
+La libreria include **gestione intelligente delle porte**:
 
-# Ferma report UI
-curl -X POST http://localhost:3000/report/stop
+1. **Controllo automatico** - Verifica se la porta è già in uso
+2. **Riutilizzo server esistente** - Se il report è già attivo, lo riutilizza
+3. **Cleanup automatico** - Chiusura pulita all'uscita del processo
+
+Questo previene l'errore `EADDRINUSE` (porta già in uso).
+
+## 📊 Struttura Progetto
+
+```
+@playwright-test-runner/core/
+├── dist/                      # Build TypeScript
+│   ├── cli.js                # CLI per API server
+│   ├── daemon-cli.js         # CLI per daemon
+│   ├── run-and-show.js       # CLI esegui & mostra
+│   ├── web-cli.js            # CLI per Web UI
+│   ├── server.js             # Server API REST
+│   ├── report-daemon.js      # Daemon server
+│   ├── test-runner.js        # Test runner core
+│   ├── web-ui.js             # Web UI server
+│   └── index.js              # Entry point principale
+├── scripts/                   # Script di utilità
+│   ├── postinstall.js        # Post-install auto daemon
+│   ├── release.js            # Script per release npm
+│   ├── status-daemon.js      # Controlla stato daemon
+│   └── stop-daemon.js        # Ferma daemon
+├── public/                    # Asset Web UI
+│   └── index.html            # Interfaccia grafica
+├── src/                       # Sorgenti TypeScript
+├── playwright.config.ts       # Config Playwright inclusa
+└── package.json
 ```
 
-## Script package.json consigliati
+## 🚀 Pubblicazione (per Maintainer)
 
-Aggiungi questi script al `package.json` del tuo progetto:
+La libreria include uno script interattivo per gestire versioning e pubblicazione:
 
-```json
-{
-  "scripts": {
-    "test:server": "playwright-runner",
-    "test:run": "playwright test",
-    "test:report": "playwright show-report"
-  }
-}
+```bash
+# Esegui lo script di release
+npm run release
+
+# Lo script ti guiderà attraverso:
+# 1. Commit automatico modifiche (se presenti)
+# 2. Scelta tipo versione (PATCH/MINOR/MAJOR/CUSTOM)
+# 3. Aggiornamento automatico versione
+# 4. Login npm (con browser)
+# 5. Pubblicazione su npm
+# 6. Reminder per git push
 ```
 
-## Troubleshooting
+## ✅ Requisiti
+
+- **Node.js** >= 18
+- **TypeScript** >= 5.0 (per progetti TypeScript)
+- **Playwright** - ✅ Incluso nella libreria!
 
-Hai problemi? Consulta la [Guida al Troubleshooting](TROUBLESHOOTING.md) per risolvere i problemi più comuni:
+## 📝 Versione Corrente
 
-- ❌ Errore "porta 9323 già in uso" → [Soluzione](TROUBLESHOOTING.md#errore-listen-eaddrinuse-address-already-in-use-19323)
-- ❌ Errore "cartella tests non trovata" → [Soluzione](TROUBLESHOOTING.md#errore-cartella-tests-non-trovata)
-- ❌ Errore "playwright: command not found" → [Soluzione](TROUBLESHOOTING.md#errore-playwright-command-not-found)
-- E molti altri...
+**v1.0.9** - Include daemon server, port management, Web UI e CLI completi
 
-## Guide Aggiuntive
+## 🤝 Contributing
 
-- 📖 [QUICKSTART.md](QUICKSTART.md) - Guida rapida per iniziare
-- 🔧 [SETUP_SEMPLIFICATO.md](SETUP_SEMPLIFICATO.md) - Setup zero-config
-- 🌐 [WEB_UI_GUIDE.md](WEB_UI_GUIDE.md) - Guida all'interfaccia Web
-- 🔗 [INTEGRATION.md](INTEGRATION.md) - Integrazione con framework (React, Vue, Angular, ecc.)
-- 🧪 [LOCAL_TESTING_GUIDE.md](LOCAL_TESTING_GUIDE.md) - Testing locale con npm link
+Contributi benvenuti! Leggi [CONTRIBUTING.md](CONTRIBUTING.md) per le linee guida.
 
-## Requisiti
+## 📄 License
 
-- Node.js >= 18
-- TypeScript >= 5.0 (per progetti TypeScript)
-- **Playwright è incluso nella libreria** - NON serve installarlo!
+MIT © Giovanni Cannone
 
-## License
+---
 
-MIT
+**Made with ❤️ for the Playwright community**