Aide LibreOffice 25.2
Le service UnitTest fournit un cadre pour automatiser les tests unitaires à l'aide du langage Basic, notamment la possibilité de :
Regrouper les cas de test en suites de tests et en tests unitaires.
Partager le code de configuration et d’arrêt entre les scénarios de test.
Rapporter les résultats des tests à l'aide de la Console.
Les tests unitaires et le code à tester doivent être écrits en Basic. Le code testé peut appeler des fonctions écrites dans d'autres langages.
Le service UnitTest n'est pas disponible pour les scripts Python.
Un scénario de test est l’unité individuelle de test. Il vérifie une réponse spécifique à un ensemble particulier d’entrées.
Dans le service UnitTest, un scénario de test est représenté par un seul Sub Basic dont le nom commence par un préfixe commun (la valeur par défaut est "Test_").
Le scénario de test échoue si l'une des méthodes AssertX renvoie False.
Une suite de tests est un ensemble de scénarios de tests qui doivent être exécutés ensemble.
Tous les scénarios de test d'une suite de tests sont stockés dans un seul module Basic.
Une suite de tests peut implémenter les méthodes SetUp et TearDown pour préparer les cas de test dans son module.
Un test unitaire complet consiste en un ensemble de suites de tests dans la même bibliothèque Basic.
Avant d'utiliser le service UnitTest, la bibliothèque ScriptForge doit être chargée ou importée :
Invoquez le service en simple mode pour appeler les fonctions AssertX sans avoir à créer la hiérarchie complète des suites de tests et des scénarios de test.
En mode simple, le service est invoqué dans le scénario de test, comme le montre l'exemple ci-dessous :
    Sub SimpleTest
        On Local Error GoTo CatchError
        Dim myTest As Variant
        myTest = CreateScriptService("UnitTest")
        ' Quelques tests factices
        myTest.AssertEqual(1 + 1, 2)
        myTest.AssertEqual(1 - 1, 0)
        MsgBox("All tests passed")
        Exit Sub
    CatchError:
        myTest.ReportError("A test failed")
    End Sub
  Dans cet exemple, si l'un des appels AssertEqual échoue, l'interpréteur ira à l'étiquette CatchError et signalera l'erreur en appelant la méthode ReportError.
Lorsqu'elle est invoquée en mode complet, la création du service est externe au code de test et tous les tests sont organisés en scénarios de tests et suites de tests au sein d'une seule bibliothèque.
L'exemple suivant crée une instance UnitTest dont les tests sont situés à l'intérieur du document actuel (ThisComponent) dans la bibliothèque "Tests".
    GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
    Dim myUnitTest As Variant
    myUnitTest = CreateScriptService("UnitTest", ThisComponent, "Tests")
  Considérons qu'un fichier ODS possède un module nommé « MathUtils » dans sa bibliothèque « Standard » avec le code suivant :
    ' Code dans le module Standard.MathUtils
    Function Sum(a, b) As Double
        Sum = a + b
    End Function
    
    Function Multiply(a, b) As Double
        Multiply = a * b
    End Function
  Pour créer une suite de tests complète, considérez qu'une nouvelle bibliothèque nommée "Tests" est créée dans le fichier avec un seul module "AllTests" contenant le code ci-dessous :
    ' Code dans le module 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)
        ' Le code de préparation a été exécuté avant le premier scénario de test
        Dim exc As Variant
        exc = CreateScriptService("Exception")
        exc.Console(Modal := False)
    End Sub
    
    Sub TearDown(test)
        ' Code de nettoyage facultatif appelé après le dernier scénario de test
    End Sub
    
    Sub Test_Sum(test)
        On Local Error GoTo CatchError
        test.AssertEqual(Sum(1, 1), 2, "Sum two positive integers")
        test.AssertEqual(Sum(-10, 20), 10, "Sum of negative and positive integers")
        test.AssertEqual(Sum(1.5, 1), 2.5, "Sum of float and integer values")
        Exit Sub
    CatchError:
        test.ReportError("Sum method is broken")
    End Sub
    
    Sub Test_Multiply(test)
        On Local Error GoTo CatchError
        test.AssertEqual(Multiply(2, 2), 4, "Multiply two positive integers")
        test.AssertEqual(Multiply(-4, 2), -8, "Multiply negative and positive integers")
        test.AssertEqual(Multiply(1.5, 3), 4.5, "Multiply of float and integer values")
        Exit Sub
    CatchError:
        test.ReportError("Multiply method is broken")
    End Sub
  La suite de tests ci-dessus se compose de deux cas de test Test_Sum et Test_Multiply. Pour exécuter tous les tests, exécutez simplement la méthode Main à partir du module "AllTests".
La Console du service Exception est utilisée comme sortie par défaut pour imprimer les résultats des tests. Après avoir exécuté l'exemple ci-dessus, le résultat suivant s'affichera dans la console :
    ' 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)
  Si l'une des méthodes AssertEqual échoue lors de ces tests, un message d'erreur est ajouté à la console.
| Nom | En lecture seule | Type | Description | 
|---|---|---|---|
| LongMessage | Non | Boolean | Lorsqu'elle est définie sur True (par défaut), la console affiche le message standard ajouté au message fourni par le testeur. Lorsque False, seul le message défini par le testeur est utilisé. | 
| ReturnCode | Oui | Integer | Valeur renvoyée par RunTest une fois le test unitaire terminé. Voici ensuite une liste de valeurs possibles : 0 - Test terminé sans erreurs ou test non démarré | 
| Verbose | Non | Boolean | Lorsqu'elle est définie sur True, toutes les assertions sont signalées dans la console (en échec ou non). Lorsque False (par défaut), seules les assertions défaillantes sont signalées. | 
| WhenAssertionFails | Non | Integer | Définit ce qui est fait lorsqu'une assertion échoue. Voici ensuite une liste de valeurs possibles : 0 - Ignorer l'échec et continuer à exécuter le test | 
Toutes les assertions testent une ou deux expressions, référencées dans le reste de cette page d'aide par A et B. Il s'agit toujours du ou des deux premiers arguments de la méthode AssertX.
Toutes les méthodes AssertX acceptent un argument message spécifiant un message personnalisé à signaler dans la console concernant l'assertion. Par défaut, une chaîne vide est utilisée. Cet argument est toujours en dernière position de l'assertion.
Certaines méthodes AssertX acceptent également des arguments supplémentaires, comme décrit par leurs syntaxes ci-dessous.
Renvoie True lorsque A et B sont des valeurs numériques et sont considérées comme proches l'une de l'autre, compte tenu d'une tolérance relative.
svc.AssertAlmostEqual(a: any, b: any, tolerance: double = 1E-09, message: str = ""): bool
Cette assertion renvoie True si les deux conditions ci-dessous sont remplies :
A et B peuvent être convertis en type Double.
La différence absolue entre A et B divisée par la plus grande valeur absolue de A ou B est inférieure à la valeur spécifiée dans tolerance.
Renvoie True lorsque A et B sont considérés comme égaux.
svc.AssertEqual(a: any, b: any, message: str = ""): bool
Lorsque A et B sont des scalaires, True est renvoyé si :
Les deux expressions ont le même VarType ou sont toutes deux numériques.
Les valeurs booléennes et numériques sont comparées avec l'opérateur =.
Les chaînes sont comparées avec la fonction intégrée StrComp. La comparaison est sensible à la casse.
Les dates et heures sont comparées à la seconde près.
Null, Empty et Nothing ne sont pas égaux, mais AssertEqual(Nothing, Nothing) renvoie True.
Les objets UNO sont comparés à la méthode intégrée EqualUnoObjects.
Notez que les objets Basic ne sont jamais égaux.
Lorsque A et B sont des matrices, True est renvoyé si :
Les deux matrices ont le même nombre de dimensions (jusqu'à 2 dimensions) et leurs limites inférieure et supérieure sont identiques pour toutes les dimensions.
Tous les éléments des deux matrices sont égaux, un par un.
Deux matrices vides sont considérées comme égales.
Renvoie True lorsque le type de A est Boolean et que sa valeur est False.
svc.AssertFalse(a: any, message: str = ""): bool
Renvoie True lorsque A est supérieur à B.
svc.AssertGreater(a: any, b: any, message: str = ""): bool
La comparaison entre A et B suppose ce qui suit :
Les types de données éligibles sont String, Date ou numérique.
Les deux expressions doivent avoir le même VarType ou les deux doivent être numériques.
Les comparaisons de chaînes sont sensibles à la casse.
Renvoie True lorsque A est supérieur ou égal à B.
svc.AssertGreaterEqual(a: any, b: any, message: str = ""): bool
La comparaison entre A et B suppose ce qui suit :
Les types de données éligibles sont String, Date ou numérique.
Les deux expressions doivent avoir le même VarType ou les deux doivent être numériques.
Les comparaisons de chaînes sont sensibles à la casse.
Renvoie True lorsque A est trouvé dans B.
svc.AssertIn(a: any, b: any, message: str = ""): bool
Cette assertion suppose ce qui suit :
L'expression B peut être une matrice 1D, un objet ScriptForge Dictionary ou une chaîne.
Lorsque l'expression B est une matrice 1D, l'expression A peut être une date ou une valeur numérique.
Lorsque l'expression B est un objet ScriptForge Dictionary, alors la chaîne A est recherchée parmi les clés de B.
Les comparaisons de chaînes sont sensibles à la casse.
Renvoie True lorsque A est une instance d'un type d'objet spécifié, spécifié sous forme de chaîne contenant le nom du type.
svc.AssertIsInstance(a: any, objecttype: str, message: str = ""): bool
L'expression A peut être l'une des suivantes :
Un objet ScriptForge. Dans ce cas, l'argument objecttype est une chaîne telle que "DICTIONARY", "calc", "Dialog", etc.
Un objet UNO. Dans ce cas, l'argument objecttype doit être une chaîne identique à la valeur renvoyée par la méthode SF_Session.UnoObjectType().
Une matrice. Dans ce cas, l'argument objecttype devrait être "array".
Toute autre variable (ni un Object ni un Array). Dans ce cas, objecttype est une chaîne correspondant à la valeur renvoyée par la fonction intégrée TypeName.
Renvoie True lorsque A est un objet qui a la valeur Nothing.
svc.AssertIsNothing(a: any, message: str = ""): bool
Renvoie True lorsque A a la valeur Null.
svc.AssertIsNull(a: any, message: str = ""): bool
Renvoie True lorsque A est inférieur à B.
svc.AssertLess(a: any, b: any, message: str = ""): bool
La comparaison entre A et B suppose ce qui suit :
Les types de données éligibles sont String, Date ou numérique.
Les deux expressions doivent avoir le même VarType ou les deux doivent être numériques.
Les comparaisons de chaînes sont sensibles à la casse.
Renvoie True lorsque A est inférieur ou égal à B.
svc.AssertLessEqual(a: any, b: any, message: str = ""): bool
La comparaison entre A et B suppose ce qui suit :
Les types de données éligibles sont String, Date ou numérique.
Les deux expressions doivent avoir le même VarType ou les deux doivent être numériques.
Les comparaisons de chaînes sont sensibles à la casse.
Renvoie True si la chaîne A correspond à un modèle donné contenant des caractères génériques.
svc.AssertLike(a: any, pattern: str = "", message: str = ""): bool
Les caractères génériques suivants sont acceptés :
? - Représente n'importe quel caractère.
* - Représente zéro, un ou plusieurs caractères.
Renvoie True lorsque A et B sont des valeurs numériques et ne sont pas considérées comme proches l'une de l'autre, étant donné un tolérance relative.
svc.AssertNotAlmostEqual(a: any, b: any, tolerance: double = 1E-09, message: str = ""): bool
Cette assertion renvoie True si les deux conditions ci-dessous sont remplies :
A et B peuvent être convertis en type Double.
La différence absolue entre A et B divisée par la plus grande valeur absolue de A ou B est supérieure à la valeur spécifiée dans tolerance.
Renvoie True lorsque A et B ne sont pas considérés comme égaux.
svc.AssertNotEqual(a: any, b: any, message: str = ""): bool
Cette méthode fonctionne à la fois pour les scalaires et les matrices. Lisez les instructions de AssertEqual pour plus d'informations sur ce que signifie l'égalité dans cette assertion.
Renvoie True lorsque A (une chaîne) n'est pas trouvée dans B.
svc.AssertNotIn(a: any, b: any, message: str = ""): bool
Lisez les instructions de AssertIn pour plus d'informations sur les hypothèses de cette méthode.
Renvoie True lorsque A n'est pas une instance d'un type d'objet spécifié.
svc.AssertNotInstance(a: any, objecttype: str, message: str = ""): bool
Lisez les instructions de AssertIsInstance pour plus d'informations sur les hypothèses de cette méthode.
Renvoie True si la chaîne A ne correspond pas à un modèle donné contenant des caractères génériques.
svc.AssertNotLike(a: any, pattern: str = "", message: str = ""): bool
Lisez les instructions de AssertLike pour plus d'informations sur les hypothèses de cette méthode.
Renvoie True sauf lorsque A est un objet qui a la valeur Nothing.
svc.AssertNotNothing(a: any, message: str = ""): bool
Renvoie True sauf lorsque A a la valeur Null.
svc.AssertNotNull(a: any, message: str = ""): bool
Renvoie True lorsque A n'est pas une chaîne ou ne correspond pas à l'expression régulière donnée.
svc.AssertNotRegex(a: any, regex: str = "", message: str = ""): bool
La comparaison est sensible à la casse.
Renvoie True lorsque la chaîne A correspond à l'expression régulière donnée.
svc.AssertRegex(a: any, regex: str = "", message: str = ""): bool
La comparaison est sensible à la casse.
Renvoie True lorsque l'expression A est un Boolean et que sa valeur est True.
svc.AssertTrue(a: any, message: str = ""): bool
Force l’échec d’un scénario de test.
svc.Fail(message: str = "")
Un message peut être fourni pour être signalé dans la console.
Écrit le message spécifié dans la console.
svc.Log(message: str = "")
Un message peut être fourni pour être signalé dans la console.
Affiche une boîte de message avec un message et les valeurs de propriété actuelles du service Exception.
Cette méthode est couramment utilisée dans la section de gestion des exceptions du Sub contenant le scénario de test, qui est atteint lorsqu'une assertion échoue ou lorsque la méthode Fail est appelée.
svc.ReportError(message: str = "")
Selon la valeur de la propriété WhenAssertionFails, l'exécution du test peut continuer ou être interrompue.
Lors de l'écriture de scénarios de test, il est recommandé d'inclure un appel à la méthode ReportError dans la section de gestion des exceptions du Sub.
Si la propriété LongMessage est égale à True, le message spécifié est suivi de la description du message d'erreur standard. Sinon seul le message est affiché.
Exécute la suite de tests complète implémentée dans le module spécifié. Chaque scénario de test est exécuté indépendamment les uns des autres.
L'exécution d'une suite de tests consiste à :
Exécuter la méthode facultative Setup présente dans le module.
Exécuter une fois chaque scénario de test, sans ordre spécifique.
Exécuter la méthode facultative TearDown présente dans le module.
svc.RunTest(testsuite: str, testcasepattern: str = "", message: str = ""): int
L'argument testcasepattern spécifie un modèle composé de "?" et les caractères génériques "*" pour sélectionner les cas de test à exécuter. La comparaison n'est pas sensible à la casse.
Si un message est fourni, il est écrit sur la console au démarrage du test.
Interrompt la suite de tests en cours d'exécution sans appeler la méthode TearDown.
Ignorer un test est généralement utile lors de la méthode Setup lorsque toutes les conditions pour exécuter le test ne sont pas remplies.
Il appartient à la méthode Setup de quitter le Sub peu de temps après l'appel SkipTest.
Si SkipTest est appelé depuis un scénario de test, l'exécution de la suite de tests est interrompue et les scénarios de test restants ne sont pas exécutés. Gardez à l’esprit que l’ordre dans lequel les cas de test sont exécutés est arbitraire au sein d’une suite de tests.
svc.SkipTest(message: str = "")
Si un message est fourni, il est écrit sur la console.