Guida di LibreOffice 25.2
Il servizio UnitTest fornisce un framework per automatizzare i test unitari usando il linguaggio Basic, comprende le funzionalità per:
Aggregare i casi da verificare in suite di test e test unitari.
Condividere il codice di impostazione e di terminazione tra i vari casi sottoposti a test.
Visualizzare i risultati dei test usando la Console.
Sia i test unitari che il codice da verificare devono essere scritti in Basic. Il codice sottoposto a test può chiamare funzioni scritte in altri linguaggi.
Il servizio UnitTest non è disponibile per gli script in Python.
Un test case è la singola unità del test. Verifica una specifica risposta a un determinato insieme di input.
Nel servizio UnitTest, un test case è costituito da una singola Sub di Basic il cui nome inizia con un prefisso comune (quello predefinito è "Test_").
Il test case fallisce se uno dei metodi AssertX restituisce False.
Una test suite è una raccolta di test case che dovrebbero essere eseguiti assieme.
Tutti i test case di una test suite sono memorizzati in un singolo modulo di Basic.
Una test suite può implementare i metodi SetUp e TearDown per preparare i test case del modulo.
Un test unitario completo è costituito da un insieme di test suite all'interno della stessa libreria di Basic.
Prima di usare il servizio UnitTest è necessario caricare o importare le librerie ScriptForge:
È possibile invocare il servizio nel modo semplificato per chiamare le funzioni AssertX senza dover costruire una gerarchia completa di test suite e test case.
Nel modo semplificato, il servizio è invocato all'interno del test case, come mostrato nell'esempio seguente:
    Sub SimpleTest
        On Local Error GoTo CatchError
        Dim myTest As Variant
        myTest = CreateScriptService("UnitTest")
        ' Alcuni semplici test
        myTest.AssertEqual(1 + 1, 2)
        myTest.AssertEqual(1 - 1, 0)
        MsgBox("Tutti i controlli sono stati passati")
        Exit Sub
    CatchError:
        myTest.ReportError("Un controllo è fallito")
    End Sub
  In questo esempio, se una delle chiamate AssertEqual fallisce, l'interprete andrà all'etichetta CatchError e visualizzerà l'errore chiamando il metodo ReportError.
Quando è invocato nel modo completo, la creazione del servizio è esterna al codice del test e tutti i controlli sono organizzati in test case e test suite all'interno di una singola libreria.
L'esempio seguente crea un'istanza di UnitTest i cui controlli sono situati all'interno del documento corrente (ThisComponent) nella libreria "Tests".
    GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
    Dim myUnitTest As Variant
    myUnitTest = CreateScriptService("UnitTest", ThisComponent, "Tests")
  Si consideri un file ODS che contenga un modulo denominato "MathUtils" nella sua libreria "Standard" con il seguente codice:
    ' Codice nel modulo Standard.MathUtils
    Function Sum(a, b) As Double
        Sum = a + b
    End Function
    
    Function Multiply(a, b) As Double
        Multiply = a * b
    End Function
  Per creare una test suite completa, si presuma che una nuova libreria "Tests" venga creata nel file con all'interno un unico modulo "AllTests" contenente il seguente codice:
    ' Codice nel modulo Tests.AllTests
    Sub Main()
        GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
        Dim test As Variant
        test = CreateScriptService("UnitTest", ThisComponent, "Tests")
        test.RunTest("AllTests")
        test.Dispose()
    End Sub
    
    Sub Setup(test)
        ' Il codice di preparazione è eseguito prima del primo test case
        Dim exc As Variant
        exc = CreateScriptService("Exception")
        exc.Console(Modal := False)
    End Sub
    
    Sub TearDown(test)
        ' Codice di pulizia opzionale, chiamato dopo l'ultimo test case
    End Sub
    
    Sub Test_Sum(test)
        On Local Error GoTo CatchError
        test.AssertEqual(Sum(1, 1), 2, "Somma due interi positivi")
        test.AssertEqual(Sum(-10, 20), 10, "Somma di interi negativi e positivi")
        test.AssertEqual(Sum(1.5, 1), 2.5, "Somma di valori interi e a virgola mobile")
        Exit Sub
    CatchError:
        test.ReportError("Il metodo Sum non funziona")
    End Sub
    
    Sub Test_Multiply(test)
        On Local Error GoTo CatchError
        test.AssertEqual(Multiply(2, 2), 4, "Moltiplica due positivi interi")
        test.AssertEqual(Multiply(-4, 2), -8, "Moltiplica degli interi negativi e positivi")
        test.AssertEqual(Multiply(1.5, 3), 4.5, "Moltiplica dei valori interi e in virgola mobile")
        Exit Sub
    CatchError:
        test.ReportError("Il metodo Multiply non funziona")
    End Sub
  La test suite di cui sopra, è costituita da due test case Test_Sum e Test_Multiply. Per eseguire tutti i test eseguire semplicemente il metodo Main del modulo "AllTests".
La Console del servizio Exception è usata come output predefinito per visualizzare i risultati dei test. Dopo l'esecuzione dell'esempio di cui sopra, nella console sarà visualizzato il seguente output:
    ' RUNTEST ENTER testsuite='Tests.AllTests', pattern='Test_*'
    '   SETUP Tests.AllTests.Setup() ENTER
    '   SETUP Tests.AllTests.Setup() EXIT
    '   TESTCASE Tests.AllTests.Test_Multiply() ENTER
    '   TESTCASE Tests.AllTests.Test_Multiply() EXIT (0,017 sec)
    '   TESTCASE Tests.AllTests.Test_Sum() ENTER
    '   TESTCASE Tests.AllTests.Test_Sum() EXIT (0,016 sec)
    '   TEARDOWN Tests.AllTests.TearDown() ENTER
    '   TEARDOWN Tests.AllTests.TearDown() EXIT
    ' RUNTEST EXIT testsuite='Tests.AllTests' (0,223 sec)
  Se durante questi test uno dei metodi AssertEqual fallisce, nella console verrà aggiunto un messaggio di errore.
| Nome | Sola lettura | Tipo | Descrizione | 
|---|---|---|---|
| LongMessage | No | Boolean | Quando è impostato su True (predefinito) la console visualizza il messaggio standard accodato al messaggio definito da colui che effettua il test. Se è False, viene usato solo il messaggio definito da colui che effettua il test. | 
| ReturnCode | Sì | Integer | Valore restituito da RunTest dopo che il test unitario è terminato. Il seguente è un elenco dei possibili valori: 0 - Test terminato senza errori o test non avviato | 
| Verbose | No | Boolean | Quando è impostato a True, tutte le asserzioni sono visualizzate nella console (sia che falliscano o no). Se è False (predefinito), vengono visualizzate solo le asserzioni che falliscono. | 
| WhenAssertionFails | No | Integer | Stabilisce cosa fare quando una asserzione non è rispettata. Il seguente è un elenco dei valori possibili: 0 - Ignora il fallimento e continua a eseguire il test | 
Tutte le asserzioni verificano una o due espressioni, a cui nel resto di questa guida si fa riferimento come A e B. Questi sono sempre il primo o i primi due argomenti del metodo AssertX.
Tutti i metodi AssertX accettano un argomento message che specifica un messaggio personalizzato da visualizzare nella console relativamente a quella asserzione. Per impostazione predefinita è usata una stringa vuota. Questo argomento è sempre nell'ultima posizione dell'asserzione.
Alcuni metodi AssertX accettano anche degli argomenti aggiuntivi, descritti di seguito con le loro sintassi.
Restituisce True quando A e B sono valori numerici e sono considerati tra loro vicini, data una tolleranza relativa.
svc.AssertAlmostEqual(a: any, b: any, tolerance: double = 1E-09, message: str = ""): bool
Questa asserzione restituisce True se si verificano le due seguenti condizioni:
A e B possono essere convertiti nel tipo Double.
La differenza assoluta tra A e B divisa per il maggiore tra i valori assoluti di A e B è minore del valore di tolleranza (tolerance) specificato.
Restituisce True quando A e B sono considerati uguali.
svc.AssertEqual(a: any, b: any, message: str = ""): bool
Quando A e B sono scalari, viene restituito True se:
Entrambe le espressioni hanno lo stesso VarType o sono entrambe numeriche.
I valori booleani e numerici sono comparati con l'operatore =.
Le stringhe sono comparate con la funzione incorporata StrComp. Il confronto distingue tra minuscole e maiuscole.
Date e orari sono comparati fino al secondo.
Null, Empty e Nothing non sono uguali, ma AssertEqual(Nothing, Nothing) restituisce True.
Gli oggetti UNO sono comparati con il metodo incorporato EqualUnoObjects.
Da notare che gli oggetti di Basic non sono mai uguali.
Quando A e B sono matrici, viene restituito True se:
Entrambe le matrici hanno lo stesso numero di dimensioni (fino a 2 dimensioni) e i loro limiti inferiori e superiori sono identici per tutte le dimensioni.
Tutti gli elementi di entrambe le matrici sono uguali, uno per uno.
Due matrici vuote sono considerate uguali.
Restituisce True quando il tipo di A è Boolean e il suo valore è False.
svc.AssertFalse(a: any, message: str = ""): bool
Restituisce True quando A è maggiore di B.
svc.AssertGreater(a: any, b: any, message: str = ""): bool
Il confronto tra A e B presume quanto segue:
I tipi di dati possibili sono String, Date o un tipo numerico.
Entrambe le espressioni devono avere lo stesso VarType o entrambe devono essere numeriche.
Il confronto tra stringhe distingue tra maiuscole e minuscole.
Restituisce True quando A è maggiore o uguale a B.
svc.AssertGreaterEqual(a: any, b: any, message: str = ""): bool
Il confronto tra A e B presume quanto segue:
I tipi di dati possibili sono String, Date o un tipo numerico.
Entrambe le espressioni devono avere lo stesso VarType o entrambe devono essere numeriche.
Il confronto tra stringhe distingue tra maiuscole e minuscole.
Restituisce True quando A si trova all'interno di B.
svc.AssertIn(a: any, b: any, message: str = ""): bool
Questa asserzione presume quanto segue:
L'espressione B può essere una matrice unidimensionale, un oggetto Dictionary di ScriptForge o una stringa.
Quando l'espressione B è una matrice unidimensionale, l'espressione A può essere una data o un valore numerico.
Quando l'espressione B è un oggetto Dictionary di ScriptForge, la stringa A viene cercata tra le chiavi di B.
Il confronto tra stringhe distingue tra maiuscole e minuscole.
Restituisce True se A è un'istanza del tipo di oggetto specificato, indicato in formato stringa contenente il nome del tipo.
svc.AssertIsInstance(a: any, objecttype: str, message: str = ""): bool
L'espressione A può contenere uno dei seguenti elementi:
Un oggetto di ScriptForge. In questo caso, l'argomento objecttype è una stringa come "DICTIONARY", "calc", "Dialog", ecc.
Un oggetto UNO. In questo caso l'argomento objecttype deve essere una stringa identica al valore restituito dal metodo SF_Session.UnoObjectType().
Una matrice. In questo caso l'argomento objecttype è atteso come "array" (matrice).
Qualsiasi altra variabile (che non sia un Object o un Array). In questo caso l'argomento objecttype è una stringa corrispondente al valore restituito dalla funzione incorporata TypeName.
Restituisce True se A è un oggetto con valore Nothing.
svc.AssertIsNothing(a: any, message: str = ""): bool
Restituisce True quando A ha valore Null.
svc.AssertIsNull(a: any, message: str = ""): bool
Restituisce True quando A è minore di B.
svc.AssertLess(a: any, b: any, message: str = ""): bool
Il confronto tra A e B presume quanto segue:
I tipi di dati possibili sono String, Date o un tipo numerico.
Entrambe le espressioni devono avere lo stesso VarType o entrambe devono essere numeriche.
Il confronto tra stringhe distingue tra maiuscole e minuscole.
Restituisce True quando A è minore o uguale a B.
svc.AssertLessEqual(a: any, b: any, message: str = ""): bool
Il confronto tra A e B presume quanto segue:
I tipi di dati possibili sono String, Date o un tipo numerico.
Entrambe le espressioni devono avere lo stesso VarType o entrambe devono essere numeriche.
Il confronto tra stringhe distingue tra maiuscole e minuscole.
Restituisce True se la stringa A corrisponde al pattern indicato con dei caratteri jolly.
svc.AssertLike(a: any, pattern: str = "", message: str = ""): bool
Sono accettati i seguenti caratteri jolly:
? - Rappresenta qualunque carattere singolo.
* - Rappresenta nessuno, uno o più caratteri.
Restituisce True se A e B sono valori numerici e non sono considerati vicini l'uno all'altro in base a una tolleranza relativa.
svc.AssertNotAlmostEqual(a: any, b: any, tolerance: double = 1E-09, message: str = ""): bool
Questa asserzione restituisce True se si verificano le due seguenti condizioni:
A e B possono essere convertiti nel tipo Double.
La differenza assoluta tra A e B divisa per il valore assoluto maggiore tra A e B è maggiore del valore di tolleranza specificato in tolerance.
Restituisce True se A e B non sono considerati uguali.
svc.AssertNotEqual(a: any, b: any, message: str = ""): bool
Questo metodo funziona sia per gli scalari che per le matrici. Per maggiori informazioni sul significato di uguaglianza in questa asserzione si leggano le istruzioni in AssertEqual.
Restituisce True se A (una stringa) non viene trovata in B.
svc.AssertNotIn(a: any, b: any, message: str = ""): bool
Per maggiori informazioni sulle presunzioni di questo metodo si leggano le istruzioni in AssertIn.
Restituisce True se A non è un'istanza di uno specifico tipo di oggetto.
svc.AssertNotInstance(a: any, objecttype: str, message: str = ""): bool
Per maggiori informazioni sulle presunzioni di questo metodo si leggano le istruzioni in AssertIsInstance.
Restituisce True se la stringa A non corrisponde a un pattern indicato con dei caratteri jolly.
svc.AssertNotLike(a: any, pattern: str = "", message: str = ""): bool
Per maggiori informazioni sulle presunzioni di questo metodo si leggano le istruzioni in AssertLike.
Restituisce True tranne quando A è un oggetto con valore Nothing.
svc.AssertNotNothing(a: any, message: str = ""): bool
Restituisce True tranne quando A ha valore Null.
svc.AssertNotNull(a: any, message: str = ""): bool
Restituisce True quando A non è una stringa o non corrisponde all'espressione regolare specificata.
svc.AssertNotRegex(a: any, regex: str = "", message: str = ""): bool
Il confronto distingue tra maiuscole e minuscole.
Restituisce True se la stringa A corrisponde all'espressione regolare specificata.
svc.AssertRegex(a: any, regex: str = "", message: str = ""): bool
Il confronto distingue tra maiuscole e minuscole.
Restituisce True quando l'espressione A è di tipo Boolean e il suo valore è True.
svc.AssertTrue(a: any, message: str = ""): bool
Causa forzatamente il fallimento di un test.
svc.Fail(message: str = "")
È possibile fornire un messaggio da riportare nella console.
Scrive il messaggio indicato in message nella console.
svc.Log(message: str = "")
È possibile fornire un messaggio da riportare nella console.
Visualizza una finestra di dialogo con un messaggio e i valori correnti delle proprietà del servizio Exception.
Questo metodo è comunemente usato nella sezione per la gestione delle eccezioni delle Sub che contiene il test case, che viene raggiunto quando un'asserzione fallisce o quando viene chiamato il metodo Fail.
svc.ReportError(message: str = "")
A seconda del valore della proprietà WhenAssertionFails l'esecuzione del testo può continuare o essere interrotta.
Quando si scrivono i test case è raccomandata l'inclusione di una chiamata al metodo ReportError nella sezione della gestione delle eccezioni all'interno della Sub.
Se la proprietà LongMessage è uguale a True, il messaggio specificato in message è seguito dal messaggio standard di descrizione dell'errore. In caso contrario viene visualizzato solo message.
Esegue la test suite completa implementata nel modulo specificato. Ogni test case viene eseguito indipendentemente dagli altri.
L'esecuzione di una test suite comprende:
L'esecuzione del metodo opzionale Setup presente nel modulo.
L'esecuzione per una volta di ciascun test case, senza un ordine specifico.
L'esecuzione del metodo opzionale TearDown presente nel modulo.
svc.RunTest(testsuite: str, testcasepattern: str = "", message: str = ""): int
L'argomento testcasepattern specifica un pattern costituito dai caratteri jolly "?" e "*" per selezionare quale test case eseguire. Il confronto non distingue tra maiuscole e minuscole.
Se in message è fornito un messaggio, questo viene scritto nella console all'avvio del test.
Interrompe la test suite in esecuzione senza chiamare il metodo TearDown.
Saltare un test di solito ha senso nel metodo Setup quando non tutte le condizioni per l'esecuzione del test sono verificate.
È compito del metodo Setup uscire dalla Sub subito dopo la chiamata a SkipTest.
Se SkipTest viene chiamato all'interno di un test case, l'esecuzione della test suite viene interrotta e i restanti test case non sono eseguiti. Va ricordato che l'ordine in cui sono eseguiti i test case, presenti nella test suite, è arbitrario.
svc.SkipTest(message: str = "")
Se in message è fornito un messaggio, questo viene scritto nella console.