[Libreoffice] howto for getting non-trivial cppunit tests up and running

[Caolán McNamara]

sc/qa/unit had an existing cppunit test to ensure that calc can do
=SUM(A1:A2) correctly but it was currently disabled seeing as it didn't
work, mostly due to miserable bootstrapping problems. I've fixed that
test (I think), so I hope it can now provide a basis for adding more.

It can be a little bit tricky to bootstrap up something as large as
ScDocument standalone outside of a full installation. For simpler tests
a lot of the following isn't necessary, but here are some notes taking
sc/qa/unit/makefile.mk as an example (btw, sfx2/qa/cppunit is another
medium-level example which might also be useful).

a) STAR_RESOURCEPATH can be set to the solver/.../bin dir to find .res
files if they're needed during the test
b) see the -env:FOO lines to set the location of the types.rdb and
udkapi.rdb that describe the LibreOffice UNO types and apis
c) see the services.rdb trickery to register the shared libraries that
we know contain the services we need to run our tests successfully into
a local services.rdb. This bit is unfortunately fragile because you
(currently at least) need to know what services you'll need and where
they live. So that's a "debug and see where it crashes due to a missing
service, and grep for where its implemented, and add it to the
services.rdb line" step :-(
d) see the -env:OOO_BASE_DIR etc settings which are there just to point
the configuration backend at a directory to force it accept that there's
"no config found" and attempt to keep on trucking rather than "invalid
config dir path" and die immediately.
e) There could be some build-dependencies issues where libraries or
resources that are needed for the test aren't currently
build-dependencies of the module. I don't think that's the case for sc
at least, but something to watch out for.
f) see -headless -invisible being passed to the test to suppress any
attempt to launch anything graphical, don't want that to happen in a
built-time unit test.
f) I added some tweaks under the hood here and there to make various
configuration using code take defaults or otherwise not panic if there
is no config data available in order to make writing tests less
miserable. 

HELP NEEDED:

I've only tested this on x86_64 Linux, and I have a vague memory of some
windows build problem the last time I added a cppunit test. So I need
someone under windows to just simply cd sc/qa/unit and run dmake. If it
builds and runs ok on windows change sc_qa_cppunit.u to sc_qa_cppunit in
prj/build.lst and push that.

Obviously seeing as the sc cppunit test (I hope) now works, calc tests
can just be added to that existing example, or extra ones added into
that dir without much effort I hope. So, one suggestion I have it to
look at stripmining testtool and try and start to *move* the calc tests
out of the unreliable and painful testtool and into hopefully reliable
cppunit tests which are run at buildtime

C.