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
|
eCryptfs Test Suite
Follow these steps when adding a new test:
NOTE: This guide primarily focuses on kernel test cases. If you're writing a
userspace test case, substitute all mentions of tests/kernel/ with
tests/userspace/ and pay attention to any other kernel-specific
instructions.
1) Pick a name for the new test. This guide will be using the test case name
"mmap-close", but you'll need to substitute in the name of your own test
case.
If it is a reproducer for a bug, consider using the bug tracker and bug
number. For example, lp-469664 is the test for
https://launchpad.net/bugs/469664.
Otherwise, pick a short, but descriptive, name for the test. For example,
trunc-file is the name of a test that excercises file truncation.
2) Copy the skeleton test script to the appropriate test directory. In this
guide, we're creating a kernel test so copy it to the tests/kernel/
directory:
---
$ cp tests/new.sh tests/kernel/mmap-close.sh
---
3) Update the information in the comments at the top of your new test case.
Specifically, the words below in all caps need to be modified:
---
# FILENAME: Test for BUG_URL|LIST_URL|DESCRIPTION
# Author: FIRST LAST <USER@DOMAIN>
#
# Copyright (C) YEAR COPYRIGHT_HOLDER
---
In this case, we end up with something along these lines:
---
# mmap-close.sh : Test for catching regressions when applications do this:
#
# open() -> mmap() -> *close()* -> dirty mapping -> munmap()
#
# Past regressions have been reported in these bugs:
#
# https://bugs.launchpad.net/bugs/870326
# https://bugs.launchpad.net/bugs/1047261
# Author: Tyler Hicks <tyhicks@canonical.com>
---
4) Now you can start writing the test. You'll probably need to set up a basic
eCryptfs mount. You can do that by pasting in these sequence of helper
functions after the "# TEST" line in your new test case:
---
# TEST
etl_add_keys || exit
etl_lmount || exit
etl_mount_i || exit
test_dir=$(etl_create_test_dir) || exit
---
This is probably a good time to introduce the library of helper functions.
It can be found in tests/lib/etl_funcs.sh. Take a look at the functions
available and feel free to add any new functions if you feel like they would
benefit multiple test cases.
5) At this point, we have a lower filesystem mounted, an eCryptfs filesystem
mounted on top of it, and a test directory created inside of the eCryptfs
mount. We'll need to properly tear all of that down when the test case
exits, so update the test_cleanup() function accordingly:
---
test_cleanup()
{
etl_remove_test_dir $test_dir
etl_umount
etl_lumount
etl_unlink_keys
exit $rc
}
trap test_cleanup 0 1 2 3 15
---
6) Now we are ready to implement the actual test. If it is simple enough to do
with basic bash commands, as is the case for lp-469664.sh, simply add those
commands and skip to step 11).
If you need to write a C (or possibly Python) program, proceed to step 7).
7) Create a directory to hold the C source file(s) and any other data files
that you'll need. It should be named after your test case.
---
$ mkdir tests/kernel/mmap-close/
---
8) Create a new file, inside that directory, called test.c and implement the
test case in the new file. Be sure to add a header, including the GPLv2
text, similar to what is in the example test script that was modified in
step 3).
9) Update the test script (mmap-close.sh) to call the test binary after the
environment setup stage:
---
${test_script_dir}/mmap-close/test || exit
---
10) Add a line to tests/kernel/Makefile.am to build test.c:
---
mmap_close_test_SOURCES = mmap-close/test.c
---
And add the test binary to the noinst_PROGRAMS list:
---
noinst_PROGRAMS = directory-concurrent/test \
...
mmap-close/test \
...
trunc-file/test
---
11) Add a line to tests/kernel/Makefile.am to place the new test script in the
dist_noinst_SCRIPTS list:
---
dist_noinst_SCRIPTS = directory-concurrent.sh \
...
mmap-close.sh \
...
trunc-file.sh
---
12) Finally, add the new test script to the appropriate list in
tests/kernel/tests.rc. There are only two lists - safe and destructive.
Safe means that the tests aren't likely to cause a kernel oops or other
unrecoverable error. Everything else goes in the destructive list.
This was a quick introduction into creating a new test case. Look at other
existing test cases for more examples.
|
