Service SFUnitTests.UnitTest

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.

Définitions

Scénario de test

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.

Suite de tests

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.

Test unitaire

Un test unitaire complet consiste en un ensemble de suites de tests dans la même bibliothèque Basic.

Invocation du service

Avant d'utiliser le service UnitTest, la bibliothèque ScriptForge doit être chargée ou importée :

• Les macros Basic nécessitent de charger la bibliothèque ScriptForge à l'aide de l'instruction suivante :
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Les scripts Python nécessitent un import depuis le module scriptforge :
from scriptforge import CreateScriptService

Mode simple

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.

Mode complet

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

Un exemple minimaliste en mode complet

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.

Propriétés

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é 1 - Une assertion dans un scénario de test a renvoyé False 2 - Un SkipTest a été émis par le Méthode Setup ou par l'un des cas de tests. 3 - Fin de test anormale
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 1 - La méthode TearDown du module est exécutée dans la suite de tests actuelle et la suite suivante est démarrée (par défaut en mode complet). 2 - Arrêter immédiatement (par défaut en mode simple)

Liste des méthodes dans le service the UnitTest
AssertAlmostEqual AssertEqual AssertFalse AssertGreater AssertGreaterEqual AssertIn AssertIsInstance AssertIsNothing AssertLike	AssertNotRegex AssertIsNull AssertLess AssertLessEqual AssertNotAlmostEqual AssertNotEqual AssertNotIn AssertNotInstance AssertNotLike	AssertNotNothing AssertNotNull AssertRegex AssertTrue Fail Log ReportError RunTest SkipTest

Arguments des méthodes AssertX

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.

AssertAlmostEqual

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.

Syntaxe :

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.

AssertEqual

Renvoie True lorsque A et B sont considérés comme égaux.

Syntaxe :

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.

AssertFalse

Renvoie True lorsque le type de A est Boolean et que sa valeur est False.

Syntaxe :

svc.AssertFalse(a: any, message: str = ""): bool

AssertGreater

Renvoie True lorsque A est supérieur à B.

Syntaxe :

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.

AssertGreaterEqual

Renvoie True lorsque A est supérieur ou égal à B.

Syntaxe :

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.

AssertIn

Renvoie True lorsque A est trouvé dans B.

Syntaxe :

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.

AssertIsInstance

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.

Syntaxe :

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.

AssertIsNothing

Renvoie True lorsque A est un objet qui a la valeur Nothing.

Syntaxe :

svc.AssertIsNothing(a: any, message: str = ""): bool

AssertIsNull

Renvoie True lorsque A a la valeur Null.

Syntaxe :

svc.AssertIsNull(a: any, message: str = ""): bool

AssertLess

Renvoie True lorsque A est inférieur à B.

Syntaxe :

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.

AssertLessEqual

Renvoie True lorsque A est inférieur ou égal à B.

Syntaxe :

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.

AssertLike

Renvoie True si la chaîne A correspond à un modèle donné contenant des caractères génériques.

Syntaxe :

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.

AssertNotAlmostEqual

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.

Syntaxe :

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.

AssertNotEqual

Renvoie True lorsque A et B ne sont pas considérés comme égaux.

Syntaxe :

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.

AssertNotIn

Renvoie True lorsque A (une chaîne) n'est pas trouvée dans B.

Syntaxe :

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.

AssertNotInstance

Renvoie True lorsque A n'est pas une instance d'un type d'objet spécifié.

Syntaxe :

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.

AssertNotLike

Renvoie True si la chaîne A ne correspond pas à un modèle donné contenant des caractères génériques.

Syntaxe :

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.

AssertNotNothing

Renvoie True sauf lorsque A est un objet qui a la valeur Nothing.

Syntaxe :

svc.AssertNotNothing(a: any, message: str = ""): bool

AssertNotNull

Renvoie True sauf lorsque A a la valeur Null.

Syntaxe :

svc.AssertNotNull(a: any, message: str = ""): bool

AssertNotRegex

Renvoie True lorsque A n'est pas une chaîne ou ne correspond pas à l'expression régulière donnée.

Syntaxe :

svc.AssertNotRegex(a: any, regex: str = "", message: str = ""): bool

La comparaison est sensible à la casse.

AssertRegex

Renvoie True lorsque la chaîne A correspond à l'expression régulière donnée.

Syntaxe :

svc.AssertRegex(a: any, regex: str = "", message: str = ""): bool

La comparaison est sensible à la casse.

AssertTrue

Renvoie True lorsque l'expression A est un Boolean et que sa valeur est True.

Syntaxe :

svc.AssertTrue(a: any, message: str = ""): bool

Fail

Force l’échec d’un scénario de test.

Syntaxe :

svc.Fail(message: str = "")

Un message peut être fourni pour être signalé dans la console.

Log

Écrit le message spécifié dans la console.

Syntaxe :

svc.Log(message: str = "")

Un message peut être fourni pour être signalé dans la console.

ReportError

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.

Syntaxe :

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é.

RunTest

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.

Syntaxe :

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.

SkipTest

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.

Syntaxe :

svc.SkipTest(message: str = "")

Si un message est fourni, il est écrit sur la console.

Service ScriptForge.Exception