Tjenesten SFUnitTests.UnitTest

Tjenesten UnitTest giver en struktur til at automatisere enhedstests i Basic-sproget, inklusive muligheden for at:

Samle testcases i testsamlinger og enhedstests.
Dele opsætning- og nedluknings-kode mellem testcases.
Rapportere testresultater ved hjælp af Console (konsol).

Både enhedstests og koden, der skal testes, skal være skrevet i Basic. Koden, som testes, kan kalde funktioner skrevet i andre sprog.

UnitTest-tjenesten er ikke tilgængelig for Python-scripts.

Definitioner

Testcase

En testcase er den individuelle testenhed. Den afprøver et specifikt respons til et bestemt set af input.

I UnitTest-tjenesten bliver en testcase repræsenteret med en enkelt Basic-Sub, hvis navn begynder med et fælles præfiks (standardpræfikset er "Test_").

Testcasen fejler hvis en af AssertX-metoderne returnerer False.

Testsamling

En testsamling er en samling af testcases, som er beregnet på at udføres sammen.

Alle testcases i en testsamling er gemt i et enkelt Basic-modul.

En testsamling kan implementere metoderne SetUp (opsæt) og TearDown (nedriv) til at forberede testcasene i dens modul.

Komponenttest

En fuld enhedstest består af et sæt af testcases i det samme Basic-bibliotek

Kald af tjeneste

Før du bruger tjenesten UnitTest skal ScriptForge-biblioteket være indlæst eller importeret:

• Basic-makroer kræver, at biblioteket ScriptForge indlæses med følgende udtryk:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python-scripts kræver import af scriptforge-modulet:
from scriptforge import CreateScriptService

Enkel tilstand

Kald tjenesten i simpel tilstand for at kalde AssertX-funktioner, uden at du behøver at bygge hele hierarkiet af testsamlinger og testcases.

I simpel tilstand kaldes tjenesten inde fra testcasen, som vist i eksemplet herunder:


    Sub SimpleTest
        On Local Error GoTo CatchError
        Dim myTest As Variant
        myTest = CreateScriptService("UnitTest")
        ' Nogle få dummy-tests
        myTest.AssertEqual(1 + 1, 2)
        myTest.AssertEqual(1 - 1, 0)
        MsgBox("Alle tests bestået")
        Exit Sub
    CatchError:
        myTest.ReportError("An test fejlede")
    End Sub

I dette eksempel sker det, at hvis nogen af AssertEqual-kaldende fejler, vil fortolkeren gå til CatchError-etiketten og rapportere fejlen ved at kalde metoden ReportError.

Fuld tilstand

Når tjenesten kaldes i fuld tilstand, er oprettelsen af tjenesten ekstern i forhold til testkoden, og alle tests er organiserede i testcases og testsamlinger i et samlet bibliotek.

Det følgende eksempel opretter en UnitTest-instans, hvis tests er placeret i det aktuelle dokument (ThisComponent) i biblioteket "Tests".


    GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
    Dim myUnitTest As Variant
    myUnitTest = CreateScriptService("UnitTest", ThisComponent, "Tests")

Et minimalistisk eksempel i fuld tilstand

Antag, at en ODS-fil har et modul kaldet "MathUtils" i dets "Standard"-bibliotek, med den følgende kode:


    ' Kode i modulet Standard.MathUtils
    Function Sum(a, b) As Double
        Sum = a + b
    End Function
    
    Function Multiply(a, b) As Double
        Multiply = a * b
    End Function

For at oprette en fuld testsamling, tænk på et nyt bibliotek med navnet "Test" oprettet i filen med et enkelt modul "AllTests", som indeholder koden herunder:


    ' Kode i modulet 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)
        ' Forberedelseskode, som blev udfør forud for den første testcase
        Dim exc As Variant
        exc = CreateScriptService("Exception")
        exc.Console(Modal := False)
    End Sub
    
    Sub TearDown(test)
        ' Valgfri oprydningskode, som kaldes efter den sidste testcase
    End Sub
    
    Sub Test_Sum(test)
        On Local Error GoTo CatchError
        test.AssertEqual(Sum(1, 1), 2, "Sum af to positive heltal")
        test.AssertEqual(Sum(-10, 20), 10, "Sum af negative og positive heltal")
        test.AssertEqual(Sum(1.5, 1), 2.5, "Sum af decimaltal og heltal")
        Exit Sub
    CatchError:
        test.ReportError("Metoden Sum virker ikke")
    End Sub
    
    Sub Test_Multiply(test)
        On Local Error GoTo CatchError
        test.AssertEqual(Multiply(2, 2), 4, "Multiplikation af to positive heltal")
        test.AssertEqual(Multiply(-4, 2), -8, "Multiplikation af negative og positive heltal")
        test.AssertEqual(Multiply(1.5, 3), 4.5, "Multiplikation af decimaltal og heltal")
        Exit Sub
    CatchError:
        test.ReportError("Metoden Multiply virker ikke")
    End Sub

Testsamlingen ovenfor består af to testcases Test_Sum og Test_Multiply. For at udføre alle tests, udfør Main-metoden fra "AllTests"-modulet.

Metoden Console fra Exception-tjenesten bliver brugt som standardoutput til at udskrive testresultater. Efter afvikling af eksemplet ovenfor vil følgende output blive vist i konsollen:


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

Hvis nogen af AssertEqual-metoderne fejler under disse tests, bliver en fejlmeddelelse tilføjet til konsollen.

Egenskaber

Navn	Skrivebeskyttet	Type	Beskrivelse
LongMessage	Nej	Boolean	Når sat til True (standard), viser konsollen standardbeskeden i forlængelse af beskeden fra testeren. Når False, bruges kun beskeden fra testeren.
ReturnCode	Ja	Integer	Værdi returneret af RunTest efter at enhedstesten er afsluttet. Her følger en liste over mulige værdier: 0 – Test afsluttet uden fejl, eller test ikke startet 1 – En påstand (assertion) i en testcase returnerede False 2 – En SkipTest blev udført af Setup-metoden eller af en af testcasene 3 – Unormal afslutning af test
Verbose	Nej	Boolean	Når sat til True, bliver alle påstande (assertions) rapporteret i konsollen (med eller uden fejl). Når False (standard), bliver kun påstande som fejler rapporterede.
WhenAssertionFails	Nej	Integer	Definerer, hvad der gøres, når en påstand mislykkes. Dernæst er en liste over mulige værdier: 0 – Ignorér fejlen og fortsæt afviklingen af testen 1 – TearDown-metoden i modulet udføres i den aktuelle testsamlingen, og den næste testsamling startes (standardværdi i fuld tilstand). 2 – Stop med det samme (standardværdi i simpel tilstand)

Liste over metoder i tjenesten 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

Argumenter til AssertX-metoder

Alle påstande (assertions) tester et eller to udtryk, som i resten af denne hjælpeside kaldes A og B. De er altid det første eller de to første argumenter i AssertX-metoden.

Alle AssertX-metoder accepterer et message-argument (besked), som angiver en selvvalgt besked om påstanden, der skal rapporteres i konsollen. Som standard bruges en tom streng. Beskeden er altid argumentet i sidste position af AssertX-metoden.

Nogle AssertX-metoder accepterer også yderligere argumenter, som beskrevet af deres syntakser herunder.

AssertAlmostEqual

Returnerer True når A og B er numeriske værdier og betragtes som tæt på hinanden, ud fra en given relativ tolerance.

Syntaks:

svc.AssertAlmostEqual(a: any, b: any, tolerance: double = 1E-09, message: str = ""): bool

Denne påstand returner True, hvis to betingelser er opfyldt:

A og B kan konverteres til typen Double.
Den absolutte difference mellem A og B divideret med den største absolutte værdi af A eller B er mindre end værdien angivet i tolerance. Dvs. |A-B| / max(|A|,|B|) er indenfor tolerancen.

AssertEqual

Returnerer True når A og B betragtes som lig med hinanden.

Syntaks:

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

Når A og B er enkeltværdier (skalarer), bliver True returneret hvis:

Begge udtryk var samme VarType eller begge er numeriske.
Boolske og numeriske værdier sammenlignes med = operatoren.
Strenge sammenlignes med den indbyggede StrComp-funktion. Sammenlingen skelner mellem store og små bogstaver.
Datoer og tidspunkter sammenlignes op til sekundet.
Null, Empty og Nothing er ikke lig med hinanden, men AssertEqual(Nothing, Nothing) returnerer True.
UNO-objekter bliver sammenlignet med den indbyggede EqualUnoObjects-metode.
Bemærk, at Basic-objekter aldrig er ens.

Når A og B er arrays, returneres True hvis:

Begge arrays har det samme antal dimensioner (op til 2 dimensioner), og deres nedre og øvre grænser er identiske for alle dimensioner.
Alle elementer i begge arrays er parvis lig med hinanden.
To tomme arrays betragtes som lig med hinanden.

AssertFalse

Returnerer True når typen af A er Boolean og værdien er False.

Syntaks:

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

AssertGreater

Returnerer True når A er større end B.

Syntaks:

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

Sammenligningen mellem A og B forudsætter følgende:

De tilladte datatyper er String, Date eller numeriske.
Begge udtryk skal have samme VarType, eller begge skal være numeriske.
Streng-sammenligninger skelner mellem store og små bogstaver.

AssertGreaterEqual

Returnerer True når A er større end eller lig med B.

Syntaks:

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

Sammenligningen mellem A og B forudsætter følgende:

De tilladte datatyper er String, Date eller numeriske.
Begge udtryk skal have samme VarType, eller begge skal være numeriske.
Streng-sammenligninger skelner mellem store og små bogstaver.

AssertIn

Returnerer True når A kan findes i B.

Syntaks:

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

Denne påstand forudsætter følgende:

Udtryk B kan være et 1D-array, et ScriptForge Dictionary-objekt eller en streng.
Når udtryk B er et 1D-array, kan udtryk B være en dato eller en numerisk værdi.
Når udtryk B er et ScriptForge Dictionary-objekt, så søges der efter strenge A blandt nøglerne i B.
Streng-sammenligninger skelner mellem store og små bogstaver.

AssertIsInstance

Returnerer True når A er en instans af en angivet objekttype, specificeret som en streng med typenavnet.

Syntaks:

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

Udtryk A kan være et af følgende:

Et ScriptForge-objekt. I dette tilfælde er argumentet objecttype en streng såsom "DICTIONARY", "calc", "Dialog", osv.
Et UNO-objekt. I dette tilfælde skal argumentet objecttype være en streng, som er identisk med værdien returneret af SF_Session.UnoObjectType()-metoden.
Et Array. I dette tilfælde forventes argumentet objecttype at være "array".
En anden type variabel (hver Object eller Array). I dette tilfælde skal argumentet objecttype matche den streng, som returneres af den indbyggede TypeName-funktion.

AssertIsNothing

Returnerer True, når A er et objekt, som har værdien Nothing.

Syntaks:

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

AssertIsNull

Returnerer True når A har værdien Null.

Syntaks:

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

AssertLess

Returnerer True når A er mindre end B.

Syntaks:

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

Sammenligningen mellem A og B forudsætter følgende:

De tilladte datatyper er String, Date eller numeriske.
Begge udtryk skal have samme VarType, eller begge skal være numeriske.
Streng-sammenligninger skelner mellem store og små bogstaver.

AssertLessEqual

Returnerer True når A er mindre end eller lig med B.

Syntaks:

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

Sammenligningen mellem A og B forudsætter følgende:

De tilladte datatyper er String, Date eller numeriske.
Begge udtryk skal have samme VarType, eller begge skal være numeriske.
Streng-sammenligninger skelner mellem store og små bogstaver.

AssertLike

Returnerer True hvis strengen A matcher et givet mønster med jokertegn.

Syntaks:

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

Følgende jokertegn accepteres:

? – står for et enkelt tegn.
* – står for nul, et eller flere tegn.

AssertNotAlmostEqual

Returnerer True, når A og B er numeriske værdier og ikke betragtes som tæt på hinanden, givet en relativ tolerance.

Syntaks:

svc.AssertNotAlmostEqual(a: any, b: any, tolerance: double = 1E-09, message: str = ""): bool

Denne påstand returnerer True, hvis nedenstående to betingelser er opfyldt:

A og B kan konverteres til typen Double.
Den absolutte difference mellem A og B divideret med den største absolutte værdi af A eller B er større end værdien angivet i tolerance. Dvs. |A-B| / max(|A|,|B|) er ikke indenfor tolerancen.

AssertNotEqual

Returnerer True når A og B ikke betragtes som lig med hinanden.

Syntaks:

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

Denne metode kan bruges på både enkeltværdier (skalarer) og arrays. Læs instruktionen til AssertEqual for mere information om, hvad "lig med" betyder i denne påstand.

AssertNotIn

Returnerer True, når A (en streng) ikke findes i B.

Syntaks:

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

Læs instruktionen til AssertIn for mere information om antagelserne for denne metode.

AssertNotInstance

Returnerer True, når A ikke er en instans af en angivet objekttype.

Syntaks:

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

Læs instruktionerne til AssertIsInstance for mere information of antagelserne for denne metode.

AssertNotLike

Returnerer True, hvis strengen A ikke matcher et givet mønster med jokertegn.

Syntaks:

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

Læs instruktionerne for AssertLike for mere information om antagelserne for denne metode.

AssertNotNothing

Returnerer True, undtagen når A er et objekt som har værdien Nothing.

Syntaks:

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

AssertNotNull

Returnerer True, undtagen når A har værdien Null.

Syntaks:

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

AssertNotRegex

Returnerer True, når A ikke er en streng eller ikke matcher det angivne regulære udtryk.

Syntaks:

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

Sammenligningen skelner mellem store og små bogstaver.

AssertRegex

Returnerer True når strengen A matcher det angivne regulære udtryk.

Syntaks:

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

Sammenligningen skelner mellem store og små bogstaver.

AssertTrue

Returnerer True, når udtrykket A er en Boolean (boolsk udtryk), og udtrykkets værdi er True.

Syntaks:

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

Fail

Tvinger en test til at mislykkes.

Syntaks:

svc.Fail(message: str = "")

Der kan leveres en besked, der skal rapporteres i konsollen.

Log

Skriver den angivne message (besked) i konsollen.

Syntaks:

svc.Log(message: str = "")

Der kan leveres en besked, der skal rapporteres i konsollen.

ReportError

Viser et beskedfelt med en besked og de aktuelle egenskabsværdier for Exception-tjenesten.

Denne metode bruges ofte i undtagelseshåndterings-sektionen af den Sub, som indeholder den testcase der er nået, når en påstand fejler eller når Fail-metoden bliver kaldt.

Syntaks:

svc.ReportError(message: str = "")

Afhængigt af værdien af egenskaben WhenAssertionFails kan testafviklingen fortsætte eller blive afbrudt.

Når du skriver testcases er det anbefalet at inkludre et kald til metoden ReportError i undtagelseshåndterings-sektionen af den tilhørende Sub.

Hvis egenskaben LongMessage er lig med True, så følges den angivne message (besked) af standard-fejlmeldingsbeskrivelsen. Eller vises kun message.

RunTest

Udfører hele testpakken implementeret i det angivne modul. Hver testcase køres uafhængigt af hinanden.

Kørsel af en testsamling består af:

Afvikling af den valgfrie Setup-metode, hvis den findes i modulet.
Afvikling én gang af hver testcase, uden nogen bestemt rækkefølge.
Afvikling af den valgfrie TearDown-metode, hvis den findes i modulet.

Syntaks:

svc.RunTest(testsuite: str, testcasepattern: str = "", message: str = ""): int

Argumentet testcasepattern (testcase_mønster) angiver et mønster med "?" og "*" jokertegn til at udvælge, hvilke testcases der skal udføres. Sammenligningen skelner ikke mellem store og små bogstaver.

Hvis argumentet message (besked) er angivet, skrives det på konsollen når testet starter.

SkipTest

Afbryder den igangværende testsamling uden at kalde TearDown-metoden.

At skippe en test giver normalt mest mening under Setup-metoden, hvis ikke alle betingelser for at køre testen er opfyldt.

Det er op til Setup-metoden at afslutte Sub kort efter kaldet af SkipTest.

Hvis SkipTest bliver inde fra en testcase, så bliver afviklingen af testsamlingen afbrudt, og de tilbageværende testcases bliver ikke kørt. Husk at testcasene i en testsamling udføres i vilkårlig rækkefølge.

Syntaks:

svc.SkipTest(message: str = "")

Hvis argumentet message (besked) er angivet, bliver det skrevet til konsollen.

Tjenesten ScriptForge.Exception (Undtagelse)