← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/testing.txt

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2009-09-18 09:49:39 UTC
  • mfrom: (4702.1.1 integration2)
  • Revision ID: pqm@pqm.ubuntu.com-20090918094939-xmi0ihhvas4qlks9
(vila) Introduce shell-like tests feature

Show diffs side-by-side

added added

removed removed

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