Gambas Documentation
Application Repository
Code Snippets
Compilation & Installation
Controls pictures
Deprecated components
Developer Documentation
Development Environment Documentation
About The Best Formula In The World
Architecture details
By Reference Argument Passing
Compatibility between versions
Creating And Using Libraries
Database Datatype Mapping
Database Request Quoting
Date & time management
Dates and calendars
DBus and Gambas
Differences Between Shell And Exec
Differences From Visual Basic
Distributions & Operating Systems
Drag & Drop
DrawingArea Internal Behaviour
External functions datatype mapping
Frequently Asked Questions
Gambas Farm Server Protocol
Gambas Mailing List Netiquette
Gambas Markdown Syntax
Gambas Naming Conventions
Gambas Object Model
Gambas Scripting
Gambas Server Pages
Gambas Unit Testing
Gambas Wiki Markup Syntax
Getting Started With Gambas
Hall Of Fame
Image Management In Gambas
Including Help Comments in Source Code
Interpreter limits
Just In Time Compiler
Just In Time Compiler (old version)
Localisation and Internationalization
Mailing Lists & Forums
Naming Conventions
Network Programming
ODBC Component Documentation
PCRE Pattern Syntax
Porting from Gambas 2 to Gambas 3
Previous News
Project Directory Structure
Release Notes
Reporting a problem, a bug or a crash
Rich Text Syntax
Text highlighting definition file syntax
The Program has stopped unexpectedly by raising signal #11
Variable Naming Convention
WebPage Syntax
Web site home page
What Is Gambas?
Window & Form Management
Window Activation & Deactivation
Window Life Cycle
Error Messages
Gambas Playground
How To's
Language Index
Language Overviews
Last Changes
Search the wiki
To Do
Wiki License
Wiki Manual

Gambas Unit Testing

gb.test is a Gambas component for unittesting and test-driven-development (TDD). With this component you can create tests for your Gambas program, you can develop software in a test-driven matter (write test first, program functionality afterwards) and you are able to ensure that on refactoring or when you enhance your software the desired results of your code stays the same. Therefore gb.test is helpful to ensure better stability and higher reliability of Gambas programs.

You can write the tests in special test classes (class files with the ending '.test').

gb.test runs the tests and the results are output as a TAP string together with a summary. You can start the testing inside the Gambas IDE and watch the progress of the testing as well as the result in the Unit Tests tab. The summary at the end shows "PASSED" or "FAILED" so you can easily see if your tests have been successful or not. But they also can be displayed, analyzed or viewed with any Tap consumer.

You can also run the tests of your project on the command line and so gb.test provides the tools to run tests automatically.

How gb.test works

gb.test is there to test a project from the inside. It can access all procedures and variables that are public within a project.

By default, gb.test executes all tests that exist in a project. The tests are grouped into test modules. test modules are classes with the extension '.test'. They contain public methods (we call them 'test methods'). The names of the test methods must not begin with '_'.

gb.test organizes the order in which the test methods are called in test modules in alphabetical order. This results in this sequence of execution:


The test methods themselves contain the actual tests, which are performed with methods of the class 'Assert'. The class 'Assert' provides various assertions, which are checked in the gb.test process.

For example, the assertion 'Assert.Equals(Got as String, Expected as String)' can be used to test whether the content of the variable 'Got' is identical to the content of the variable 'Expected'.

If yes, gb.test outputs 'ok', if no, gb.test outputs 'not ok' to Stdout.

So basically gb.test works through all assertions, in all test methods in all test modules of a project, checks the assertions and outputs the result to stdout. In addition, gb.test also runs a statistic and at the end it outputs a summary that shows if and which errors were found.

If you don't want gb.test to perform all tests it finds in a project, you can limit its work with so-called test suites to single or groups of tests. A test-suite is basically nothing more than a string containing the names of the desired tests that gb.test should execute.


There is an example in this simple Gambas project.

Test module

In test driven development it is common practice to first write the test that the future program will later fulfill. Therefore we start by creating a test module.

This is a class, named like any other Gambas class with the ending ".test", for example "THelloWorld.test". This class contains one or more tests, these are public subs whose name must not contain an underscore:

' Gambas test module file
''' Test module THelloWorld

Public Sub AHelloWorld()

  Test.Note("I am the first test, because my name starts with A.")
  Assert.Equals(Hello.World(), "Hello World", "HW strings should be equal")


With the methods provided by the Assert class you are able to test the output of any public state (variable, constant or function) in your project.

Module (Function) to test:

Now that we have written the test, it is time to develop the program that will fulfill the test. So we create a function "World" in a module "Hello" in our project:

' Gambas module file

''' Module is named "Hello"

'' Returns "World"
Public Function World() As String
  Return "Hello World"

Running the test

If you are working with the Gambas IDE you can hit F4 to let your tests run. The IDE will show you the "Unit tests" tab with this content:


Test THello:AHelloWorld
  # I am the first test, because my name starts with A.
  ok 1 - HW strings should be equal
ok 1 - THello:AHelloWorld

# Ran: 'THello.AHelloWorld'

If a failure occurs it will report FAILED instead of PASSED and will show you the place of the failure. If you want to debug the code you can set a breakpoint anywhere in your test or production code, hit <F4> again and start debugging.

Test modules and test methods can be named the same way as any Gambas module or method except that a test method may not be named _Setup(), _Teardown(), _SetupEach() or _TeardownEach() and it's name must not contain an underscore.


If you hit Shift-F4 the Gambas IDE lets you create so called "test suites". This is convenient if you have a lot of tests but need to run just one or a couple of them by chance. You can create a lot of test suites and use them to test different aspects of your project separately.

Testsuites are stored in the file .test in the project's path.

Test your project on the console

You also can test your project on the console. It has to be compiled first. The command gbx3 -T "*" /path/to/my/project executes the unittests and prints the result to standard output. You can call single tests or an arrangement of tests in the same way, as these are stored in the file .test after you created a test suite.

You can even let run a testsuite by name by adding a preceeding "@" to it's name if you let it run with gbx3:

gbx3 -T "@my first testsuite" /path/to/my/project

If your project relies on the existence of environment variables you can define these on the command line:

MyEnvVar=1 gbx3 -T "@my first testsuite" /path/to/my/project

Environment variables defined inside the Project properties dialog of the Gambas IDE are not taken into account.

Test fixture

Sometimes it is neccessary to create a "fixture", a special environment for a test or a couple of tests, and to destroy this environment after the test is done. For example a database connection should be established at the beginning of all tests, some tables for testing should be created and deleted for every single test method and the database connection should be closed at the end. This can be done with _Setup... and _Teardown... functions inside the test module.

Sub _Setup() and Sub _Teardown()

You can create methods with these names to create an environment for all test methods inside a test module, in the beginning _Setup() is invoked and after all test methods inside the test module are done you can destroy the environment with _Teardown().

Sub _SetupEach() and Sub _TeardownEach()

You can create methods with these names to create an environment for each test method before it is invoked and to destroy it afterwards. If you have five test methods inside your test module these functions will be invoked five times, _SetupEach() before each test method, _TeardownEach() after each test method. Got it?

Plan tests

It would be pretty stupid if your test system, for unknown reasons, swallowed single tests and never showed you that they did not run. To protect yourself from this, there is a way to specify a plan that defines the number of assertions that must run inside a testmethod. And it goes like this:

' Gambas test file
''' Test module THelloWorld

Public Sub AHelloWorld()

  '' Defines the count of assertions in this test method

  Assert.Equals(Hello.World(), "Hello World", "HW strings should be equal")


If the tests have not fulfilled the plan, the system will display "FAILED" and tell you the reason.