@playwright-test-runner/core

v1.0.10

Published

6 days ago

Libreria agnostica per eseguire test Playwright con server Express e UI report

0High
0Medium
0Low

gcannone

playwright testing e2e test-runner express

Playwright Test Runner Library

Libreria completa e agnostica per eseguire test Playwright con server Express, UI report e daemon server integrato.

✨ Caratteristiche Principali

🎭 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

npm install @playwright-test-runner/core

Installazione Automatica del Daemon

Dopo l'installazione, il daemon server si avvia automaticamente e serve i report su http://localhost:9324!

╔════════════════════════════════════════════════════════════╗
║   🎭 Playwright Test Runner - Post Install                ║
╚════════════════════════════════════════════════════════════╝

✅ Report Server avviato in background!

📊 Report disponibile su:
   → http://localhost:9324

📋 Dashboard:
   → http://localhost:9324/dashboard

Controllo del daemon tramite variabili d'ambiente:

# 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

🚀 Utilizzo Rapido

Metodo 1: Web UI (Interfaccia Grafica) 🎨

Il modo più semplice - interfaccia web completa:

npx playwright-ui

Apri il browser su http://localhost:3001

Funzionalità:

📋 Vedere tutti i test disponibili
▶️ Eseguire i test con un click
📊 Visualizzare il report interattivo
⚙️ Configurare reporter e opzioni

Metodo 2: Daemon Server (Report Persistente) 🔄

Il daemon si avvia automaticamente all'installazione, ma puoi gestirlo manualmente:

# 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:

npx playwright-test

Questo comando:

✅ Legge automaticamente i test dalla cartella tests
✅ Esegue tutti i test Playwright
✅ Apre automaticamente il report UI nel browser

Opzioni disponibili:

npx playwright-test --tests-dir e2e           # Usa cartella 'e2e'
npx playwright-test --project /path/to/dir    # Specifica root
npx playwright-test --help                    # Mostra help

Metodo 4: Server API REST 🔌

Avvia server con API REST complete:

npx playwright-runner

Opzioni disponibili:

npx playwright-runner --port 4000                    # Usa porta 4000
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

Passo 2: Scrivi i tuoi test

File tests/example.spec.ts:

import { test, expect } from '@playwright/test';

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)

# 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)

# 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

import { createDaemon } from '@playwright-test-runner/core';

const daemon = createDaemon({
  port: 9324,
  projectRoot: process.cwd(),
  testsDir: 'tests',
});

await daemon.start();
// Daemon attivo su http://localhost:9324

// Ferma il daemon
daemon.stop();

Test Runner

import { PlaywrightTestRunner } from '@playwright-test-runner/core';

const runner = new PlaywrightTestRunner({
  projectRoot: process.cwd(),
  testsDir: 'tests'
});

// 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
});

// Mostra report
const { url } = await runner.showReport();
console.log('Report disponibile su:', url);

// Cleanup
runner.stopReportServer();

API Server

import { createServer } from '@playwright-test-runner/core';

const server = createServer({
  port: 3000,
  projectRoot: process.cwd(),
  testsDir: 'tests'
});

server.start();
// Server attivo su http://localhost:3000

📋 Script package.json Consigliati

Aggiungi questi script al tuo package.json:

{
  "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"
  }
}

🔄 Workflow Completi

Sviluppo Locale

# 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

Produzione

# Il daemon NON si avvia in produzione
NODE_ENV=production npm install

# Esegui i test (se necessario)
npx playwright-test

# Il report sarà in playwright-report/ ma il daemon non sarà attivo

CI/CD (GitHub Actions)

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/

🛠️ Gestione Daemon

Comandi Daemon

# 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

Troubleshooting Daemon

# Processo zombie sulla porta 9324
lsof -ti:9324 | xargs kill -9

# Riavvia il daemon
npx playwright-daemon

📚 Guide Complete

📖 QUICKSTART.md - Guida rapida per iniziare
🔧 SETUP_SEMPLIFICATO.md - Setup zero-config
🌐 WEB_UI_GUIDE.md - Guida all'interfaccia Web
🔄 DAEMON_GUIDE.md - Guida completa al Daemon Server
🔗 INTEGRATION.md - Integrazione con framework (React, Vue, Angular)
🧪 LOCAL_TESTING_GUIDE.md - Testing locale con npm link
❌ TROUBLESHOOTING.md - Risoluzione problemi comuni

🚨 Troubleshooting Rapido

Errore: "porta 9324 già in uso"

# Verifica stato daemon
npx playwright-daemon status

# Se appeso, killalo
lsof -ti:9324 | xargs kill -9

# Riavvia
npx playwright-daemon

Errore: "cartella tests non trovata"

# Crea la cartella tests
mkdir tests

# 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:

PLAYWRIGHT_DAEMON_AUTO=true npm install

Consulta la Guida Troubleshooting completa per altri problemi.

🔧 Port Management Avanzato

La libreria include gestione intelligente delle porte:

Controllo automatico - Verifica se la porta è già in uso
Riutilizzo server esistente - Se il report è già attivo, lo riutilizza
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

🚀 Pubblicazione (per Maintainer)

La libreria include uno script interattivo per gestire versioning e pubblicazione:

# 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

✅ Requisiti

Node.js >= 18
TypeScript >= 5.0 (per progetti TypeScript)
Playwright - ✅ Incluso nella libreria!

📝 Versione Corrente

v1.0.9 - Include daemon server, port management, Web UI e CLI completi

🤝 Contributing

Contributi benvenuti! Leggi CONTRIBUTING.md per le linee guida.

📄 License

Made with ❤️ for the Playwright community