+ + + + SFUnitTests.UnitTest service + /text/sbasic/shared/03/sf_unittest.xhp + + + +

+ + UnitTest service + +

SFUnitTests.UnitTest service

+ The UnitTest service provides a framework for automating unit tests using the Basic language, including the ability to: + + + Aggregate test cases into test suites and unit tests. + + + Share setup and shutdown code among test cases. + + + Report test results using the Console. + + +

+ Both the unit tests and the code to be tested must be written in Basic. The code being tested may call functions written in other languages. + The UnitTest service is not available for Python scripts. + +

Definitions

Test Case

+ A test case is the individual unit of testing. It checks for a specific response to a particular set of inputs. + In the UnitTest service, a test case is represented by a single Basic Sub whose name starts with a common prefix (the default is "Test_"). + The test case fails if one of the AssertX methods returns False. +

Test Suite

+ A test suite is a collection of test cases that should be executed together. + All test cases of a test suite are stored in a single Basic module. + A test suite may implement the SetUp and TearDown methods to prepare for test cases in its module. +

Unit Test

+ A full unit test consists of a set of test suites in the same Basic library. + +

Service invocation

+ Before using the UnitTest service the ScriptForge library needs to be loaded or imported: +

Simple mode

+ Invoke the service in simple mode to call AssertX functions without having to build the full hierarchy of test suites and test cases. + In simple mode, the service is invoked inside the test case, as shown in the example below: + + Sub SimpleTest + On Local Error GoTo CatchError + Dim myTest As Variant + myTest = CreateScriptService("UnitTest") + ' A few dummy tests + myTest.AssertEqual(1 + 1, 2) + myTest.AssertEqual(1 - 1, 0) + MsgBox("All tests passed") + Exit Sub + CatchError: + myTest.ReportError("A test failed") + End Sub + + In this example, if any of the AssertEqual calls fail, the interpreter will go to the CatchError label and report the error by calling the ReportError method. +

Full mode

+ When invoked in full mode, the service creation is external to the test code and all tests are organized into test cases and test suites inside a single library. + The following example creates a UnitTest instance whose tests are located inside the current document (ThisComponent) in the "Tests" library. + + GlobalScope.BasicLibraries.loadLibrary("ScriptForge") + Dim myUnitTest As Variant + myUnitTest = CreateScriptService("UnitTest", ThisComponent, "Tests") + +

A minimalist example in full mode

+ Consider that a ODS file has a module named "MathUtils" in its "Standard" library with the following code: + + ' Code in 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 + + To create a full test suite, consider that a new library named "Tests" is created in the file with a single module "AllTests" containing the code below: + + ' Code in 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) + ' Preparation code ran prior to the first test case + Dim exc As Variant + exc = CreateScriptService("Exception") + exc.Console(Modal := False) + End Sub + + Sub TearDown(test) + ' Optional cleanup code called after the last test case + 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 + + The test suite above consists of two test cases Test_Sum and Test_Multiply. To run all tests simply run the Main method from the "AllTests" module. + The Console from the Exception service is used as the default output to print test results. After running the example above, the following output will be displayed in the 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) + + If any of the AssertEqual methods fails during these tests, an error message is added to the console. + + + Region service;LongMessage + Region service;ReturnCode + Region service;Verbose + Region service;WhenAssertionFails + + +

Properties

+ + + + Name + + + Readonly + + + Type + + + Description + + + + + LongMessage + + + No + + + Boolean + + + When set to True (default) the console shows the standard message appended to the message provided by the tester. When False, only the message defined by the tester is used. + + + + + ReturnCode + + + Yes + + + Integer + + + Value returned by RunTest after the unit test is finished. Next is a list of possible values: + 0 - Test finished without errors or test not started
+ 1 - An assertion within a test case returned False
+ 2 - A SkipTest was issued by the Setup method or by one of the test cases.
+ 3 - Abnormal end of test + + + + + Verbose + + + No + + + Boolean + + + When set to True, all assertions are reported in the console (failing or not). When False (default), only failing assertions are reported. + + + + + WhenAssertionFails + + + No + + + Integer + + + Defines what is done when an assertion fails. Next is a list of possible values: + 0 - Ignore the failure and continue running the test
+ 1 - The TearDown method in the module is executed in the current test suite and the next suite is started (default in full mode).
+ 2 - Stop immediately (default in simple mode) + + +

+ + + + List of Methods in the UnitTest Service + + + + + 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 of the AssertX methods

+ All assertions test one or two expressions, referred in the remainder of this help page as A and B. They are always the first one or two arguments in the AssertX method. + All AssertX methods accept a message argument specifying a custom message to be reported in the console regarding the assertion. By default an empty string is used. This argument is always in the last position of the assertion. + Some AssertX methods also accept additional arguments, as described by their syntaxes below. + +

+ AssertAlmostEqual -------------------------------------------------------------------------------------- + + UnitTest service;AssertAlmostEqual + +

AssertAlmostEqual

+ Returns True when A and B are numerical values and are considered to be close to each other, given a relative tolerance. +

+ + svc.AssertAlmostEqual(a: any, b: any, tolerance: double = 1E-09, message: str = ""): bool + + This assertion returns True if the two conditions below are met: + + + A and B can be converted to the Double type. + + + The absolute difference between A and B divided by the largest absolute value of A or B is lower than the value specified in tolerance. + + +

+ +

+ AssertEqual -------------------------------------------------------------------------------------------- + + UnitTest service;AssertEqual + +

AssertEqual

+ Returns True when A and B are considered to be equal. +

+ + svc.AssertEqual(a: any, b: any, message: str = ""): bool + + When A and B are scalars, True is returned if: + + + Both expressions have the same VarType or are both numeric. + + + Booleans and numeric values are compared with the = operator. + + + Strings are compared with the builtin StrComp function. The comparison is case-sensitive. + + + Dates and times are compared up to the second. + + + Null, Empty and Nothing are not equal, but AssertEqual(Nothing, Nothing) returns True. + + + UNO objects are compared with the builtin EqualUnoObjects method. + + + Note that Basic objects are never equal. + + + When A and B are arrays, True is returned if: + + + Both arrays have the same number of dimensions (up to 2 dimensions) and their lower and upper bounds are identical for all dimensions. + + + All items in both arrays are equal, one by one. + + + Two empty arrays are considered to be equal. + + +

+ +

+ AssertFalse -------------------------------------------------------------------------------------------- + + UnitTest service;AssertFalse + +

AssertFalse

+ Returns True when the type of A is Boolean and its value is False. +

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

+ +

+ AssertGreater ------------------------------------------------------------------------------------------ + + UnitTest service;AssertGreater + +

AssertGreater

+ Returns True when A is greater than B. +

+ + svc.AssertGreater(a: any, b: any, message: str = ""): bool + + The comparison between A and B assumes the following: + + + Eligible data types are String, Date or numeric. + + + Both expressions must have the same VarType or both must be numeric. + + + String comparisons are case-sensitive. + + +

+ +

+ AssertGreaterEqual ------------------------------------------------------------------------------------- + + UnitTest service;AssertGreaterEqual + +

AssertGreaterEqual

+ Returns True when A is greater than or equal to B. +

+ + svc.AssertGreaterEqual(a: any, b: any, message: str = ""): bool + + The comparison between A and B assumes the following: + + + Eligible data types are String, Date or numeric. + + + Both expressions must have the same VarType or both must be numeric. + + + String comparisons are case-sensitive. + + +

+ +

+ AssertIn ----------------------------------------------------------------------------------------------- + + UnitTest service;AssertIn + +

AssertIn

+ Returns True when A is found in B. +

+ + svc.AssertIn(a: any, b: any, message: str = ""): bool + + This assertion assumes the following: + + + Expression B may be a 1D array, a ScriptForge Dictionary object or a string. + + + When expression B is a 1D array, expression A may be a date or a numeric value. + + + When expression B is a ScriptForge Dictionary object, then string A is searched for among the keys in B. + + + String comparisons are case-sensitive. + + +

+ +

+ AssertIsInstance --------------------------------------------------------------------------------------- + + UnitTest service;AssertIsInstance + +

AssertIsInstance

+ Returns True when A is an instance of a specified object type, specified as a string containing the type name. +

+ + svc.AssertIsInstance(a: any, objecttype: str, message: str = ""): bool + + Expression A may be one of the following: + + + A ScriptForge object. In this case, the objecttype argument is a string such as "DICTIONARY", "calc", "Dialog", etc. + + + A UNO object. In this case, the objecttype argument must be a string identical to the value returned by the SF_Session.UnoObjectType() method. + + + An Array. In this case, the objecttype argument is expected to be "array". + + + Any other variable (neither an Object nor an Array). In this case, objecttype is a string matching the value returned by the builtin TypeName function. + + +

+ +

+ AssertIsNothing ---------------------------------------------------------------------------------------- + + UnitTest service;AssertIsNothing + +

AssertIsNothing

+ Returns True when A is an object that has the Nothing value. +

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

+ +

+ AssertIsNull ------------------------------------------------------------------------------------------- + + UnitTest service;AssertIsNull + +

AssertIsNull

+ Returns True when A has the Null value. +

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

+ +

+ AssertLess --------------------------------------------------------------------------------------------- + + UnitTest service;AssertLess + +

AssertLess

+ Returns True when A is less than B. +

+ + svc.AssertLess(a: any, b: any, message: str = ""): bool + + The comparison between A and B assumes the following: + + + Eligible data types are String, Date or numeric. + + + Both expressions must have the same VarType or both must be numeric. + + + String comparisons are case-sensitive. + + +

+ +

+ AssertLessEqual ---------------------------------------------------------------------------------------- + + UnitTest service;AssertLessEqual + +

AssertLessEqual

+ Returns True when A is less than or equal to B. +

+ + svc.AssertLessEqual(a: any, b: any, message: str = ""): bool + + The comparison between A and B assumes the following: + + + Eligible data types are String, Date or numeric. + + + Both expressions must have the same VarType or both must be numeric. + + + String comparisons are case-sensitive. + + +

+ +

+ AssertLike --------------------------------------------------------------------------------------------- + + UnitTest service;AssertLike + +

AssertLike

+ Returns True if string A matches a given pattern containing wildcards. +

+ + svc.AssertLike(a: any, pattern: str = "", message: str = ""): bool + + The following wildcards are accepted: + + + ? - Represents any single character. + + + * - Represents zero, one, or multiple characters. + + +

+ +

+ AssertNotAlmostEqual ----------------------------------------------------------------------------------- + + UnitTest service;AssertNotAlmostEqual + +

AssertNotAlmostEqual

+ Returns True when A and B are numerical values and are not considered to be close to each other, given a relative tolerance. +

+ + svc.AssertNotAlmostEqual(a: any, b: any, tolerance: double = 1E-09, message: str = ""): bool + + This assertion returns True if the two conditions below are met: + + + A and B can be converted to the Double type. + + + The absolute difference between A and B divided by the largest absolute value of A or B is greater than the value specified in tolerance. + + +

+ +

+ AssertNotEqual ----------------------------------------------------------------------------------------- + + UnitTest service;AssertNotEqual + +

AssertNotEqual

+ Returns True when A and B are not considered to be equal. +

+ + svc.AssertNotEqual(a: any, b: any, message: str = ""): bool + + This method works both for scalars and arrays. Read the instructions in AssertEqual for more information on what equality means in this assertion. +

+ +

+ AssertNotIn -------------------------------------------------------------------------------------------- + + UnitTest service;AssertNotIn + +

AssertNotIn

+ Returns True when A (a string) is not found in B. +

+ + svc.AssertNotIn(a: any, b: any, message: str = ""): bool + + Read the instructions in AssertIn for more information on the assumptions of this method. +

+ +

+ AssertNotInstance -------------------------------------------------------------------------------------- + + UnitTest service;AssertNotInstance + +

AssertNotInstance

+ Returns True when A is not an instance of a specified object type. +

+ + svc.AssertNotInstance(a: any, objecttype: str, message: str = ""): bool + + Read the instructions in AssertIsInstance for more information on the assumptions of this method. +

+ +

+ AssertNotLike ------------------------------------------------------------------------------------------ + + UnitTest service;AssertNotLike + +

AssertNotLike

+ Returns True if string A does not match a given pattern containing wildcards. +

+ + svc.AssertNotLike(a: any, pattern: str = "", message: str = ""): bool + + Read the instructions in AssertLike for more information on the assumptions of this method. +

+ +

+ AssertNotNothing --------------------------------------------------------------------------------------- + + UnitTest service;AssertNotNothing + +

AssertNotNothing

+ Returns True except when A is an object that has the Nothing value. +

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

+ +

+ AssertNotNull ------------------------------------------------------------------------------------------ + + UnitTest service;AssertNotNull + +

AssertNotNull

+ Returns True except when A has the Null value. +

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

+ +

+ AssertNotRegex ----------------------------------------------------------------------------------------- + + UnitTest service;AssertNotRegex + +

AssertNotRegex

+ Returns True when A is not a string or does not match the given regular expression. +

+ + svc.AssertNotRegex(a: any, regex: str = "", message: str = ""): bool + + The comparison is case-sensitive. +

+ +

+ AssertRegex -------------------------------------------------------------------------------------------- + + UnitTest service;AssertRegex + +

AssertRegex

+ Returns True when string A matches the given regular expression. +

+ + svc.AssertRegex(a: any, regex: str = "", message: str = ""): bool + + The comparison is case-sensitive. +

+ +

+ AssertTrue --------------------------------------------------------------------------------------------- + + UnitTest service;AssertTrue + +

AssertTrue

+ Returns True when expression A is a Boolean and its value is True. +

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

+ +

+ Fail --------------------------------------------------------------------------------------------------- + + UnitTest service;Fail + +

Fail

+ Forces a test case to fail. +

+ + svc.Fail(message: str = "") + + A message can be provided to be reported in the console. +

+ +

+ Log ---------------------------------------------------------------------------------------------------- + + UnitTest service;Log + +

Log

+ Writes the specified message in the console. +

+ + svc.Log(message: str = "") + + A message can be provided to be reported in the console. +

+ +

+ ReportError -------------------------------------------------------------------------------------------- + + UnitTest service;ReportError + +

ReportError

+ Displays a message box with a message and the current property values of the Exception service. + This method is commonly used in the exception handling section of the Sub containing the test case, which is reached when an assertion fails or when the Fail method is called. +

+ + svc.ReportError(message: str = "") + + Depending on the value of the property WhenAssertionFails, the test execution may continue or be interrupted. + When writing test cases it is recommended to include a call to the ReportError method in the exception handling section of the Sub. + If the property LongMessage is equal to True, the specified message is followed by the standard error message description. Otherwise only the message is displayed. +

+ +

+ RunTest ------------------------------------------------------------------------------------------------ + + UnitTest service;RunTest + +

RunTest

+ Executes the complete test suite implemented in the specified module. Each test case is run independently from each other. + Running a test suite consists of: + + + Executing the optional Setup method present in the module. + + + Executing once each test case, in no specific order. + + + Executing the optional TearDown method present in the module. + + +

+ + svc.RunTest(testsuite: str, testcasepattern: str = "", message: str = ""): int + + The argument testcasepattern specifies a pattern composed of "?" and "*" wildcards to select which test cases will be run. The comparison is not case-sensitive. + If a message is provided, it is written to the console when the test starts. +

+ +

+ SkipTest ----------------------------------------------------------------------------------------------- + + UnitTest service;SkipTest + +

SkipTest

+ Interrupts the running test suite without calling the TearDown method. + Skipping a test is usually meaningful during the Setup method when not all conditions to run the test are met. + It is up to the Setup method to exit the Sub shortly after the SkipTest call. + If SkipTest is called from within a test case, the execution of the test suite is interrupted and the remaining test cases are not run. Keep in mind that the order in which test cases are run is arbitrary within a test suite. +

+ + svc.SkipTest(message: str = "") + + If a message is provided, it is written to the console. +

+ +