[ Impressum ]

LiveCode TestLib

www.Rozek.de > LiveCode > TestLib
The "TestLib" is a small LiveCode [1] "library stack" with a series of commands to simplify automated (unit) tests in LiveCode scripts.

The basic idea behind the commands presented here is that the formulated conditions should usually be met: if a test fails, the tested program is considered faulty and either the test needs to be adjusted or the program itself to be corrected.

Applications of the "TestLib" usually look something like this:

assert_empty the result
assert_beginsWith "InvalidArgument", Signal
assert_Integer NumberOfCustomers

If any of the tests fail, an "AssertionFailure" is thrown and the call chain for the test is shown in the LiveCode "Message Box" - in this way the error can be located quickly.

Download and Installation

The "TestLib" is available as an unencrypted LiveCode stack and can be downloaded from here:
After downloading, just place the "TestLib" in a directory of your choice - an explicit installation is not required.

Usage Instructions

The "TestLib" has been implemented as a LiveCode "library stack" and must therefore be attached to a "MainStack" prior to its use using

start using stack "TestLib"

Appropriately, this statement is executed in the context of a preOpenStack procedure of a MainStack.

Should the MainStack later be converted into a standalone application, the "TestLib" must also become part of the list of "Stack Files" in this MainStack (this is easiest done by using the "Standalone Application Settings" from the LiveCode development environment).

Usage Instructions for mobile Applications

The "TestLib" can also be used in mobile applications. However - and unlike for standalone desktop applications - it must then be included in the list of "non-stack files" and attached to the MainStack using

start using stack (specialFolderPath("engine") & "/TestLib.livecode")

The list of "non-stack files" can likewise be found on the "Copy Files" page in the "Standalone Application Settings" of the LiveCode development environment.

Command Overview

The "TestLib" contains only commands, no functions.

Datatype Assertions

Some of the tests check if a given argument is of an appropriate data type. These are (in alphabetical order):

assert_Array <Candidate>


assert_Array requires that the given argument Candidate contains a non-empty LiveCode array. The command will proceed silently, if this condition is met - but if not, an "AssertionFailure" exception will be thrown that points you to this test..

assert_Boolean <Candidate>


assert_Boolean requires that the given argument Candidate contains a valid boolean value (i.e., either true or false). The command will proceed silently, if this condition is met - but if not, an "AssertionFailure" exception will be thrown that points you to this test.

assert_Color <Candidate>


assert_Color requires that the given argument Candidate contains a valid color value. This can be a color name ("green"), a specification in HTML format ("#2255ab") or a list of RGB values (255,255,255). The command will proceed silently, if this condition is met - but if not, an "AssertionFailure" exception will be thrown that points you to this test.

assert_Date <Candidate>


assert_Date requires that the given argument Candidate contains a valid date value. The command will proceed silently, if this condition is met - but if not, an "AssertionFailure" exception will be thrown that points you to this test.

assert_Integer <Candidate>


assert_Integer requires that the given argument Candidate contains a valid integer. The command will proceed silently, if this condition is met - but if not, an "AssertionFailure" exception will be thrown that points you to this test.

assert_Number <Candidate>


assert_Number requires that the given argument Candidate contains a numeric value. The command will proceed silently, if this condition is met - but if not, an "AssertionFailure" exception will be thrown that points you to this test.

assert_Point <Candidate>


assert_Point requires that the given argument Candidate contains a valid point specification (i.e., a list consisting of two numbers). The command will proceed silently, if this condition is met - but if not, an "AssertionFailure" exception will be thrown that points you to this test.

assert_Rect <Candidate>


assert_Rect requires that the given argument Candidate contains a valid rectangle specification (i.e., a list consisting of four numbers). The command will proceed silently, if this condition is met - but if not, an "AssertionFailure" exception will be thrown that points you to this test.

Comparative Assertions

Other tests compare a given argument with predetermined content. These are (in alphabetical order):

assert_empty <Candidate>


assert_empty requires that the given argument Candidate is empty. The command will proceed silently, if this condition is met - but if not, an "AssertionFailure" exception will be thrown that points you to this test.

assert_nonempty <Candidate>


assert_nonempty requires that the given argument Candidate is not empty. The command will proceed silently, if this condition is met - but if not, an "AssertionFailure" exception will be thrown that points you to this test.

assert_equals <expectedValue>, <actualValue>


assert_equals requires that the given actualValue has the same content as the given expectedValue (regardless of its data type). If both arguments are strings, the current "CaseSensitive" setting is taken into account during comparison. The command will proceed silently, if this condition is met - but if not, an "AssertionFailure" exception will be thrown that points you to this test.

assert_differs <forbiddenValue>, <actualValue>


assert_differs requires that the given actualValue has a different content than the given forbiddenValue (regardless of its data type). If both arguments are strings, the current "CaseSensitive" setting is taken into account during comparison. The command will proceed silently, if this condition is met - but if not, an "AssertionFailure" exception will be thrown that points you to this test.

assert_beginsWith <Prefix>, <actualValue>


assert_beginsWith requires that the given actualValue begins with the given Prefix - taking into account the current "CaseSensitive" setting. The command will proceed silently, if this condition is met - but if not, an "AssertionFailure" exception will be thrown that points you to this test.

assert_endsWith <Suffix>, <actualValue>


assert_endsWith requires that the given actualValue ends with the given Suffix - taking into account the current "CaseSensitive" setting. The command will proceed silently, if this condition is met - but if not, an "AssertionFailure" exception will be thrown that points you to this test.

Statement Assertions

Another collection of tests handles the success or failure of instructions. These are (in alphabetical order):

assert_Success <Statement>


assert_Success requires that the given Statement (represented by a string) is executed without throwing an exception. The command will proceed silently, if this condition is met - but if not, an "AssertionFailure" exception will be thrown that points you to this test.

assert_Failure <SignalPrefix>, <Statement>


assert_Failure requires that the execution of the given Statement (represented by a string) throws an exception whose message starts with the given SignalPrefix (the comparison is carried out taking into account the current "CaseSensitive" setting). If SignalPrefix is empty, every thrown exception will satisfy this condition. The command will proceed silently, if this condition is met - but if not, an "AssertionFailure" exception will be thrown that points you to this test.

assert_DispatchSuccess <HandlerName> [, <TargetRef> [, <Argument> [, ...]]]


assert_DispatchSuccess requires that dispatching the given "HandlerName" with the given arguments ("Argument" and others) to the given "TargetRef" object runs without throwing an exception. The command will proceed silently, if this condition is met - but if not, an "AssertionFailure" exception will be thrown that points you to this test.

If the specification of TargetRef is missing, the call is sent to the object containing the current (test) script.

Currently, up to 16 arguments are supported.

assert_DispatchFailure <SignalPrefix>, <HandlerName> [, <TargetRef> [, <Argument> [, ...]]]


assert_DispatchFailure requires that dispatching the given "HandlerName" with the given arguments ("Argument" and others) to the given "TargetRef" object throws an exception whose message starts with the given SignalPrefix (the comparison is carried out taking into account the current "CaseSensitive" setting). If SignalPrefix is empty, every thrown exception will satisfy this condition. The command will proceed silently, if this condition is met - but if not, an "AssertionFailure" exception will be thrown that points you to this test.

If the specification of TargetRef is missing, the call is sent to the object containing the current (test) script.

Currently, up to 16 arguments are supported.

System Requirements

The "TestLib" requires LiveCode 6.x or later, and works regardless of the operating system on both stationary and mobile platforms.

Dependencies

Internally, the "TestLib" uses my "BasicLib" - when using the "TestLib" it must therefore also be present.

Automated Tests

There is also a separate stack with automated tests of the "TestLib":
When this stack is opened, the command performTests is executed, which is responsible for running the actual tests. In the end, the "Message Box" of the LiveCode development environment should appear and display the message

all tests passed

Otherwise, an error message with information about the failed test should be shown instead.

Known Bugs

There are currently no known bugs in the "TestLib".

License Information

The "TestLib" and its tests are licensed under a "Creative Commons Attribution 4.0 Unported license", which essentially means that you may both use and modify them (even in a commercial context) - provided that your changes have been marked as such and there is a reference to me as the original author at an appropriate place.

                       
Have fun with LiveCode and my libraries! Creative Commons License

Bibliography

[1]
(RunRev Ltd.)
LiveCode | Create apps for multiple platforms. Quickly. Easily. Free
LiveCode is a development environment for both stationary (Windows, Linux, MacOS X) and mobile (iOS, Android) applications modeled after the legendary Apple HyperCard. A visual editor allows fast design of user interfaces, a programming language inspired by the english language allows even non-professional programmers to develop professional applications and the concept of "modifying a running program" simplifies testing and troubleshooting.