← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/testing.txt

Fixed as per Martin's review.

* doc/developers/testing.txt: 
Add a shelli-like tests section.

* bzrlib/tests/test_script.py:
Update scripts for new prefixes and fix echo tests.

* bzrlib/tests/script.py: Move doc to doc/developers/testing.txt.
(_script_to_commands): Commands are prefixed by '$', expected
output are not prefixed anymore.
(ScriptRunner.do_echo): Put spaces between arguments.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/testing.txt
201
201
  __ http://docs.python.org/lib/module-doctest.html
202
202
 
203
203
 
 
204
Shell-like tests
 
205
~~~~~~~~~~~~~~~~
 
206
 
 
207
``bzrlib/tests/script.py`` allows users to write tests in a syntax very close to a shell session,
 
208
using a restricted and limited set of commands that should be enough to mimic
 
209
most of the behaviours.
 
210
 
 
211
A script is a set of commands, each command is composed of:
 
212
 
 
213
 * one mandatory command line,
 
214
 * one optional set of input lines to feed the command,
 
215
 * one optional set of output expected lines,
 
216
 * one optional set of error expected lines.
 
217
 
 
218
Input, output and error lines can be specified in any order.
 
219
 
 
220
Except for the expected output, all lines start with a special
 
221
string (based on their origin when used under a Unix shell):
 
222
 
 
223
 * '$ ' for the command,
 
224
 * '<' for input,
 
225
 * nothing for output,
 
226
 * '2>' for errors,
 
227
 
 
228
Comments can be added anywhere, they start with '#' and end with
 
229
the line.
 
230
 
 
231
The execution stops as soon as an expected output or an expected error is not
 
232
matched. 
 
233
 
 
234
When no output is specified, any ouput from the command is accepted
 
235
and execution continue. 
 
236
 
 
237
If an error occurs and no expected error is specified, the execution stops.
 
238
 
 
239
An error is defined by a returned status different from zero, not by the
 
240
presence of text on the error stream.
 
241
 
 
242
The matching is done on a full string comparison basis unless '...' is used, in
 
243
which case expected output/errors can be less precise.
 
244
 
 
245
Examples:
 
246
 
 
247
The following will succeeds only if 'bzr add' outputs 'adding file'::
 
248
 
 
249
  $ bzr add file
 
250
  >adding file
 
251
 
 
252
If you want the command to succeed for any output, just use::
 
253
 
 
254
  $ bzr add file
 
255
 
 
256
The following will stop with an error::
 
257
 
 
258
  $ bzr not-a-command
 
259
 
 
260
If you want it to succeed, use::
 
261
 
 
262
  $ bzr not-a-command
 
263
  2> bzr: ERROR: unknown command "not-a-command"
 
264
 
 
265
You can use ellipsis (...) to replace any piece of text you don't want to be
 
266
matched exactly::
 
267
 
 
268
  $ bzr branch not-a-branch
 
269
  2>bzr: ERROR: Not a branch...not-a-branch/".
 
270
 
 
271
This can be used to ignore entire lines too::
 
272
 
 
273
  $ cat
 
274
  <first line
 
275
  <second line
 
276
  <third line
 
277
  # And here we explain that surprising fourth line
 
278
  <fourth line
 
279
  <last line
 
280
  >first line
 
281
  >...
 
282
  >last line
 
283
 
 
284
You can check the content of a file with cat::
 
285
 
 
286
  $ cat <file
 
287
  >expected content
 
288
 
 
289
You can also check the existence of a file with cat, the following will fail if
 
290
the file doesn't exist::
 
291
 
 
292
  $ cat file
 
293
 
 
294
 
 
295
 
204
296
.. Effort tests
205
297
.. ~~~~~~~~~~~~
206
298