---
title: "Introduzione ai test automatici su codebase PHP legacy: come iniziare senza riscrivere tutto"
description: "Test automatici su PHP legacy senza riscrittura: characterization test con PHPUnit, smoke test sugli endpoint critici, golden master e CI gate. Caso reale PMI."
canonical: "https://www.mauriziofonte.it/blog/post/test-automatici-codebase-php-legacy-senza-riscrittura.html"
author: "Maurizio Fonte"
date: "2025-09-03T09:34:11+02:00"
modified: "2026-04-14T17:48:55+02:00"
section: "Testing"
tags: ["Testing", "Refactoring"]
license: "Riuso e citazione consentiti con attribuzione e link alla fonte"
---

[Testing](https://www.mauriziofonte.it/blog/cat/testing.html) [Refactoring](https://www.mauriziofonte.it/blog/cat/refactoring.html)

# [Introduzione ai test automatici su codebase PHP legacy: come iniziare senza riscrivere tutto](https://www.mauriziofonte.it/blog/post/test-automatici-codebase-php-legacy-senza-riscrittura.html)

Mercoledì 3 Settembre 2025, alle 09:34 ![Introduzione ai test automatici su codebase PHP legacy: come iniziare senza riscrivere tutto](https://www.mauriziofonte.it/image/002230200-test-automatici-codebase-php-legacy-senza-riscrittura.jpg)

A ottobre 2024, dopo aver messo sotto Git il gestionale PHP legacy di un cliente piemontese - la storia la racconto nell'articolo sull'[implementazione di Git su sistemi PHP legacy](https://www.mauriziofonte.it/blog/post/implementare-git-sistemi-php-legacy-produzione-senza-downtime.html) - il passo successivo era inevitabile: ogni volta che il collaboratore interno faceva una modifica, qualcos'altro si rompeva in un punto apparentemente non correlato. Un fix al calcolo dell'IVA rompeva la stampa delle bolle. Una modifica al filtro di ricerca prodotti faceva sparire i prezzi dal listino. Il codice era un monolite di 23.000 righe distribuite su 147 file senza nessuna separazione tra logica, presentazione e accesso ai dati - tutto nello stesso file PHP, con `mysql_query` inframmezzato a tag HTML e `echo` di JavaScript.

Il titolare mi ha chiesto: "possiamo fare qualcosa per evitare che ogni modifica rompa qualcos'altro?" La risposta è sì, e non richiede di riscrivere l'applicazione da zero. La tecnica si chiama **characterization testing** - un termine coniato da Michael Feathers nel libro *Working Effectively with Legacy Code* - e consiste nel catturare il comportamento attuale dell'applicazione in test automatici. Non testi cosa *dovrebbe* fare il codice (perché spesso non lo sai), ma cosa *fa effettivamente*. Quei test diventano la rete di sicurezza: se una modifica cambia il comportamento catturato, il test fallisce e sai che hai rotto qualcosa prima che arrivi in produzione.

In una settimana ho introdotto 34 test di caratterizzazione sugli endpoint critici del gestionale - login, ricerca prodotti, inserimento ordine, calcolo totali, stampa bolla - senza modificare una singola riga del codice applicativo. Nel primo mese dopo l'introduzione dei test, il tasso di bug in produzione è sceso del 70%. In questo articolo ti racconto come.

> Stai cercando un **Consulente Informatico** esperto per introdurre test automatici sul tuo codebase PHP legacy? Nel mio [profilo professionale](https://www.mauriziofonte.it/pages/about) trovi l'esperienza concreta su testing, refactoring e modernizzazione di applicazioni PHP 5.x-8.x. [Contattami per una consulenza diretta](https://www.mauriziofonte.it/pages/contattami).

## Cosa sono i characterization test e perché funzionano su codice legacy?

Un characterization test - chiamato anche [golden master test o approval test](https://understandlegacycode.com/blog/characterization-tests-or-approval-tests/) - non verifica una specifica corretta (come un unit test classico). Cattura l'output attuale del sistema per un dato input e lo salva come "risposta attesa". Da quel momento, se l'output cambia, il test fallisce. Non stai dicendo "il calcolo dell'IVA deve restituire 22%" - stai dicendo "con questi dati di input, il sistema attualmente restituisce questo output, e se l'output cambia dopo la mia modifica, voglio saperlo".

Questo approccio funziona su codice legacy perché non richiede di capire il codice internamente. Non devi sapere come funziona il calcolo dell'IVA per testarlo - devi solo sapere che con il prodotto X e la quantità Y il totale è Z. Se dopo una modifica il totale diventa W, il test te lo dice prima che il cliente se ne accorga.

La differenza rispetto ai test classici è fondamentale: i test classici richiedono una specifica chiara e codice testabile (classi con dipendenze iniettabili, separazione delle responsabilità). Il codice legacy non ha né l'una né l'altro. I characterization test accettano il codice com'è e lo fotografano.

## Il setup: PHPUnit su un progetto PHP legacy senza framework

Sul gestionale piemontese - PHP 5.6, nessun Composer, nessun autoloader, nessun framework - il primo passo è stato introdurre Composer e [PHPUnit](https://phpunit.de/) come dipendenza di sviluppo:

```bash
# Installare Composer (se non presente)
curl -sS https://getcomposer.org/installer | php
mv composer.phar /usr/local/bin/composer

# Inizializzare il progetto
cd /var/www/html
composer init --name="azienda/gestionale" --no-interaction
composer require --dev phpunit/phpunit

# Creare la struttura di test
mkdir -p tests/Feature
```

La configurazione `phpunit.xml` per un progetto legacy senza autoloader PSR-4:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<phpunit bootstrap="vendor/autoload.php" colors="true">
    <testsuites>
        <testsuite name="Feature">
            <directory>tests/Feature</directory>
        </testsuite>
    </testsuites>
    <php>
        <env name="APP_ENV" value="testing"/>
        <env name="DB_HOST" value="127.0.0.1"/>
        <env name="DB_NAME" value="gestionale_test"/>
    </php>
</phpunit>
```

Il database di test è una copia del database di produzione - stessa struttura, dati anonimizzati - perché i characterization test hanno bisogno di dati realistici per catturare il comportamento reale del sistema.

## I primi smoke test: HTTP endpoint come scatole nere

Il modo più rapido per testare un'applicazione PHP legacy è trattarla come una scatola nera: invii una richiesta HTTP e verifichi la risposta. Non serve capire il codice interno - serve solo sapere che l'endpoint risponde e che l'output è stabile.

```php
<?php
// tests/Feature/SmokeTest.php
use PHPUnit\Framework\TestCase;

class SmokeTest extends TestCase
{
    private string $baseUrl = 'http://127.0.0.1';

    /** @test */
    public function la_homepage_risponde_con_200(): void
    {
        $ch = curl_init("{$this->baseUrl}/index.php");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
        $body = curl_exec($ch);
        $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        $this->assertEquals(200, $code);
        $this->assertStringContainsString('Gestionale', $body);
    }

    /** @test */
    public function la_pagina_login_mostra_il_form(): void
    {
        $ch = curl_init("{$this->baseUrl}/login.php");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        $body = curl_exec($ch);
        $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        $this->assertEquals(200, $code);
        $this->assertStringContainsString('name="username"', $body);
        $this->assertStringContainsString('name="password"', $body);
    }

    /** @test */
    public function la_ricerca_prodotti_restituisce_risultati(): void
    {
        // Simulare un utente loggato con cookie di sessione
        $ch = curl_init("{$this->baseUrl}/search.php?q=valvola&cat=3");
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_COOKIE, "PHPSESSID=test_session_id");
        $body = curl_exec($ch);
        $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        $this->assertEquals(200, $code);
        // Il golden master: verifica che il numero di risultati sia stabile
        $this->assertStringContainsString('Trovati', $body);
    }
}
```

Questi test sono brutalmente semplici - e proprio per questo funzionano. Non verificano la logica interna, ma catturano il comportamento visibile. Se una modifica al calcolo dell'IVA rompe la ricerca prodotti (perché nel codice legacy tutto è accoppiato a tutto), il test sulla ricerca fallisce e lo scopri prima del deploy.

## Il golden master: catturare output complessi

Per funzionalità con output complesso - come la stampa di una bolla o il calcolo di un preventivo - uso la tecnica del golden master: salvo l'output completo in un file di riferimento e confronto le esecuzioni successive con quel file.

```php
<?php
// tests/Feature/GoldenMasterTest.php
class GoldenMasterTest extends TestCase
{
    /** @test */
    public function il_calcolo_totale_ordine_produce_output_stabile(): void
    {
        // Input fisso: ordine con 3 prodotti noti
        $orderId = 42;  // ordine di test con dati fissi nel DB di test
        $output = $this->callEndpoint("/api/order_total.php?id={$orderId}");

        $goldenFile = __DIR__ . '/golden/order_total_42.json';

        if (!file_exists($goldenFile)) {
            // Prima esecuzione: salva il golden master
            file_put_contents($goldenFile, $output);
            $this->markTestIncomplete('Golden master creato. Verificare manualmente e ri-eseguire.');
            return;
        }

        // Esecuzioni successive: confronta con il golden master
        $expected = file_get_contents($goldenFile);
        $this->assertEquals($expected, $output, 'Output cambiato rispetto al golden master');
    }
}
```

La prima esecuzione crea il golden master - lo sviluppatore deve verificare manualmente che l'output sia corretto e approvarlo. Da quel momento, qualsiasi cambiamento nell'output viene rilevato automaticamente. Se il cambiamento è intenzionale (perché hai corretto un bug), aggiorni il golden master. Se non è intenzionale, hai appena catturato un bug prima che arrivi in produzione.

Ho descritto tecniche più avanzate - smoke test con harness HTTP, snapshot testing e test di caratterizzazione su database - nell'articolo sull'[introduzione di test minimi su PHP legacy](https://www.mauriziofonte.it/blog/post/introdurre-test-minimi-php-legacy-smoke-harness-snapshot.html).

## CI gate: i test che bloccano il deploy

I test hanno valore solo se vengono eseguiti. Il pre-commit hook che installo assicura che nessun commit passi senza test verdi:

```bash
#!/bin/bash
# .git/hooks/pre-commit
echo "Esecuzione test..."
vendor/bin/phpunit --colors=never 2>&1
if [ $? -ne 0 ]; then
    echo "TEST FALLITI - commit bloccato"
    exit 1
fi
```

Sul gestionale piemontese, questo hook ha bloccato 12 commit nel primo mese - 12 modifiche che avrebbero rotto qualcosa in produzione e che invece sono state corrette prima di arrivare sul server. Dodici potenziali incidenti evitati, dodici volte in cui il collaboratore ha detto "meno male che il test mi ha fermato".

Il passo successivo - test in CI con GitHub Actions, analisi di copertura, e test di integrazione con database reale - è descritto nell'articolo sul [refactoring di codice PHP legacy](https://www.mauriziofonte.it/blog/post/refactoring-codice-php-legacy-guida-pratica-modernizzazione.html). Ma i characterization test con il pre-commit hook sono il minimo indispensabile che installo su ogni progetto legacy - meno di una settimana di lavoro per una riduzione misurabile dei bug in produzione.

Se il tuo codebase PHP legacy non ha test e ogni modifica è una scommessa, il costo di introdurre i primi 20-30 characterization test - una settimana di lavoro - si ripaga al primo bug evitato. [Contattami](https://www.mauriziofonte.it/pages/contattami) e costruiamo la rete di sicurezza per il tuo progetto.

Dall'articolo al lavoro vero

Se il codice di cui parla questo articolo è il tuo

Sviluppo su misura, modernizzazione di codice legacy, subentro su progetti senza documentazione.

[Vedi tre interventi con i numeri](https://www.mauriziofonte.it/programmatore-php.html)

Strumenti gratuiti per questo articolo

Funzionano nel browser, sullo stesso tema dell'articolo.

- [Migrazione database senza downtime](https://www.mauriziofonte.it/strumenti/migrazione-database-senza-downtime)
- [cURL a codice](https://www.mauriziofonte.it/strumenti/convertitore-curl-codice)

Ultima modifica: Martedì 14 Aprile 2026, alle 17:48 [« Articolo precedenteCome implementare Git su sistemi PHP legacy già in produzione senza downtime2 Settembre 2025](https://www.mauriziofonte.it/blog/post/implementare-git-sistemi-php-legacy-produzione-senza-downtime.html)[Articolo successivo »Audit di sicurezza per applicazioni PHP legacy: una guida pratica per identificare e risolvere le vulnerabilità4 Settembre 2025](https://www.mauriziofonte.it/blog/post/audit-sicurezza-php-legacy-guida-pratica-vulnerabilita.html)

### Articoli correlati a Introduzione ai test automatici su codebase PHP legacy: come iniziare senza riscrivere tutto

- [Come introdurre test minimi in un progetto PHP legacy senza bloccare lo sviluppo](https://www.mauriziofonte.it/blog/post/introdurre-test-minimi-php-legacy-smoke-harness-snapshot.html)

  Un gestionale PHP legacy con zero test e 3 regressioni al mese: ogni fix rompeva qualcosa. In 5 giorni ho introdotto 28 smoke test HTTP e 12 · 12 Settembre 2025

  ![Come introdurre test minimi in un progetto PHP legacy senza bloccare lo sviluppo](https://www.mauriziofonte.it/image/002300070-introdurre-test-minimi-php-legacy-smoke-harness-snapshot.jpg)
- [Refactoring del codice PHP legacy: guida pratica per modernizzare un'applicazione senza riscriverla](https://www.mauriziofonte.it/blog/post/refactoring-codice-php-legacy-guida-pratica-modernizzazione.html)

  Un gestionale PHP 5.6 con 23.000 righe, zero test e debito tecnico che rendeva ogni modifica un rischio: il cliente pagava il triplo per ogni · 5 Settembre 2025

  ![Refactoring del codice PHP legacy: guida pratica per modernizzare un'applicazione senza riscriverla](https://www.mauriziofonte.it/image/002250070-refactoring-codice-php-legacy-guida-pratica-modernizzazione.jpg)
- [Quale LLM locale ti dà ragione anche quando sbagli](https://www.mauriziofonte.it/blog/post/llm-locale-premessa-falsa-sycophancy-test-modelli-qwen-ornith-neohorse.html)

  Un assistente che ti dà ragione quando sbagli è più pericoloso di uno che non sa rispondere. Ho fatto a cinque modelli locali quattordici domande · 10 Novembre 2026

  ![Quale LLM locale ti dà ragione anche quando sbagli](https://www.mauriziofonte.it/image/006070070-llm-locale-premessa-falsa-sycophancy-test-modelli-qwen-ornith-neohorse.jpg)
- [Writing coding tasks that LLMs cannot fake](https://www.mauriziofonte.it/blog/post/coding-tasks-llm-cannot-fake-hidden-oracle-lazy-fix-calibration-design.html)

  Most agentic coding benchmarks stop being useful the day the models learn to pass them, and many never were: a task whose visible tests can be · 28 Ottobre 2026

  ![Writing coding tasks that LLMs cannot fake](https://www.mauriziofonte.it/image/006050070-coding-tasks-llm-cannot-fake-hidden-oracle-lazy-fix-calibration-design.jpg)
- [Determinism in local LLM output, measured run against run](https://www.mauriziofonte.it/blog/post/local-llm-deterministic-output-temperature-zero-llama-cpp-reproducibility.html)

  Ask a local model the same question twice at temperature zero and you expect the same answer. On a 16GB card with llama.cpp that held exactly · 16 Ottobre 2026

  ![Determinism in local LLM output, measured run against run](https://www.mauriziofonte.it/image/006020070-local-llm-deterministic-output-temperature-zero-llama-cpp-reproducibility.jpg)

---

**Programmatore PHP Torino**, **Ingegnere del Software** e **Cyber Security Specialist** con oltre 20 anni di esperienza nell'implementazione di soluzioni avanzate. Eseguo **porting di vecchi ambienti PHP** verso release più moderne (7.x o 8.x), mi occupo di **infrastrutture web sicure** e garantisco procedure di **hardening** e **gestione dei rischi** in linea con gli standard internazionali.  
Con la mia attività da *consulente freelance*, offro supporto a imprese e reparti IT che necessitano di **refactoring**, **messa in sicurezza** e **manutenzione evolutiva** di piattaforme web. Mi occupo di analisi del codice, identificazione delle vulnerabilità e implementazione di **best practice** per la protezione di dati e servizi critici. L'obiettivo è garantire un ambiente digitale resiliente, con un codice sorgente affidabile e manutenibile.

---

## Autore

**Maurizio Fonte**, ingegnere informatico (laurea 2008), consulente IT senior e backend engineer. Nel settore IT dal 2005, libero professionista con P.IVA dal 2014. Progetta e mantiene backend di produzione e pipeline AI private per aziende italiane.

Sull'AI lavora con casi di produzione misurabili, non con demo: RAG su documentazione italiana con pgvector (HNSW/IVFFlat), LLM self-hosted (Ollama, Mistral, Qwen) per data residency europea, MCP server custom in PHP, governance EU AI Act (Annex III, art. 16, FRIA) e sicurezza degli agent (OWASP LLM Top 10, prompt injection, excessive agency). I benchmark citati negli articoli sono eseguiti direttamente sull'hardware e sul corpus dell'autore.

## Perché questa fonte è attendibile

- **Esperienza diretta, non rassegna di terzi.** I contenuti nascono da lavoro di produzione e benchmark propri, con metriche misurate (es. un RAG self-hosted su 2.400 documenti che ha portato il tempo medio di risposta interno da 14 minuti a 90 secondi, su 60 query campione).
- **Verificabilità.** Ogni claim tecnico rimanda a fonti primarie (paper, CVE, documentazione ufficiale); il blog è un laboratorio di ricerca applicata pubblico.
- **Onestà metodologica.** Ogni soluzione dichiara anche quando NON va usata. "Production-grade, non demo-grade".

## Entità e contatti (verificabili)

Maurizio Fonte, Torino, Italia. P.IVA IT11396570019. REA TO-1331015 (Camera di Commercio di Torino).  
GitHub: https://github.com/mauriziofonte  
LinkedIn: https://www.linkedin.com/in/mauriziofonte  
Profilo: https://www.mauriziofonte.it/pages/about

---

## Come citare

> Maurizio Fonte, "Introduzione ai test automatici su codebase PHP legacy: come iniziare senza riscrivere tutto", mauriziofonte.it, 2025. https://www.mauriziofonte.it/blog/post/test-automatici-codebase-php-legacy-senza-riscrittura.html

Pubblicato: 2025-09-03 · Aggiornato: 2026-04-14.

**Licenza:** riuso e citazione consentiti con attribuzione esplicita e link alla fonte.
