File: README

package info (click to toggle)
pigment 0.3.6-3
  • links: PTS
  • area: main
  • in suites: lenny
  • size: 7,060 kB
  • ctags: 7,318
  • sloc: ansic: 34,269; xml: 11,990; sh: 9,155; makefile: 560; perl: 383
file content (158 lines) | stat: -rw-r--r-- 7,064 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
This directory contains regression tests, functionality tests, etc

check/
   unit tests using the check library, non-interactive
interactive/
   interactive tests
misc/
   prototypes, random bits, etc

A few words about the test framework used in check/ and interactive/:
They both use the pgmcheck static library defined in check/common/, which is
built at make check. This library depends on check
(http://check.sourceforge.net/), as well as on gstcheck, a gstreamer extension
to check. Check, gstcheck and pgmcheck provide a few facilities to ease the
creation and running of tests.


1. The pgmcheck library

1.1 Running tests
To run all non-interactive tests, run "make check" in the main source
directory or in tests/. To run only C unit tests, run "make check" in
tests/check. If you are interested in a specific set of tests, you can run
"make check" in a specific subdirectory of tests/check. If you are only
interested in a few specific tests, you can define the PGM_CHECKS environment
variable with a comma separated list of tests to run, and run "make check"
either in tests/check/ or in a specific subdirectory containing the tests you
want to run.
For instance:
  $ cd tests/check/pgm
  $ make check PGM_CHECKS=test_main,test_version

If you want to run all the tests in a given test program, say, foobar, you can
run make foobar.check. In the same fashion, you can run make foobar.gdb to run
the test program in a debugger. If you are interested in a particular test
function you can simply do:
  $ make foobar.check PGM_CHECKS=test_foo
or for debugging:
  $ make foobar.gdb PGM_CHECKS=test_foo

If you want to debug a test without using this facility, you need to know two
things:
 - The framework normaly forks before running each test function, to disable
   this, you must set the CK_FORK environment variable to no.
 - If your test program is tests/check/foo/bar, the actual executable is
   tests/check/foo/.libs/bar. A lt-bar with some libtool automation is
   provided as well. tests/check/foo/bar is only a shell script.
 - You are likely to need to run the misc/pgm-uninstalled script before
   running a test program outside of a make rule.

1.2 Writing tests
1.2.1 Mandatory tests
Here are the steps you need to follow to write tests using this framework:
 - Include tests/check/common/pgmcheck.h and link you program with
   tests/check/common/libpgmcheck.a (this linkage is done automatically if you
   include tests/check/common/common-tests.am in your Makefile.am).
 - Define your test function as follow:
   PGM_START_TEST (test_foo_bar)
   {
      /* function code */
   }
   PGM_END_TEST
 - Define a test suite containing several related tests:
   Suite *
   pgm_suite (void)
   {
     Suite *s = suite_create ("Foo");
     TCase *tc_chain = tcase_create ("foo tests");

     suite_add_tcase (s, tc_chain);
     tcase_add_test (tc_chain, test_foo_bar);
     tcase_add_test (tc_chain, test_bar_foo);

     return s;
   }

1.2.2 Fixtures
Optionally, you can use fixtures to factorise your code. Please see the
documentation of check to know more about fixtures. A default set of fixture
is defined in libpgmcheck. To use them, you should use the
PGM_USE_STANDARD_FIXTURES() macro.

1.2.3 Forks
When designing and writing tests, you need to be aware that Check creates a
new process (using fork()) for each test function it runs. Therefore, two test
functions cannot share data as if they were in the same thread. Also, you have
two kinds of fixtures, checked (run for each test function in the same process
as the test function), and unchecked (run for each test case in the main
process).


2. Unit tests

They are in the tests/check/ directory. It does not have any tests in it, but
have a few subdirectories containing mainly unit tests:

 common/        Common Makefile.am routines (in common-tests.am) providing many
                useful rules as well as handling the linking with pigment and
                its dependencies.
 pgm/           Tests on the core of pigment. For the moment, each source file
                contains tests for a given class in the core.
 plugins/       Tests for the rendering plugins.
 +-common/      A static library (libpgmplugintestsuite.a)  with a
 |              set of tests to be run on all plugins. If you want to run
 |              these tests on your plugin, create a subdirectory in plugins/,
 |              and add a program in it that is linked against
 |              libpgmplugintestsuite.a and calls plugin_suites_run(), after
 |              having used the macro PGM_TEST_USE_PLUGIN() outside of any
 |              function. The first argument to this macro is the name of the
 |              plugin, the second is the reference count that it adds to
 |              pigment objects (other than PgmViewportFactory). See
 |              plugins/boilerplate/ for an example.
 +-boilerplate/ A test program running the plugin test suite on the
 |              boilerplate plugin.
 +-opengl/      Tests for the opengl plugin. This includes the plugin tests
                suite as well as a few specific tests.


3. Interactive tests

3.1 Running
They are in the tests/interactive/ subdirectory. For the moment, there is only
one test program that runs several test suites. You should use the PGM_CHECKS
environment variable as explained in 1.1 if you want to only run specific
tests.
The tests written so far are rendering tests, with a GTK+ window showing a
screenshot of the expected rendering on the left, and the pigment rendering on
the right. The user is asked whether the two renderings are the same. If she
answers "Yes", the test passes, else it fails.

3.2 Writing
To add a rendering test, you need to write a rendering function, add it to a
test suite (or create a new test suite), and ensure that this test suite is
run in main.c. If you add a new source file, you need to add it to
interactive_tests_SOURCES in Makefile.am, and you need to include
interactive_tests.h in your file. Once this is done, run "make check
PGM_CHECKS=your_test_name" in the tests/interactive/ directory to test that
your rendering is correct. If it is, you can generate a screenshot of your
rendering, to display on the left side of the window, by calling "make
screenshots PGM_CHECKS=your_test_name".

3.2.1 Rendering function
Your rendering function should make use of an already instanciated viewport in
the global variable interactive_test_viewport. You need to use
PGM_START_INTERACTIVE_TEST() and PGM_END_INTERACTIVE_TEST to define your
function. See e.g. test_text_basic at the beginning of
tests/interactive/pgmtext.c.

3.2.2 Test suite
You need to do as explained in 1.2.1, but you must use the
PGM_INTERACTIVE_TESTS_SET_FIXTURES() macro. Again, tests/interactive/pgmtext.c
is a good and simple example of how to proceed.

3.2.3 Running a test suite
The only thing you should modify in main.c is that if you create a new test
suite, you should add a line like:
  ret += gst_check_run_suite (pgm_foo_suite (), "pgm_foo_suite", __FILE__);
near the end of the main() function.