14
14
test before writing the code.
16
16
In general, you can test at either the command-line level or the
17
internal API level. See Writing Tests below for more detail.
17
internal API level. Choose whichever is appropriate: if adding a
18
new command, or a new command option, then call through run_bzr().
19
It is not necessary to do both. Tests that test the command line level
20
are appropriate for checking the UI behaves well - bug fixes and
21
core improvements should be tested closer to the code that is doing the
22
work. Command line level tests should be placed in 'blackbox.py'.
19
24
* Try to practice Test-Driven Development. before fixing a bug, write a
20
25
test case so that it does not regress. Similarly for adding a new
236
In general tests should be placed in a file named test_FOO.py where
241
In general tests should be placed in a file named testFOO.py where
237
242
FOO is the logical thing under test. That file should be placed in the
238
243
tests subdirectory under the package being tested.
240
For example, tests for merge3 in bzrlib belong in bzrlib/tests/test_merge3.py.
241
See bzrlib/selftest/test_sampler.py for a template test script.
243
Tests can be written for the UI or for individual areas of the library.
244
Choose whichever is appropriate: if adding a new command, or a new command
245
option, then you should be writing a UI test. If you are both adding UI
246
functionality and library functionality, you will want to write tests for
247
both the UI and the core behaviours. We call UI tests 'blackbox' tests
248
and they are found in bzrlib/tests/blackbox/*.py.
250
When writing blackbox tests please honour the following conventions:
252
1. Place the tests for the command 'name' in
253
bzrlib/tests/blackbox/test_name.py. This makes it easy for developers
254
to locate the test script for a faulty command.
256
2. Use the 'self.run_bzr("name")' utility function to invoke the command
257
rather than running bzr in a subprocess or invoking the
258
cmd_object.run() method directly. This is a lot faster than
259
subprocesses and generates the same logging output as running it in a
260
subprocess (which invoking the method directly does not).
262
3. Only test the one command in a single test script. Use the bzrlib
263
library when setting up tests and when evaluating the side-effects of
264
the command. We do this so that the library api has continual pressure
265
on it to be as functional as the command line in a simple manner, and
266
to isolate knock-on effects throughout the blackbox test suite when a
267
command changes it name or signature. Ideally only the tests for a
268
given command are affected when a given command is changed.
245
For example, tests for merge3 in bzrlib belong in bzrlib/tests/testmerge3.py.
246
See bzrlib/selftest/testsampler.py for a template test script.
272
251
Currently, bzr selftest is used to invoke tests.
273
252
You can provide a pattern argument to run a subset. For example,
274
to run just the blackbox tests, run::
253
to run just the whitebox tests, run::
276
./bzr selftest -v blackbox
255
bzr selftest -v whitebox
279
258
Errors and exceptions
294
273
indexes into the branch's revision history.
300
The ``Transport`` layer handles access to local or remote directories.
301
Each Transport object acts like a logical connection to a particular
302
directory, and it allows various operations on files within it. You can
303
*clone* a transport to get a new Transport connected to a subdirectory or
306
Transports are not used for access to the working tree. At present
307
working trees are always local and they are accessed through the regular
308
Python file io mechanisms.
313
Transports work in URLs. Take note that URLs are by definition only
314
ASCII - the decision of how to encode a Unicode string into a URL must be
315
taken at a higher level, typically in the Store. (Note that Stores also
316
escape filenames which cannot be safely stored on all filesystems, but
317
this is a different level.)
319
The main reason for this is that it's not possible to safely roundtrip a
320
URL into Unicode and then back into the same URL. The URL standard
321
gives a way to represent non-ASCII bytes in ASCII (as %-escapes), but
322
doesn't say how those bytes represent non-ASCII characters. (They're not
323
guaranteed to be UTF-8 -- that is common but doesn't happen everywhere.)
325
For example if the user enters the url ``http://example/%e0`` there's no
326
way to tell whether that character represents "latin small letter a with
327
grave" in iso-8859-1, or "latin small letter r with acute" in iso-8859-2
328
or malformed UTF-8. So we can't convert their URL to Unicode reliably.
330
Equally problematic if we're given a url-like string containing non-ascii
331
characters (such as the accented a) we can't be sure how to convert that
332
to the correct URL, because we don't know what encoding the server expects
333
for those characters. (Although this is not totally reliable we might still
334
accept these and assume they should be put into UTF-8.)
336
A similar edge case is that the url ``http://foo/sweet%2Fsour" contains
337
one directory component whose name is "sweet/sour". The escaped slash is
338
not a directory separator. If we try to convert URLs to regular Unicode
339
paths this information will be lost.
341
This implies that Transports must natively deal with URLs; for simplicity
342
they *only* deal with URLs and conversion of other strings to URLs is done
343
elsewhere. Information they return, such as from ``list_dir``, is also in
344
the form of URL components.
347
276
Merge/review process
348
277
====================
added
removed
HACKING
