Quartz 4

FIRE 45.02 - Manuale Tecnico & Guida al Testing

4 min read

FIRE - Manuale Tecnico & Guida al Testing

Versione Applicazione: 0.3.0 (ipotizzata) Versione Documento: 4.0 Data: 2025-07-13

1. Scopo del Documento

Questo documento fornisce le linee guida operative per l’utilizzo, lo sviluppo e il testing della piattaforma FIRE. È rivolto a sviluppatori, QA e collaboratori interni. La conoscenza del flusso di lavoro standard è data per presupposta.

2. Architettura UI e Flusso Dati

L’interfaccia è composta da tre macro-componenti disaccoppiati:

  • Pannello di Controllo (BacktestTabWidget):

    • Input: Fornisce i parametri di base per un’esecuzione (ticker, date).

    • Output: Visualizza i risultati numerici (BacktestStatsModel) e invia i dati di plot al Charting Panel.

    • Responsabilità: Configurazione e visualizzazione dei risultati. Non contiene logica di business.

  • Editor di Strategie (StrategyEditorTab):

    • Input: Codice Python scritto dall’utente.

    • Output: Un percorso a un file .py valido.

    • Responsabilità: Gestione del codice sorgente della strategia. Non ha conoscenza dei parametri di backtest.

  • Pannello di Charting (ChartingTabsWidget):

    • Input: Un dizionario contenente DataFrame OHLC e Series di segnali.

    • Responsabilità: Rendering grafico dei dati. Non ha conoscenza della logica di backtest o di strategia.

Il flusso di orchestrazione è gestito dalla MainWindow, che intercetta gli eventi di richiesta di backtest, raccoglie i dati dai vari pannelli e istanzia il BacktestWorker.

3. Procedura di Esecuzione Standard (Workflow di Test)

Per eseguire un test end-to-end, seguire questi passaggi:

  1. Configurazione: Nel pannello Controls & Backtest, inserire un ticker valido per Yahoo Finance (es. MSFT) e un intervallo di date.

  2. Strategia: Nel Strategy Editor, caricare (Apri…) o scrivere una strategia Python valida.

    • La strategia DEVE essere una classe che eredita da fire.strategies.base_strategy.BaseStrategy.

    • La strategia DEVE implementare i metodi init(self) e next(self).

  3. Salvataggio: La strategia DEVE essere salvata su disco prima dell’esecuzione. L’applicazione richiederà un salvataggio se il file è nuovo.

  4. Esecuzione: Cliccare “Esegui Backtest” da uno dei due pannelli.

  5. Verifica:

    • Log Panel: Controllare l’output per messaggi di stato o ERROR/CRITICAL. Un traceback qui indica un errore nel codice Python della strategia o nel worker.

    • Backtest Report: Verificare che la tabella delle statistiche sia popolata con dati coerenti.

    • Charting Panel: Verificare che i segnali (triangoli) siano renderizzati correttamente sul grafico in corrispondenza delle date di trade.

4. API delle Strategie (BaseStrategy)

Qualsiasi strategia eseguibile deve aderire a questa API.

Metodi Obbligatori:

  • init(self): Eseguito una sola volta prima del ciclo. Usare per pre-calcolare indicatori e inizializzare lo stato.

    • Accesso Dati: self.data (DataFrame Pandas completo OHLCV).

  • next(self): Eseguito per ogni riga del DataFrame self.data. Contiene la logica decisionale.

Attributi e Metodi Disponibili in next(self):

MembroTipoDescrizione
self.iintIndice numerico (posizione) della riga corrente (barra).
self.openfloatValore Open della barra corrente.
self.highfloatValore High della barra corrente.
self.lowfloatValore Low della barra corrente.
self.closefloatValore Close della barra corrente.
self.volumefloatValore Volume della barra corrente.
self.buy()methodEsegue un ordine di acquisto al prezzo Close della barra corrente.
self.sell()methodEsegue un ordine di vendita al prezzo Close della barra corrente.
self.close_position()methodAlias per self.sell(). Chiude una posizione long esistente.

Esempio di Codice di Riferimento (Test Case Base)

Usare questo codice come base per testare la funzionalità del motore. Produce trade verificabili.

code Python

downloadcontent_copy

expand_less

`# Test Case: SMA Crossover Strategy from fire.strategies.base_strategy import BaseStrategy  class SmaCrossoverStrategy(BaseStrategy):     fast_period = 50     slow_period = 100      def init(self):         # Il calcolo vettorizzato è lo standard di performance atteso.         self.sma_fast = self.data['Close'].rolling(window=self.fast_period).mean()         self.sma_slow = self.data['Close'].rolling(window=self.slow_period).mean()         self.position_open = False      def next(self):         # Ignora le barre iniziali dove gli indicatori non sono validi.         if self.i < self.slow_period:             return          # Accede ai dati pre-calcolati usando l'indice posizionale .iloc         sma_fast_current = self.sma_fast.iloc[self.i]         sma_slow_current = self.sma_slow.iloc[self.i]          # Logica di entrata         if sma_fast_current > sma_slow_current and not self.position_open:             self.buy()             self.position_open = True                  # Logica di uscita         elif sma_fast_current < sma_slow_current and self.position_open:             self.sell()             self.position_open = False`

5. Punti di Attenzione per il Testing e Debugging

  • Errori di Sintassi nella Strategia: Un errore di sintassi Python nel file .py della strategia causerà un fallimento nel strategy_loader. Il traceback completo sarà visibile nel Log Panel.

  • Errori a Runtime nella Strategia: Un errore logico (es. IndexError, KeyError) nel metodo next() causerà il fallimento del BacktestWorker. Il traceback sarà visibile nel Log Panel.

  • Nessun Trade Eseguito: Se le statistiche riportano 0 trade, il problema è al 99% nella logica condizionale if/elif del metodo next(). Le condizioni di entrata/uscita non si sono mai verificate.

  • Mancata Visualizzazione dei Segnali: Se le statistiche mostrano dei trade ma i segnali non appaiono sul grafico, il problema risiede nel “contratto” di dati tra BacktestTabWidget e ChartingTabsWidget. Verificare che le chiavi del dizionario (ohlc_data, buy_signals, sell_signals) e il formato dei dati (DataFrame/Series) siano corretti.

  • Performance: Il pre-calcolo degli indicatori in init() è fondamentale. Strategie che eseguono calcoli pesanti (es. rolling().mean()) all’interno del ciclo next() subiranno un degrado significativo delle performance.

Graph View