Mar 28 2006
Ewl Test app
Another chunk of info sent to the e mailing list that I'm copying here. If you're on the ml you can probably skip this.
I just wanted to give a quick update, and solicitation for help, on the EWL test application. We have just finished re-writing and porting the old tests over to the new framework. Hopefully this will make adding tests a lot easier.
Along with UI tests it is also possible to add unit tests and execute them through the UI. This should allow us to test a lot more of the code base without having to have complicated graphical tests.
The new framework also gives the benefit that if you have a widget that is outside the EWL tree (epdf for example) you can write tests and have them integrate into the ewl_test application. (All of the tests are dynamically loaded, you just have to implement one specific function.)
Each test can also have a tutorial attached to it. These tutorials will be displayed under the 'Tutorial' tab of the test app and will also be pulled into the generated doxygen documentation. It uses a limited subset of doxygen for rendering. (More doxy can be supported we just haven't needed it yet. There are a couple of tutorials in the test directory, if you feel like adding more please help out.
Ok, so you want to help, we need unit tests and tutorials. We have a few, and you can look at tests/ewl_text.c, tests/ewl_image.c or tests/ewl_widget.c to see how unit tests and tutorials are integrated into the files. (Or read below as I'll explain it.) We really need tests to cover all of the get/set methods and anything else that can be tested without a display. (Things like setting RGB and getting HSV back from the colour spectrum for example.) Corner cases, etc.
If you've got a widget you have out of the EWL tree and you want to write tests for it, here's the basic idea.
You'll need to include Ewl_Test.h which should be installed with your EWL headers.
You will need to implement the test_info function which takes an Ewl_Test struct. You then just fill in that struct with your module information. For example, from the Text test:
void test_info(Ewl_Test *test)
{
test->name = "Text";
test->tip = "Defines a class for multi-line text layout\n"
"and formatting.";
test->filename = "ewl_text.c";
test->func = create_test;
test->type = EWL_TEST_TYPE_SIMPLE;
test->unit_tests = text_unit_tests;
}
The test->type can be one of EWL_TEST_TYPE_SIMPLE, EWL_TEST_TYPE_ADVANCED, EWL_TEST_TYPE_CONTAINER, EWL_TEST_TYPE_MISC or EWL_TEST_TYPE_UNIT. If you use TYPE_UNIT you can leave test->func as NULL as it won't be used.
The test->func is a function pointer with a signature like:
static int create_test(Ewl_Container *box);
This function has to return 1 on completion for the test to run. (You can return 0 if your test fails to init for some reason.)
If you'd like to put some unit tests into your testing the you'll need to add a section similar to:
static Ewl_Unit_Test text_unit_tests[] = {
{"text set/get", text_test_set_get},
{NULL, NULL}
};
To the top of your file (above the test_info function). This array _must_ be {NULL, NULL} terminated. Each entry is the name of the unit test and the function to call to invoke the test.
The unit test functions have a signature like:
static int text_test_set_get(char *buf, int len);
This function will return 1 if the test passes or 0 otherwise. If the test fails you can write the reason into buf to have it displayed in the UI. buf is len bytes long.
Once you've setup your unit tests you just need to add:
test->unit_tests = text_unit_tests;
into your test_info function. (Chaning text_unit_tests to whatever you called the array in your file.)
If you have no GUI test you can leave the func NULL. If you have no unit_tests then leave the unit_tests pointer as NULL.
Compile this as a shared library and install it into PACKAGE_LIB_DIR/ewl/tests (which by default is /usr/local/lib/ewl/tests) and restart the test app. Your test should show up under the category that you assigned.
You can either run your test in the ewl_test application 'Execute' tab or if you call ewl_test and pass the name of your test as a parameter it will run your test in a separate window. (You can also use the -unit flag to ewl_test to run the unit tests for your widget on the command line.)
Tutorials are pretty simple to add. Just add a doxygen block at the top of your test file. You will put in an @addtogroup with the same group name as in the src/lib file. You can then use @section, @code, @endcode and @note to markup your documentation.
If you'd like to help please send either myself or Nathan an email if you've got any questions. As always, patches accepted.
