Debian Codegraph @

doc/html/_sources/imap/developer/developer-testing.rst.txt

raw
1 .. _developer-testing:
2
3 ==========================
4 Developer Test Environment
5 ==========================
6
7 This assumes you have your :ref:`basic server running <installing>` and you've made some changes and you want to test them to work out what's going right... or wrong.
8
9 .. _install_cassandane:
10
11 Installing Cassandane
12 =====================
13
14 Cassandane is a Perl-based integration test suite for Cyrus.
15 `Cassandane documentation <https://github.com/cyrusimap/cyrus-imapd/tree/master/cassandane/doc>`_
16 includes information on setting up tests and writing new tests.
17
18 Why "Cassandane"? Wikipedia indicates that Cassandane_ was the name of
19 the consort of King Cyrus the Great of Persia, founder of the Achaemenid
20 Persian Empire. So that's kinda cool.
21
22 .. _Cassandane: https://en.wikipedia.org/wiki/Cassandane
23
24 Install and configure Cassandane
25 --------------------------------
26
27 1. You already have it -- it's in the "cassandane" subdirectory of the cyrus-imapd
28 sources.
29
30 2. Install dependencies
31
32 .. code-block:: bash
33
34 sudo apt-get install libanyevent-perl libtest-unit-perl libconfig-inifiles-perl \
35 libdatetime-perl libbsd-resource-perl libxml-generator-perl \
36 libencode-imaputf7-perl libio-stringy-perl libnews-nntpclient-perl \
37 libfile-chdir-perl libfile-libmagic-perl libnet-server-perl libunix-syslog-perl \
38 libdata-uuid-perl libjson-xs-perl libdata-ical-perl libjson-perl \
39 libdatetime-format-ical-perl libtext-levenshteinxs-perl \
40 libmime-types-perl libdatetime-format-iso8601-perl libcal-dav-perl \
41 libclone-perl libstring-crc32-perl libnet-ldap-server-perl
42
43 The quickest option for the rest is installing via CPAN, but you could build
44 packages using dh-make-perl if that is preferred.
45
46 .. code-block:: bash
47
48 sudo cpan -i AnyEvent Config::IniFiles Data::GUID Digest::CRC File::Slurp IO::File::fcntl IO::Socket::INET6 Net::Server::PreForkSimple News::NNTPClient Plack::Loader Types::Standard Unix::Syslog XML::Generator XML::Simple
49 sudo cpan -i Tie::DataUUID
50 sudo cpan -i XML::Spice
51 sudo cpan -i XML::Fast
52 sudo cpan -i Data::ICal::TimeZone
53 sudo cpan -i Text::VCardFast
54 sudo cpan -i Mail::IMAPTalk
55 sudo cpan -i List::Pairwise
56 sudo cpan -i Convert::Base64
57 sudo cpan -i Net::DAVTalk
58 sudo cpan -i Net::CardDAVTalk
59 sudo cpan -i Net::CalDAVTalk
60 sudo cpan -i Mail::JMAPTalk
61 sudo cpan -i Math::Int64
62 sudo cpan -i Test::Unit
63
64 3. Build Cassandane's binary components
65
66 .. code-block:: bash
67
68 cd /path/to/cyrus-imapd/cassandane
69 make
70
71 4. Copy ``cassandane.ini.example`` to ``cassandane.ini`` in your home directory
72
73 5. Edit ``cassandane.ini`` to set up your cassandane environment.
74
75 * Assuming you configure cyrus with ``--prefix=/usr/cyrus`` (as above), then the defaults are mostly fine
76 * Set ``destdir`` to ``/var/tmp/cyrus``
77 * Add ``[valgrind]`` if you're using it.
78 * Add an ``[imaptest]`` section. For the moment, it may be necessary to
79 suppress the binary tests as they are buggy upstream still.
80
81 .. code-block:: ini
82
83 [imaptest]
84 basedir=/path/to/imaptest/imaptest
85 suppress=append-binary urlauth-binary fetch-binary-mime fetch-binary-mime-qp
86
87 6. Create a ``cyrus`` user and matching group and also add ``cyrus`` to group ``mail``
88
89 .. code-block:: bash
90
91 sudo adduser --system --group cyrus
92 sudo adduser cyrus mail
93
94 7. Give your user account access to sudo as ``cyrus``
95
96 * ``sudo visudo``
97 * add lines like:
98
99 .. code-block::
100
101 Defaults:username rlimit_core=default
102 username ALL = (cyrus) NOPASSWD: ALL
103
104 where "username" is your own username
105
106 8. Make the ``destdir`` directory, as the ``cyrus`` user
107
108 * ``sudo -u cyrus mkdir /var/tmp/cass``
109
110 Install IMAPTest
111 ----------------
112
113 IMAPTest_ is a testing suite which uses libraries from the Dovecot installation.
114
115 1. Fetch and compile Dovecot.
116
117 * Get the latest nightly snapshot from http://dovecot.org/nightly/dovecot-latest.tar.gz
118 * ``./configure && make`` (No need for make install)
119
120 2. Fetch and compile IMAPTest
121
122 * Download http://dovecot.org/nightly/imaptest/imaptest-latest.tar.gz
123 * ``./configure --with-dovecot=../dovecot-2.2 && make`` (No need for make install)
124 * The ``--with-dovecot=<path>`` parameter is used to specify path to Dovecot v2.2 sources' root directory.
125
126 This is not quite the same IMAPTest that CI uses. The CI system uses
127 a docker image, which among other things has Dovecot and IMAPTest already
128 built in so that they don't need to be rebuilt every time CI runs.
129
130 The docker image is built from Dockerfile_ in the cyrus-docker repo. If you
131 want to locally reproduce the same testing that CI runs, you can search it
132 for "dovecot.git" and "imaptest.git" to see how these two components
133 are fetched and built, and do the same yourself. Briefly, Dovecot is built
134 from a known commit id on the upstream repository, whereas IMAPTest is built
135 from the "cyrus" branch of our own fork.
136
137 .. _IMAPTest: http://www.imapwiki.org/ImapTest
138 .. _Dockerfile: https://github.com/cyrusimap/cyrus-docker/blob/master/Debian/Dockerfile
139
140 Rebuild Cyrus for Testing
141 =========================
142
143 Prepare to rebuild by making the source tree shiny and clean as if you've done a brand new checkout. Leave no old artifacts lying around!
144
145 .. code-block:: bash
146
147 cd /path/to/cyrus-imapd
148 make clean
149 git clean -f -x -d
150 autoreconf -v -i
151
152 .. warning::
153 Apply caution! The ``git clean`` removes anything that's a build product, but also anything it doesn't know about: which may include your new source files you haven't added yet.
154
155 Set the compile flags for testing and debugging. It may be of use to also add ``--std=gnu99`` here. That does TONS of warnings, and ``-g`` enables debug mode.
156
157 .. code-block:: bash
158
159 CFLAGS="-g -fPIC -W -Wall -Wextra -Werror"
160
161 Configure the environment.
162
163 .. code-block:: bash
164
165 ./configure --prefix=/usr/cyrus --with-cyrus-prefix=/usr/cyrus \
166 --enable-autocreate --enable-http --enable-unit-tests \
167 --enable-replication --enable-nntp --enable-murder \
168 --enable-idled --enable-xapian --enable-calalarmd \
169 --enable-backup
170
171 make lex-fix # you need this if compile fails with errors from sieve/sieve.c
172
173 And finally, make it.
174
175 If you're testing across versions, the binsymlinks is necessary as older Cyrus doesn't have the binaries in the new locations. This uses the default install path of ``/usr/cyrus/``. It can be useful to also have ``/usr/cyrus25``, ``/usr/cyrus24``, etc, if you're testing with older versions as well.
176
177 .. code-block:: bash
178
179 make -j16 && make -j16 check
180 sudo make install
181 sudo make install-binsymlinks
182 sudo cp tools/mkimap /usr/cyrus/bin/mkimap
183
184
185 Running the tests
186 =================
187
188 Cassandane internals need to run as the ``cyrus`` user, but if you gave
189 yourself passwordless sudo access as instructed above, then Cassandane will
190 take care of switching to the ``cyrus`` user for you. In which case, just run
191 it as yourself.
192
193 If you didn't give yourself this access, you will first need to become the
194 ``cyrus`` user by some other means, and then run it from there.
195
196 .. code-block:: bash
197
198 cd /path/to/cyrus-imapd/cassandane
199 ./testrunner.pl
200
201 Do not run it as root.
202
203 Debugging and stacktraces
204 =========================
205
206 Check out the guide to :ref:`running Cyrus components under gdb <faqs-o-gdb>`.
207
208 In the event of a crash, here's how to :ref:`generate a stacktrace <faqs-o-coredump>`.
209
210 Core dumps will be owned by the ``cyrus`` user, but your source tree will
211 probably be owned by yourself. Copy the core dump somewhere convenient,
212 change the ownership to yourself, and then you can open the core file in
213 gdb for examination.
214
215 Tips and Tricks
216 ===============
217
218 Read the script to see other options. If you're having problems, add more
219 ``-v`` options to the testrunner to get more info out.
220
221 **Looking for memory leaks?** Run with --valgrind to use valgrind (if it's
222 installed). It is slower, which is why it doesn't need to be always used.
223
224 Running with -v -v is very noisy, but gives a lot more data. For example: all
225 IMAP telemetry.
226
227 Also helpful to run ``sudo tail -f /var/log/syslog``, and examine
228 /var/tmp/cass as ``cyrus`` to examine log files and disk structures for
229 failed tests.