blob: b93dca7a69ee944d70332cf3cf310e47ad72ebc7 (
plain) (
blame)
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
|
=====================================
test(3) - a library for writing tests
=====================================
The ``test(3)`` API and its related scaffolding generator
(`make-test-scaffolding(1) <mts_>`_) work together to reduce the
boilerplate needed for tests.
.. _mts: bin/make-test-scaffolding
Quick Start
===========
The following source code defines a test suite that contains a single
test:
.. code:: c
/* File: test.c */
#include "test.h"
enum test_result
tf_goodbye_world(testcase_state tcs)
{
return (TEST_PASS);
}
By convention, test functions are named using a ``tf_`` prefix.
Given an object file compiled from this source, the
`make-test-scaffolding(1) <mts_>`_ utility would generate scaffolding
describing a single invocable test named "``goodbye_world``".
Test Cases
----------
Test functions that are related to each other can be grouped into test
cases. The following code snippet defines a test suite with two test
functions contained in a test case named "``helloworld``":
.. code:: c
/* File: test.c */
#include "test.h"
TEST_CASE_DESCRIPTION(helloworld) =
"A description of the helloworld test case.";
enum test_result
tf_helloworld_hello(testcase_state tcs)
{
return (TEST_PASS);
}
enum test_result
tf_helloworld_goodbye(testcase_state tcs)
{
return (TEST_FAIL);
}
Test cases can define their own set up and tear down functions:
.. code:: c
/* File: test.c continued. */
struct helloworld_test { .. state used by the helloworld tests .. };
enum testcase_status
tc_setup_helloworld(testcase_state *tcs)
{
*tcs = ..allocate a struct helloworld_test.. ;
return (TEST_CASE_OK);
}
enum testcase_status
tc_teardown_helloworld(testcase_state tcs)
{
.. deallocate test case state..
return (TEST_CASE_OK);
}
The set up function for a test case will be invoked prior to any of
the functions that are part of the test case. The set up function can
allocate test-specific state, which is then passed to each test function
for its use.
The tear down function for a test case will be invoked after the test
functions in the test case are invoked. This function is responsible for
deallocating the resources allocated by its corresponding set up function.
Building Tests
--------------
Within the `Elftoolchain Project`_'s sources, the ``elftoolchain.test.mk``
rule set handles the process of invoking the `make-test-scaffolding(1)
<mts_>`_ utility and building an test executable.
.. code:: make
# Example Makefile.
TOP= ..path to the top of the elftoolchain source tree..
TEST_SRCS= test.c
.include "$(TOP)/mk/elftoolchain.test.mk"
.. _Elftoolchain Project: http://elftoolchain.sourceforge.net/
Further Reading
===============
- The `test(3) <lib/test.3>`_ manual page.
- The `make-test-scaffolding(1) <bin/make-test-scaffolding.1>`_ manual page.
- `Example code <examples/>`_.
|
