Selftest is a great tool for writing automated regression tests. It is rather young (development started June 2002, and it has not been used very much during its first year). Writing automated regression tests is a good thing. The advantages are:
The Selftest tool has a number of nice features that make it suitable for automated regression tests, specially in combination with Opera.
Writing automated regression tests for your code is mandatory. It is part of the process for writing reliable code.
The Selftest engine is implemented in a language called Pike. Normally, you will not notice that more than you need to install Pike. The Selftest engine itself is like a black box that will take care of all the details associated with testcode generation.
Remember when you first learned C, and you saw the first simple application printing the string Hello World. Since then, a lot of languages and toolkits have provided a basic example, demonstrating what you can do, and called it Hello world.
Here we have a Hello world test for Selftest. Create a file called tutorial.ot. Then, add this content:
// tutorial1.ot
group "tutorial 1";
test("Hello world")
{
int i = 1;
int j = 1;
verify(i == j);
}
group is the first keyword in this file. All tests and other
content below the group definition, until next group definition or the end
of the file, will belong to the group. "tutorial_1" is the name
of the group.
The next keyword that we need to know is test. It is used to
define a test.
This test is called "Hello world". The body of the test consists of
regular C++ code, with the addition of a special
command verify.
verify will make sure that the expression given as a
parameter evaluates to true. If it doesn't, the test will
fail. In this case, verify will verify that 1 equals 1, and
the "Hello world" test will pass, unless the compiler is buggy.
Next is a test that will fail.
// tutorial2.ot
group "tutorial 2";
test("Fail Hello world")
{
int i = 1;
int j = 2;
verify(i == j);
}
The test "Fail Hello world" will fail, since 1 is not equal to 2.
Now we have written two tests, but how do we run them?
When we compile Opera, the Selftest engine will search for all *.ot-files in the Opera directory and its subdirectories. Then, the Selftest engine creates a file with C++ code based on all the *.ot-files called optestsuite.cpp. The optestsuite.cpp is compiled normally and linked with the rest of Opera.
The simplest way to run the tests in Opera is to pass -test as a command line parameter to Opera. However, since we are only interested in the tutorial tests, we want to limit the tests running to the ones with a group starting with the string tutorial. Therefore, we will use pass -test=tutorial* on the command line.
To make it easier for you, all of the examples in the tutorial are placed in the directory modules/selftest/documentation/tutorial. All the names ends with ".disabled". To enable "tutorial 1" and "tutorial 2", rename tutorial1.ot.disabled to tutorial1.ot, and rename tutorial2.ot.disabled to tutorial2.ot.
Once you have renamed the files, recompile opera and change the command line argument. You will see something similar to the following:
=========================================================================
Opera Testsuite
=========================================================================
=========================================================================
E:/src/operaclean/opera-windows7/modules/selftest/documentation/tutorial/tutorial1.ot(2): tutorial 1
=========================================================================
Hello world ................................................... Passed
=========================================================================
E:/src/operaclean/opera-windows7/modules/selftest/documentation/tutorial/tutorial2.ot(2): tutorial 2
=========================================================================
Fail Hello world .............................................. FAILED
E:/src/operaclean/opera-windows7/modules/selftest/documentation/tutorial/tutorial2.ot(8): 'i' should be equal to 'j'
=========================================================================
2 tests run, 1 test failed, 0 tests skipped, 1 test OK
Place a breakpoint in testsuite_break_here() to debug the failed test
=========================================================================
As we were expecting, the first test passed, and the second test failed.
In Windows, you can click on the line describing the error, to get to the
line in the *.ot-file that failed. In Emacs on Unix you can use M-x
compile to run the testsuite, the output is compatible with the gcc
error messages, and you can thus use the next-error function.
As you can see in the end description, you are adviced to place a
breakpoint in testsuite_break_here(). When you do that, you
will reach the breakpoint just before the failure message is output.
It is also possible to place breakpoints in the .ot-files most of the time, but sometimes the line-numbers get confused, specifically, you cannot place breakpoints in empty tests.
If you have been able to do all the steps above, got the expected results, and understood approximately what was going on, you are ready to go to the more advanced tutorials. If you did not get here safely, try once again and be more thorough. If you fail once again, ask kilsmo@opera.com or ph@opera.com for help.
html {
//! <title>Example</title>
//! <h1>Example</h1>
//! The content of the current document will be set
//! to this text.
}
This example also introduces
the //! syntax. It is
used to simplify the writing of HTML in the testfiles.