From ca72690041e8458b1fc62eebd8ca376c12f1dfe7 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Thu, 12 Jun 2008 06:20:04 +0000 Subject: [PATCH] Testing documentation fixups svn path=/trunk/; revision=7025 --- docs/reference/ChangeLog | 13 ++ docs/reference/glib/Makefile.am | 10 +- docs/reference/glib/glib-docs.sgml | 4 + docs/reference/glib/glib-sections.txt | 9 +- docs/reference/glib/gtester-report.1 | 194 +++++++++++++++++ docs/reference/glib/gtester-report.xml | 54 +++++ docs/reference/glib/gtester.1 | 251 ++++++++++++++++++++++ docs/reference/glib/gtester.xml | 120 +++++++++++ docs/reference/glib/tmpl/fileutils.sgml | 10 + docs/reference/glib/tmpl/glib-unused.sgml | 11 + docs/reference/glib/tmpl/gurifuncs.sgml | 2 - docs/reference/glib/tmpl/i18n.sgml | 26 ++- docs/reference/glib/tmpl/testing.sgml | 248 +++++++++++++++++---- docs/reference/glib/tmpl/types.sgml | 2 + docs/reference/glib/tmpl/warnings.sgml | 20 +- 15 files changed, 902 insertions(+), 72 deletions(-) create mode 100644 docs/reference/glib/gtester-report.1 create mode 100644 docs/reference/glib/gtester-report.xml create mode 100644 docs/reference/glib/gtester.1 create mode 100644 docs/reference/glib/gtester.xml diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 2a66d9ac6..55b63ff26 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,16 @@ +2008-06-12 Matthias Clasen + + * glib/glib-sections.txt: Testing documentation fixups + +2008-06-12 Matthias Clasen + + * glib/gtester.xml: + * glib/gtester.1: + * glib/gtester-report.xml: + * glib/gtester-report.1: + * glib/glib-docs.sgml: + * glib/Makefile.am: Add gtester, gtester-report man pages + 2008-06-11 Behdad Esfahbod * glib/glib-sections.txt: Add g_dgettext() and g_dngettext(). diff --git a/docs/reference/glib/Makefile.am b/docs/reference/glib/Makefile.am index 71dbd82b9..69da894d5 100644 --- a/docs/reference/glib/Makefile.am +++ b/docs/reference/glib/Makefile.am @@ -61,7 +61,9 @@ content_files = \ resources.sgml \ regex-syntax.sgml \ version.xml \ - glib-gettextize.xml + glib-gettextize.xml \ + gtester.xml \ + gtester-report.xml # Extra options to supply to gtkdoc-fixref FIXXREF_OPTIONS= @@ -80,8 +82,10 @@ EXTRA_DIST += \ ######################################################################## -man_MANS = glib-gettextize.1 - +man_MANS = \ + glib-gettextize.1 \ + gtester.1 \ + gtester-report.1 if ENABLE_MAN %.1 : %.xml diff --git a/docs/reference/glib/glib-docs.sgml b/docs/reference/glib/glib-docs.sgml index 06f4b1fef..736504137 100644 --- a/docs/reference/glib/glib-docs.sgml +++ b/docs/reference/glib/glib-docs.sgml @@ -76,6 +76,8 @@ + + ]> @@ -196,6 +198,8 @@ synchronize their operation. GLib Tools &glib-gettextize; + >ester; + >ester-report; diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt index d85930eee..da1a67d93 100644 --- a/docs/reference/glib/glib-sections.txt +++ b/docs/reference/glib/glib-sections.txt @@ -853,7 +853,6 @@ g_return_if_reached g_return_val_if_reached g_warn_if_fail g_warn_if_reached -g_warn_message g_on_error_query @@ -865,6 +864,7 @@ G_BREAKPOINT g_return_if_fail_warning g_assert_warning +g_warn_message
@@ -1112,6 +1112,7 @@ g_chmod g_access g_creat g_chdir +g_utime g_file_error_quark @@ -2551,8 +2552,6 @@ g_compute_checksum_for_string
Testing testing -GTestCase -GTestSuite g_test_minimized_result g_test_maximized_result g_test_init @@ -2605,7 +2604,8 @@ g_assert_cmphex g_assert_cmpfloat g_strcmp0 - +GTestCase +GTestSuite g_test_create_case g_test_create_suite g_test_get_root @@ -2613,6 +2613,7 @@ g_test_suite_add g_test_suite_add_suite g_test_run_suite + g_test_trap_assertions g_assertion_message g_assertion_message_expr diff --git a/docs/reference/glib/gtester-report.1 b/docs/reference/glib/gtester-report.1 new file mode 100644 index 000000000..059f68b16 --- /dev/null +++ b/docs/reference/glib/gtester-report.1 @@ -0,0 +1,194 @@ +.\" Title: gtester-report +.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] +.\" Generator: DocBook XSL Stylesheets v1.74.0 +.\" Date: 06/12/2008 +.\" Manual: [FIXME: manual] +.\" Source: [FIXME: source] +.\" Language: English +.\" +.TH "GTESTER\-REPORT" "1" "06/12/2008" "[FIXME: source]" "[FIXME: manual]" +.\" ----------------------------------------------------------------- +.\" * (re)Define some macros +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" toupper - uppercase a string (locale-aware) +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.de toupper +.tr aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ +\\$* +.tr aabbccddeeffgghhiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz +.. +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" SH-xref - format a cross-reference to an SH section +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.de SH-xref +.ie n \{\ +.\} +.toupper \\$* +.el \{\ +\\$* +.\} +.. +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" SH - level-one heading that works better for non-TTY output +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.de1 SH +.\" put an extra blank line of space above the head in non-TTY output +.if t \{\ +.sp 1 +.\} +.sp \\n[PD]u +.nr an-level 1 +.set-an-margin +.nr an-prevailing-indent \\n[IN] +.fi +.in \\n[an-margin]u +.ti 0 +.HTML-TAG ".NH \\n[an-level]" +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +\." make the size of the head bigger +.ps +3 +.ft B +.ne (2v + 1u) +.ie n \{\ +.\" if n (TTY output), use uppercase +.toupper \\$* +.\} +.el \{\ +.nr an-break-flag 0 +.\" if not n (not TTY), use normal case (not uppercase) +\\$1 +.in \\n[an-margin]u +.ti 0 +.\" if not n (not TTY), put a border/line under subheading +.sp -.6 +\l'\n(.lu' +.\} +.. +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" SS - level-two heading that works better for non-TTY output +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.de1 SS +.sp \\n[PD]u +.nr an-level 1 +.set-an-margin +.nr an-prevailing-indent \\n[IN] +.fi +.in \\n[IN]u +.ti \\n[SN]u +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.ps \\n[PS-SS]u +\." make the size of the head bigger +.ps +2 +.ft B +.ne (2v + 1u) +.if \\n[.$] \&\\$* +.. +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" BB/BE - put background/screen (filled box) around block of text +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.de BB +.if t \{\ +.sp -.5 +.br +.in +2n +.ll -2n +.gcolor red +.di BX +.\} +.. +.de EB +.if t \{\ +.if "\\$2"adjust-for-leading-newline" \{\ +.sp -1 +.\} +.br +.di +.in +.ll +.gcolor +.nr BW \\n(.lu-\\n(.i +.nr BH \\n(dn+.5v +.ne \\n(BHu+.5v +.ie "\\$2"adjust-for-leading-newline" \{\ +\M[\\$1]\h'1n'\v'+.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[] +.\} +.el \{\ +\M[\\$1]\h'1n'\v'-.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[] +.\} +.in 0 +.sp -.5v +.nf +.BX +.in +.sp .5v +.fi +.\} +.. +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" BM/EM - put colored marker in margin next to block of text +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.de BM +.if t \{\ +.br +.ll -2n +.gcolor red +.di BX +.\} +.. +.de EM +.if t \{\ +.br +.di +.ll +.gcolor +.nr BH \\n(dn +.ne \\n(BHu +\M[\\$1]\D'P -.75n 0 0 \\n(BHu -(\\n[.i]u - \\n(INu - .75n) 0 0 -\\n(BHu'\M[] +.in 0 +.nf +.BX +.in +.fi +.\} +.. +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "Name" +gtester-report \- test report formatting utility +.SH "Synopsis" +.fam C +.HP \w'\fBgtester\-report\fR\ 'u +\fBgtester\-report\fR [option...] [gtester\-log] +.fam +.SH "Description" +.PP +\fBgtester\-report\fR +is a script which converts the XML output generated by gtester into HTML\&. +.SS "Options" +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +print help and exit +.RE +.PP +\fB\-v\fR, \fB\-\-version\fR +.RS 4 +print version information and exit +.RE +.SH "See also" +.PP + +\fBgtester\fR(1) diff --git a/docs/reference/glib/gtester-report.xml b/docs/reference/glib/gtester-report.xml new file mode 100644 index 000000000..614341de2 --- /dev/null +++ b/docs/reference/glib/gtester-report.xml @@ -0,0 +1,54 @@ + + + +gtester-report +1 + + + +gtester-report +test report formatting utility + + + + +gtester-report +option +gtester-log + + + +Description +gtester-report is a script which converts +the XML output generated by gtester into HTML. + + +Options + + + +, + +print help and exit + + + + +, + +print version information and exit + + + + + + + +See also + +gtester(1) + + + + + diff --git a/docs/reference/glib/gtester.1 b/docs/reference/glib/gtester.1 new file mode 100644 index 000000000..68639020e --- /dev/null +++ b/docs/reference/glib/gtester.1 @@ -0,0 +1,251 @@ +.\" Title: gtester +.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] +.\" Generator: DocBook XSL Stylesheets v1.74.0 +.\" Date: 06/12/2008 +.\" Manual: [FIXME: manual] +.\" Source: [FIXME: source] +.\" Language: English +.\" +.TH "GTESTER" "1" "06/12/2008" "[FIXME: source]" "[FIXME: manual]" +.\" ----------------------------------------------------------------- +.\" * (re)Define some macros +.\" ----------------------------------------------------------------- +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" toupper - uppercase a string (locale-aware) +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.de toupper +.tr aAbBcCdDeEfFgGhHiIjJkKlLmMnNoOpPqQrRsStTuUvVwWxXyYzZ +\\$* +.tr aabbccddeeffgghhiijjkkllmmnnooppqqrrssttuuvvwwxxyyzz +.. +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" SH-xref - format a cross-reference to an SH section +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.de SH-xref +.ie n \{\ +.\} +.toupper \\$* +.el \{\ +\\$* +.\} +.. +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" SH - level-one heading that works better for non-TTY output +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.de1 SH +.\" put an extra blank line of space above the head in non-TTY output +.if t \{\ +.sp 1 +.\} +.sp \\n[PD]u +.nr an-level 1 +.set-an-margin +.nr an-prevailing-indent \\n[IN] +.fi +.in \\n[an-margin]u +.ti 0 +.HTML-TAG ".NH \\n[an-level]" +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +\." make the size of the head bigger +.ps +3 +.ft B +.ne (2v + 1u) +.ie n \{\ +.\" if n (TTY output), use uppercase +.toupper \\$* +.\} +.el \{\ +.nr an-break-flag 0 +.\" if not n (not TTY), use normal case (not uppercase) +\\$1 +.in \\n[an-margin]u +.ti 0 +.\" if not n (not TTY), put a border/line under subheading +.sp -.6 +\l'\n(.lu' +.\} +.. +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" SS - level-two heading that works better for non-TTY output +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.de1 SS +.sp \\n[PD]u +.nr an-level 1 +.set-an-margin +.nr an-prevailing-indent \\n[IN] +.fi +.in \\n[IN]u +.ti \\n[SN]u +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.ps \\n[PS-SS]u +\." make the size of the head bigger +.ps +2 +.ft B +.ne (2v + 1u) +.if \\n[.$] \&\\$* +.. +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" BB/BE - put background/screen (filled box) around block of text +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.de BB +.if t \{\ +.sp -.5 +.br +.in +2n +.ll -2n +.gcolor red +.di BX +.\} +.. +.de EB +.if t \{\ +.if "\\$2"adjust-for-leading-newline" \{\ +.sp -1 +.\} +.br +.di +.in +.ll +.gcolor +.nr BW \\n(.lu-\\n(.i +.nr BH \\n(dn+.5v +.ne \\n(BHu+.5v +.ie "\\$2"adjust-for-leading-newline" \{\ +\M[\\$1]\h'1n'\v'+.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[] +.\} +.el \{\ +\M[\\$1]\h'1n'\v'-.5v'\D'P \\n(BWu 0 0 \\n(BHu -\\n(BWu 0 0 -\\n(BHu'\M[] +.\} +.in 0 +.sp -.5v +.nf +.BX +.in +.sp .5v +.fi +.\} +.. +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.\" BM/EM - put colored marker in margin next to block of text +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.de BM +.if t \{\ +.br +.ll -2n +.gcolor red +.di BX +.\} +.. +.de EM +.if t \{\ +.br +.di +.ll +.gcolor +.nr BH \\n(dn +.ne \\n(BHu +\M[\\$1]\D'P -.75n 0 0 \\n(BHu -(\\n[.i]u - \\n(INu - .75n) 0 0 -\\n(BHu'\M[] +.in 0 +.nf +.BX +.in +.fi +.\} +.. +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "Name" +gtester \- test running utility +.SH "Synopsis" +.fam C +.HP \w'\fBgtester\fR\ 'u +\fBgtester\fR [option...] [testprogram] +.fam +.SH "Description" +.PP +\fBgtester\fR +is a utility to run unit tests that have been written using the GLib test framework\&. +.PP +When called with the +\fB\-o\fR +option, +\fBgtester\fR +writes an XML report of the test results, which can be converted into HTML using the +\fBgtester\-report\fR +utility\&. +.SS "Options" +.PP +\fB\-h\fR, \fB\-\-help\fR +.RS 4 +print help and exit +.RE +.PP +\fB\-v\fR, \fB\-\-version\fR +.RS 4 +print version information and exit +.RE +.PP +\fB\-\-g\-fatal\-warnings\fR +.RS 4 +make warnings fatal +.RE +.PP +\fB\-k\fR, \fB\-\-keep\-going\fR +.RS 4 +continue running after tests failed +.RE +.PP +\fB\-l\fR +.RS 4 +list paths of available test cases +.RE +.PP +\fB\-m=\fR\fB\fIMODE\fR\fR +.RS 4 +run test cases in +\fIMODE\fR, which can be perf, slow, thorough or quick\&. The default mode is quick\&. +.RE +.PP +\fB\-p=\fR\fB\fITESTPATH\fR\fR +.RS 4 +only run test cases matching +\fITESTPATH\fR +.RE +.PP +\fB\-\-seed=\fR\fB\fISEEDSTRING\fR\fR +.RS 4 +run all test cases with random number seed +\fISEEDSTRING\fR +.RE +.PP +\fB\-o=\fR\fB\fILOGFILE\fR\fR +.RS 4 +write the test log to +\fILOGFILE\fR +.RE +.PP +\fB\-q\fR, \fB\-\-quiet\fR +.RS 4 +suppress per test binary output +.RE +.PP +\fB\-\-verbose\fR +.RS 4 +report success per testcase +.RE +.SH "See also" +.PP + +\fBgtester\-report\fR(1) diff --git a/docs/reference/glib/gtester.xml b/docs/reference/glib/gtester.xml new file mode 100644 index 000000000..840dbea2c --- /dev/null +++ b/docs/reference/glib/gtester.xml @@ -0,0 +1,120 @@ + + + +gtester +1 + + + +gtester +test running utility + + + + +gtester +option +testprogram + + + +Description +gtester is a utility to run unit tests that have +been written using the GLib test framework. + + +When called with the option, gtester +writes an XML report of the test results, which can be converted +into HTML using the gtester-report utility. + + +Options + + + +, + +print help and exit + + + + +, + +print version information and exit + + + + + + +make warnings fatal + + + + +, + +continue running after tests failed + + + + + + +list paths of available test cases + + + + + + +run test cases in MODE, which can be perf, slow, thorough or quick. The default mode is quick. + + + + + + +only run test cases matching TESTPATH + + + + + + +run all test cases with random number seed SEEDSTRING + + + + + + +write the test log to LOGFILE + + + + +, + +suppress per test binary output + + + + + + +report success per testcase + + + + + + + +See also + +gtester-report(1) + + + diff --git a/docs/reference/glib/tmpl/fileutils.sgml b/docs/reference/glib/tmpl/fileutils.sgml index 017c54b32..0b9ef6c74 100644 --- a/docs/reference/glib/tmpl/fileutils.sgml +++ b/docs/reference/glib/tmpl/fileutils.sgml @@ -458,3 +458,13 @@ not be accessed directly. @Returns: + + + + + +@filename: +@utb: +@Returns: + + diff --git a/docs/reference/glib/tmpl/glib-unused.sgml b/docs/reference/glib/tmpl/glib-unused.sgml index fe2e351a3..ca73e16e9 100644 --- a/docs/reference/glib/tmpl/glib-unused.sgml +++ b/docs/reference/glib/tmpl/glib-unused.sgml @@ -877,6 +877,17 @@ Turns the argument into a string literal by using the '#' stringizing operator. @x: text to convert to a literal string. + + + + + +@domain: +@file: +@line: +@func: +@warnexpr: + diff --git a/docs/reference/glib/tmpl/gurifuncs.sgml b/docs/reference/glib/tmpl/gurifuncs.sgml index ca280305e..8e95d60ee 100644 --- a/docs/reference/glib/tmpl/gurifuncs.sgml +++ b/docs/reference/glib/tmpl/gurifuncs.sgml @@ -9,13 +9,11 @@ URI Functions - - diff --git a/docs/reference/glib/tmpl/i18n.sgml b/docs/reference/glib/tmpl/i18n.sgml index 8ebc4541c..4c1fe7980 100644 --- a/docs/reference/glib/tmpl/i18n.sgml +++ b/docs/reference/glib/tmpl/i18n.sgml @@ -115,13 +115,25 @@ To get the translated string, call gettext() at runtime. @Since: 2.4 - + +@domain: @msgid: -@msgval: +@Returns: + + + + + + + +@domain: +@msgid: +@msgid_plural: +@n: @Returns: @@ -136,6 +148,16 @@ To get the translated string, call gettext() at runtime. @Returns: + + + + + +@msgid: +@msgval: +@Returns: + + diff --git a/docs/reference/glib/tmpl/testing.sgml b/docs/reference/glib/tmpl/testing.sgml index 9cbd73f1c..52a218a9d 100644 --- a/docs/reference/glib/tmpl/testing.sgml +++ b/docs/reference/glib/tmpl/testing.sgml @@ -2,35 +2,70 @@ Testing - +a test framework - +GLib provides a framework for writing and maintaining unit tests +in parallel to the code they are testing. The API is designed according +to established concepts found in the other test frameworks (JUnit, NUnit, +RUnit), which in turn is based on smalltalk unit testing concepts. + + + Test case + + Tests (test methods) are grouped together with their + fixture into test cases. + + + + Fixture + + A test fixture consists of fixture data and setup and teardown methods + to establish the environment for the test functions. We use fresh + fixtures, i.e. fixtures are newly set up and torn down around each test + invokation to avoid dependencies between tests. + + + + Test suite + + Test cases can be grouped into test suites, to allow subsets of the + available tests to be run. Test suites can be grouped into other test + suites as well. + + + +The API is designed to handle creation and registration of test suites and +test cases implicitly. A simple call like + + g_test_add_func ("/misc/assertions", test_assertions); + +creates a test suite called "misc" with a single test case named "assertions", +which consists of running the test_assertions function. + + +In addition to the traditional g_assert(), the test framework provides +an extended set of assertions for string and numerical comparisons: +g_assert_cmpfloat(), g_assert_cmpint(), g_assert_cmpuint(), g_assert_cmphex(), +g_assert_cmpstr(). The advantage of these variants over plain g_assert() +is that the assertion messages can be more elaborate, and include the +values of the compared entities. + + +GLib ships with two utilites called gtester and gtester-report to +facilitate running tests and producing nicely formatted test reports. - - +gtester, +gtester-report - - - - - - - - - - - - - @@ -63,42 +98,42 @@ Testing - +Returns %TRUE if tests are run in quick mode. - +Returns %TRUE if tests are run in slow mode. - +Returns %TRUE if tests are run in thorough mode. - +Returns %TRUE if tests are run in performance mode. - +Returns %TRUE if tests are run in verbose mode. - +Returns %TRUE if tests are run in quite mode. @@ -342,67 +377,118 @@ Testing - +Debugging macro to terminate the application if the assertion fails. +If the assertion fails (i.e. the expression is not true), an error message +is logged and the application is terminated. + + +The macro can be turned off in final releases of code by defining +#G_DISABLE_ASSERT when compiling the application. -@expr: +@expr: the expression to check. - +Debugging macro to terminate the application if it is ever reached. +If it is reached, an error message is logged and the application is terminated. + + +The macro can be turned off in final releases of code by defining +#G_DISABLE_ASSERT when compiling the application. - +Debugging macro to terminate the application with a warning message +if a string comparison fails. +The strings are compared using g_strcmp0(). + +The effect of g_assert_cmpstr (s1, op, s2) is the same +as g_assert (s1 op s2). The advantage of this macro +is that it can produce a message that includes the actual values of @s1 +and @s2. + + + g_assert_cmpstr (mystring, ==, "fubar"); + -@s1: -@cmp: -@s2: +@s1: a string (may be %NULL) +@cmp: The comparsion operator to use. One of ==, !=, <, >, <=, >=. +@s2: another string (may be %NULL) +Since: 2.16 - +Debugging macro to terminate the application with a warning message +if an integer comparison fails. + + +The effect of g_assert_cmpint (n1, op, n2) is the same +as g_assert (n1 op n2). The advantage of this macro +is that it can produce a message that includes the actual values of @n1 +and @n2. -@n1: -@cmp: -@n2: +@n1: an integer +@cmp: The comparsion operator to use. One of ==, !=, <, >, <=, >=. +@n2: another integer +Since: 2.16 - +Debugging macro to terminate the application with a warning message +if an unsigned integer comparison fails. + + +The effect of g_assert_cmpuint (n1, op, n2) is the same +as g_assert (n1 op n2). The advantage of this macro +is that it can produce a message that includes the actual values of @n1 +and @n2. -@n1: -@cmp: -@n2: +@n1: an unsigned integer +@cmp: The comparsion operator to use. One of ==, !=, <, >, <=, >=. +@n2: another unsigned integer +Since: 2.16 - +Debugging macro to terminate the application with a warning message +if an unsigned integer comparison fails. This is a variant of +g_assert_cmpuint() that displays the numbers in hexadecimal notation +in the message. -@n1: -@cmp: -@n2: +@n1: an unsigned integer +@cmp: The comparsion operator to use. One of ==, !=, <, >, <=, >=. +@n2: another unsigned integer +Since: 2.16 - +Debugging macro to terminate the application with a warning message +if a floating point number comparison fails. + + +The effect of g_assert_cmpflott (n1, op, n2) is the same +as g_assert (n1 op n2). The advantage of this function +is that it can produce a message that includes the actual values of @n1 +and @n2. -@n1: -@cmp: -@n2: +@n1: an floating point number +@cmp: The comparsion operator to use. One of ==, !=, <, >, <=, >=. +@n2: another floating point number +Since: 2.16 @@ -415,3 +501,73 @@ Testing @Returns: + + +An opaque structure representing a test case. + + + + + +An opaque structure representing a test suite. + + + + + + + + +@test_name: +@data_size: +@test_data: +@data_setup: +@data_test: +@data_teardown: +@Returns: + + + + + + + +@suite_name: +@Returns: + + + + + + + +@Returns: + + + + + + + +@suite: +@test_case: + + + + + + + +@suite: +@nestedsuite: + + + + + + + +@suite: +@Returns: + + diff --git a/docs/reference/glib/tmpl/types.sgml b/docs/reference/glib/tmpl/types.sgml index e8b6c3e83..4c3b77883 100644 --- a/docs/reference/glib/tmpl/types.sgml +++ b/docs/reference/glib/tmpl/types.sgml @@ -185,6 +185,8 @@ An unsigned integer guaranteed to be 64 bits on all platforms. Values of this type can range from 0 to 18,446,744,073,709,551,615. +@Returns: + diff --git a/docs/reference/glib/tmpl/warnings.sgml b/docs/reference/glib/tmpl/warnings.sgml index e7f46a721..cc4687891 100644 --- a/docs/reference/glib/tmpl/warnings.sgml +++ b/docs/reference/glib/tmpl/warnings.sgml @@ -136,29 +136,19 @@ Logs a critical message and returns @val. - +Logs a warning if the expression is not true. -@expr: +@expr: the expression to check +@Since: 2.16 - +Logs a critical warning. - - - - - - - -@domain: -@file: -@line: -@func: -@warnexpr: +@Since: 2.16