[interfacekit] Re: BClipboard: Any progress?

> I have been kind of busy with other stuff, but I have recently been 
> making 
> progress.  I was actually planning on sending out a note this week 
> about it, 
> but you beat me to it.  I have quite a bit of the BClipboard 
> implemented.  
> There are still some things I need to do, but I don't foresee any 
> problems.  
> With any luck, I expect to have the implementation done by this 
> weekend.

That sounds good. :-)

>  I 
> still need to figure out how the testing system works, so if you 
> would care to 
> explain it, that would be helpful. 

Tyler wrote a newsletter about it, which should be very helpful.

As a very quick introduction: We're using cppunit for our test system. 
The UnitTester application (tests/UnitTester) dynamically loads add-ons 
containing the actual tests, and can run all of them, only single 
tests, suites,... (--help for options). A test add-on contains a test 
suite. E.g. libapptest.so contains the suite `App' for the App Kit 
tests which consists of subsuites for the App Kit classes usually 
containing subsuites for blocks of functionality (e.g. one per method 
or related methods) comprising the actual single test functions. For 
each test two versions are compiled, one reference version linked 
against the R5 libbe.so and one version linked against our 
implementation.

If that sounds complicated, go have a look at the implemented tests. 
`src/tests/kits/app' contains the tests for the App Kit test suite. It 
features a subdirectory per class. The subsuite for your class needs to 
be included in `AppKitTestAddon.cpp', the source files must be listed 
in the Jamfile.

To get started create a subdirectory (`bclipboard'), copy a e.g. 
`bmessagerunner/MessageRunnerTest.{cpp,h}' to `ClipboardTest.{cpp,h}' 
and edit the contents. It includes the subsuites that contain the 
actual tests. For a template for such a subsuite you may copy e.g. 
`BMessageRunnerTester.{h,cpp}' to `BClipboardTester.{cpp,h}'. In the 
header file you see what methods are needed. One static method 
`Suite()' returning the test suite and one method per actual test. 
Remove all but one test method, remove the unneeded stuff from the 
source file, rename everything appropriately. Empty the body of your 
single left test method and make sure that only this method is included 
in Suite().

Make sure that your subsuite is included in `ClipboardTest.cpp'. Add 
your class' test suite to `AppKitTestAddon.cpp' and add the directory 
and the two source files to the Jamfile.

You may preferrably run `jam tests' before these changes. This builds 
the cppunit library, the unit tester and all the tests (this takes 
ages!). Thereafter you may want to run only `jam libapptest.so' or `jam 
libapptest_r5.so' to build the App Kit test add-on for the OBOS or the 
R5 implementation respectively (should be a bit faster).

When your new test builds, run `tests/UnitTester BClipboard' to execute 
it. Fill the body of your test method with life, add other test 
methods, and for other sets of functionality add new source files. To 
keep track of the tests you implemented -- or rather the other way 
around, to design the tests you want to implement -- you can add a text 
file with a complete list.

Finally, how should a test methods look like. Well, you're free to do 
it as you like. The only requirement is, that you check conditions that 
shall hold with the CPPUNIT_ASSERT() macro (or, for lazy writers, 
CHK()). It throws an exception when the condition is false and thus 
terminates the test method. The unit tester then continues with the 
next test method.

Your tester class can implement two special methods, setUp() and 
tearDown(). These are called before respectively after each test method 
and can be used to allocate/free resources needed in the tests. E.g. 
all tests that create files should delete them in tearDown(). This 
guarantees that they are always deleted, even if an exception is thrown 
in the test method.

Another thing you might find helpful are the TEST_R5 and TEST_OBOS 
macros. Depending on whether the test is compiled for the R5 or the 
OBOS implementation the respective macro is defined. This allows for 
instance to `#ifndef TEST_R5' a block of code that crashes with the 
libbe implementation (often seen when checking how well methods deal 
with NULL arguments), but nevertheless allows to execute it with our 
implementation.

> Do you want me to take a crack at the ClipboardHandler, or do you 
> want me to 
> just document the protocol and let you guys take care of it? 

As you like. I guess, it would be more convenient to implement both 
ends of the communication line, especially for testing and debugging. 
But no problem, I can write the registrar side code, if you preferred 
that. I'll be on vacation for two weeks and a half with the end of the 
next week and I won't have too much time till then (this weekend is 
BeGeistert :-). Though I suspect, Tyler could easily deal with that as 
well. ;-)

> Also, feel free at any point to nag me about my work, sometimes I 
> tend to get 
> caught up in other things and forget.

Er, well, I can do that, though Erik is the chief nagger here. ;-)

CU, Ingo

Other related posts: