+2008-06-12 Matthias Clasen <mclasen@redhat.com>
+
+ * glib/glib-sections.txt: Testing documentation fixups
+
+2008-06-12 Matthias Clasen <mclasen@redhat.com>
+
+ * 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 <behdad@gnome.org>
* glib/glib-sections.txt: Add g_dgettext() and g_dngettext().
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=
########################################################################
-man_MANS = glib-gettextize.1
-
+man_MANS = \
+ glib-gettextize.1 \
+ gtester.1 \
+ gtester-report.1
if ENABLE_MAN
%.1 : %.xml
<!ENTITY glib-RegexSyntax SYSTEM "regex-syntax.sgml">
<!ENTITY glib-gettextize SYSTEM "glib-gettextize.xml">
+<!ENTITY gtester SYSTEM "gtester.xml">
+<!ENTITY gtester-report SYSTEM "gtester-report.xml">
<!ENTITY version SYSTEM "version.xml">
]>
<title>GLib Tools</title>
&glib-gettextize;
+ >ester;
+ >ester-report;
</chapter>
<index>
g_return_val_if_reached
g_warn_if_fail
g_warn_if_reached
-g_warn_message
<SUBSECTION>
g_on_error_query
<SUBSECTION Private>
g_return_if_fail_warning
g_assert_warning
+g_warn_message
</SECTION>
<SECTION>
g_access
g_creat
g_chdir
+g_utime
<SUBSECTION Private>
g_file_error_quark
<SECTION>
<TITLE>Testing</TITLE>
<FILE>testing</FILE>
-GTestCase
-GTestSuite
g_test_minimized_result
g_test_maximized_result
g_test_init
g_assert_cmpfloat
g_strcmp0
-<SUBSECTION Private>
+GTestCase
+GTestSuite
g_test_create_case
g_test_create_suite
g_test_get_root
g_test_suite_add_suite
g_test_run_suite
+<SUBSECTION Private>
g_test_trap_assertions
g_assertion_message
g_assertion_message_expr
--- /dev/null
+.\" Title: gtester-report
+.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
+.\" Generator: DocBook XSL Stylesheets v1.74.0 <http://docbook.sf.net/>
+.\" 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)
--- /dev/null
+<refentry id="gtester-report">
+
+<refmeta>
+<refentrytitle>gtester-report</refentrytitle>
+<manvolnum>1</manvolnum>
+</refmeta>
+
+<refnamediv>
+<refname>gtester-report</refname>
+<refpurpose>test report formatting utility</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<cmdsynopsis>
+<command>gtester-report</command>
+<arg choice="opt" rep="repeat">option</arg>
+<arg>gtester-log</arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+<para><command>gtester-report</command> is a script which converts
+the XML output generated by gtester into HTML.
+</para>
+
+<refsect2><title>Options</title>
+<variablelist>
+
+<varlistentry>
+<term><option>-h</option>, <option>--help</option></term>
+<listitem><para>
+print help and exit
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-v</option>, <option>--version</option></term>
+<listitem><para>
+print version information and exit
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+</refsect2>
+</refsect1>
+
+<refsect1><title>See also</title>
+<para>
+<command>gtester</command>(1)
+</para>
+</refsect1>
+</refentry>
+
+
--- /dev/null
+.\" Title: gtester
+.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
+.\" Generator: DocBook XSL Stylesheets v1.74.0 <http://docbook.sf.net/>
+.\" 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)
--- /dev/null
+<refentry id="gtester">
+
+<refmeta>
+<refentrytitle>gtester</refentrytitle>
+<manvolnum>1</manvolnum>
+</refmeta>
+
+<refnamediv>
+<refname>gtester</refname>
+<refpurpose>test running utility</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<cmdsynopsis>
+<command>gtester</command>
+<arg choice="opt" rep="repeat">option</arg>
+<arg>testprogram</arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1><title>Description</title>
+<para><command>gtester</command> is a utility to run unit tests that have
+been written using the GLib test framework.
+</para>
+<para>
+When called with the <option>-o</option> option, <command>gtester</command>
+writes an XML report of the test results, which can be converted
+into HTML using the <command>gtester-report</command> utility.
+</para>
+
+<refsect2><title>Options</title>
+<variablelist>
+
+<varlistentry>
+<term><option>-h</option>, <option>--help</option></term>
+<listitem><para>
+print help and exit
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-v</option>, <option>--version</option></term>
+<listitem><para>
+print version information and exit
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--g-fatal-warnings</option></term>
+<listitem><para>
+make warnings fatal
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-k</option>, <option>--keep-going</option></term>
+<listitem><para>
+continue running after tests failed
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-l</option></term>
+<listitem><para>
+list paths of available test cases
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-m=<replaceable>MODE</replaceable></option></term>
+<listitem><para>
+run test cases in <replaceable>MODE</replaceable>, which can be perf, slow, thorough or quick. The default mode is quick.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-p=<replaceable>TESTPATH</replaceable></option></term>
+<listitem><para>
+only run test cases matching <replaceable>TESTPATH</replaceable>
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--seed=<replaceable>SEEDSTRING</replaceable></option></term>
+<listitem><para>
+run all test cases with random number seed <replaceable>SEEDSTRING</replaceable>
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-o=<replaceable>LOGFILE</replaceable></option></term>
+<listitem><para>
+write the test log to <replaceable>LOGFILE</replaceable>
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>-q</option>, <option>--quiet</option></term>
+<listitem><para>
+suppress per test binary output
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><option>--verbose</option></term>
+<listitem><para>
+report success per testcase
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+</refsect2>
+</refsect1>
+
+<refsect1><title>See also</title>
+<para>
+<command>gtester-report</command>(1)
+</para>
+</refsect1>
+</refentry>
@Returns:
+<!-- ##### FUNCTION g_utime ##### -->
+<para>
+
+</para>
+
+@filename:
+@utb:
+@Returns:
+
+
@x: text to convert to a literal string.
+<!-- ##### FUNCTION g_warn_message ##### -->
+<para>
+
+</para>
+
+@domain:
+@file:
+@line:
+@func:
+@warnexpr:
+
<!-- ##### MACRO getcwd ##### -->
<para>
</para>
-
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
-
<!-- ##### SECTION Stability_Level ##### -->
@Since: 2.4
-<!-- ##### FUNCTION g_strip_context ##### -->
+<!-- ##### FUNCTION g_dgettext ##### -->
<para>
</para>
+@domain:
@msgid:
-@msgval:
+@Returns:
+
+
+<!-- ##### FUNCTION g_dngettext ##### -->
+<para>
+
+</para>
+
+@domain:
+@msgid:
+@msgid_plural:
+@n:
@Returns:
@Returns:
+<!-- ##### FUNCTION g_strip_context ##### -->
+<para>
+
+</para>
+
+@msgid:
+@msgval:
+@Returns:
+
+
<!-- ##### FUNCTION g_get_language_names ##### -->
<para>
Testing
<!-- ##### SECTION Short_Description ##### -->
-
+a test framework
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+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.
+<variablelist>
+ <varlistentry>
+ <term>Test case</term>
+ <listitem><para>
+ Tests (test methods) are grouped together with their
+ fixture into test cases.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Fixture</term>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Test suite</term>
+ <listitem><para>
+ 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.
+ </para></listitem>
+ </varlistentry>
+</variablelist>
+The API is designed to handle creation and registration of test suites and
+test cases implicitly. A simple call like
+<informalexample><programlisting>
+ g_test_add_func ("/misc/assertions", test_assertions);
+</programlisting></informalexample>
+creates a test suite called "misc" with a single test case named "assertions",
+which consists of running the test_assertions function.
+</para>
+<para>
+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.
+</para>
+<para>
+GLib ships with two utilites called gtester and gtester-report to
+facilitate running tests and producing nicely formatted test reports.
</para>
-
<!-- ##### SECTION See_Also ##### -->
<para>
-
+<link linkend="gtester">gtester</link>,
+<link linkend="gtester-report">gtester-report</link>
</para>
-
<!-- ##### SECTION Stability_Level ##### -->
-<!-- ##### TYPEDEF GTestCase ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### TYPEDEF GTestSuite ##### -->
-<para>
-
-</para>
-
-
<!-- ##### FUNCTION g_test_minimized_result ##### -->
<para>
<!-- ##### MACRO g_test_quick ##### -->
<para>
-
+Returns %TRUE if tests are run in quick mode.
</para>
<!-- ##### MACRO g_test_slow ##### -->
<para>
-
+Returns %TRUE if tests are run in slow mode.
</para>
<!-- ##### MACRO g_test_thorough ##### -->
<para>
-
+Returns %TRUE if tests are run in thorough mode.
</para>
<!-- ##### MACRO g_test_perf ##### -->
<para>
-
+Returns %TRUE if tests are run in performance mode.
</para>
<!-- ##### MACRO g_test_verbose ##### -->
<para>
-
+Returns %TRUE if tests are run in verbose mode.
</para>
<!-- ##### MACRO g_test_quiet ##### -->
<para>
-
+Returns %TRUE if tests are run in quite mode.
</para>
<!-- ##### MACRO g_assert ##### -->
<para>
-
+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.
+</para>
+<para>
+The macro can be turned off in final releases of code by defining
+#G_DISABLE_ASSERT when compiling the application.
</para>
-@expr:
+@expr: the expression to check.
<!-- ##### MACRO g_assert_not_reached ##### -->
<para>
-
+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.
+</para>
+<para>
+The macro can be turned off in final releases of code by defining
+#G_DISABLE_ASSERT when compiling the application.
</para>
<!-- ##### MACRO g_assert_cmpstr ##### -->
<para>
-
+Debugging macro to terminate the application with a warning message
+if a string comparison fails.
+The strings are compared using g_strcmp0().
</para>
+<para>
+The effect of <literal>g_assert_cmpstr (s1, op, s2)</literal> is the same
+as <literal>g_assert (s1 op s2)</literal>. The advantage of this macro
+is that it can produce a message that includes the actual values of @s1
+and @s2.
+</para>
+<informalexample><programlisting>
+ g_assert_cmpstr (mystring, ==, "fubar");
+</programlisting></informalexample>
-@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
<!-- ##### MACRO g_assert_cmpint ##### -->
<para>
-
+Debugging macro to terminate the application with a warning message
+if an integer comparison fails.
+</para>
+<para>
+The effect of <literal>g_assert_cmpint (n1, op, n2)</literal> is the same
+as <literal>g_assert (n1 op n2)</literal>. The advantage of this macro
+is that it can produce a message that includes the actual values of @n1
+and @n2.
</para>
-@n1:
-@cmp:
-@n2:
+@n1: an integer
+@cmp: The comparsion operator to use. One of ==, !=, <, >, <=, >=.
+@n2: another integer
+Since: 2.16
<!-- ##### MACRO g_assert_cmpuint ##### -->
<para>
-
+Debugging macro to terminate the application with a warning message
+if an unsigned integer comparison fails.
+</para>
+<para>
+The effect of <literal>g_assert_cmpuint (n1, op, n2)</literal> is the same
+as <literal>g_assert (n1 op n2)</literal>. The advantage of this macro
+is that it can produce a message that includes the actual values of @n1
+and @n2.
</para>
-@n1:
-@cmp:
-@n2:
+@n1: an unsigned integer
+@cmp: The comparsion operator to use. One of ==, !=, <, >, <=, >=.
+@n2: another unsigned integer
+Since: 2.16
<!-- ##### MACRO g_assert_cmphex ##### -->
<para>
-
+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.
</para>
-@n1:
-@cmp:
-@n2:
+@n1: an unsigned integer
+@cmp: The comparsion operator to use. One of ==, !=, <, >, <=, >=.
+@n2: another unsigned integer
+Since: 2.16
<!-- ##### MACRO g_assert_cmpfloat ##### -->
<para>
-
+Debugging macro to terminate the application with a warning message
+if a floating point number comparison fails.
+</para>
+<para>
+The effect of <literal>g_assert_cmpflott (n1, op, n2)</literal> is the same
+as <literal>g_assert (n1 op n2)</literal>. The advantage of this function
+is that it can produce a message that includes the actual values of @n1
+and @n2.
</para>
-@n1:
-@cmp:
-@n2:
+@n1: an floating point number
+@cmp: The comparsion operator to use. One of ==, !=, <, >, <=, >=.
+@n2: another floating point number
+Since: 2.16
<!-- ##### FUNCTION g_strcmp0 ##### -->
@Returns:
+<!-- ##### TYPEDEF GTestCase ##### -->
+<para>
+An opaque structure representing a test case.
+</para>
+
+
+<!-- ##### TYPEDEF GTestSuite ##### -->
+<para>
+An opaque structure representing a test suite.
+</para>
+
+
+<!-- ##### FUNCTION g_test_create_case ##### -->
+<para>
+
+</para>
+
+@test_name:
+@data_size:
+@test_data:
+@data_setup:
+@data_test:
+@data_teardown:
+@Returns:
+
+
+<!-- ##### FUNCTION g_test_create_suite ##### -->
+<para>
+
+</para>
+
+@suite_name:
+@Returns:
+
+
+<!-- ##### FUNCTION g_test_get_root ##### -->
+<para>
+
+</para>
+
+@Returns:
+
+
+<!-- ##### FUNCTION g_test_suite_add ##### -->
+<para>
+
+</para>
+
+@suite:
+@test_case:
+
+
+<!-- ##### FUNCTION g_test_suite_add_suite ##### -->
+<para>
+
+</para>
+
+@suite:
+@nestedsuite:
+
+
+<!-- ##### FUNCTION g_test_run_suite ##### -->
+<para>
+
+</para>
+
+@suite:
+@Returns:
+
+
Values of this type can range from 0 to 18,446,744,073,709,551,615.
</para>
+@Returns:
+
<!-- ##### MACRO G_GINT64_CONSTANT ##### -->
<para>
<!-- ##### MACRO g_warn_if_fail ##### -->
<para>
-
+Logs a warning if the expression is not true.
</para>
-@expr:
+@expr: the expression to check
+@Since: 2.16
<!-- ##### MACRO g_warn_if_reached ##### -->
<para>
-
-</para>
-
-
-
-<!-- ##### FUNCTION g_warn_message ##### -->
-<para>
-
+Logs a critical warning.
</para>
-@domain:
-@file:
-@line:
-@func:
-@warnexpr:
+@Since: 2.16
<!-- ##### FUNCTION g_on_error_query ##### -->
projects / platform / upstream / glib.git / commitdiff