source: project/wiki/eggref/4/salmonella @ 25854

Last change on this file since 25854 was 25854, checked in by Mario Domenech Goulart, 9 years ago

salmonella (wiki): headings can't start with numbers

File size: 13.8 KB
Line 
1[[tags: egg salmonella]]
2
3== salmonella
4
5[[toc:]]
6
7=== Introduction
8
9Salmonella is a set of tools to test CHICKEN eggs.  Here's a brief
10summary of features:
11
12* very light on dependencies (none at the moment)
13* paralellizable ({{salmonella-epidemy}})
14* can be run with or without Internet access
15
16Note: starting on version 2.0, salmonella is a rewrite of the
17salmonella 1.x series, which was available since CHICKEN 2.x.  The
18documentation for the 1.x series is still available at
19[[http://wiki.call-cc.org/egg/salmonella-1.x|http://wiki.call-cc.org/egg/salmonella-1.x]].
20
21
22=== Author
23
24[[http://wiki.call-cc.org/users/mario-domenech-goulart|Mario Domenech Goulart]]
25
26
27=== Repository
28
29salmonella is hosted on [[http://github.com|github]]:
30[[https://github.com/mario-goulart/salmonella|https://github.com/mario-goulart/salmonella]]
31
32
33=== Tools
34
35This egg provides some command line tools.  The next sections describe
36each of them.
37
38
39
40==== salmonella
41
42This is the core tool for testing eggs.  {{salmonella}} can perform
43the following tests:
44
45* installation of eggs
46* dependencies verification
47* {{.meta}} file consistency check
48* egg tests execution
49* general egg consistency (i.e., can be used as an ''egg lint'' to
50avoid common mistakes when publishing a new egg or a new egg
51version)
52
53{{salmonella}} generates a sexpr-based log file as output.  That file
54can be used by tools like
55[[/egg/salmonella-html-report|salmonella-html-report]] to generate a
56pretty output in HTML.
57
58When executing, salmonella prints some basic information on the
59standard output.  Detailed information can be viewed with the
60aforementioned [[/egg/salmonella-html-report|salmonella-html-report]]
61or with {{salmonella-log-viewer}}, a tool which is provided by this
62egg. {{salmonella-log-viewer}} parses the log file generated by
63salmonella and formats the data on the standard output.
64
65===== Command line options
66
67Here's the output of {{salmonella -h}} with an explanation for each
68command line option:
69
70  salmonella [ -h | --help ]
71  salmonella <options> eggs
72
73  <options>:
74  --log-file=<logfile>
75      The name for the log file to be generated by salmonella
76      (default=salmonella.log).
77
78  --chicken-installation-prefix=<prefix dir>
79      If you want to test eggs using a chicken installed on a certain directory,
80      you can use this option (it should point to the same directory as given to
81      `PREFIX' when installing CHICKEN). If omitted, salmonella uses CHICKEN
82      tools from the system PATH variable.
83
84  --chicken-install-args=<install args>
85      This option can be used customize chicken-install's arguments.  You can
86      use <repo> to indicate where you want the actual repository directory
87      to be replaced by salmonella.
88
89  --eggs-source-dir=<eggs dir>
90      By default, salmonella fetches eggs from the egg server.  If you have a
91      local copy of eggs code, you can use this option to point to the directory
92      where they are located.
93
94  --eggs-doc-dir=<doc dir>
95      By default, salmonella checks if documentation for eggs exist by accessing
96      the CHICKEN wiki.  If you have a local copy of the wiki documentation for
97      eggs, you can use this option to point to the directory where they can be
98      found.
99
100  --keep-repo
101      For each egg that salmonella tests, it sets the egg installation repository
102      empty and removes it at the end of its execution.  This option makes
103      salmonella keep the egg installation repository after testing each egg and
104      after finishing its execution.  This option can save a lot of time when
105      testing several eggs, at the cost of potentially making salmonella unable
106      to catch dependencies problems.
107
108  --skip-eggs=<comma-separated list of eggs to skip>
109      A comma-separated list of eggs to be skipped.
110
111  --this-egg
112      To be used from withing the egg source directory to check for common errors
113      before releasing an egg or a new egg version.
114
115  --repo-dir=<path to repo dir to be used>
116      Alternative location for the egg installation directory used by salmonella.
117      By default, salmonella generates a `salmonella-tmp-xxxxx' directory in the
118      current directory.  This option can be useful when used with `--keep-repo'
119      to reuse egg installation repositories for several salmonella executions.
120
121  --verbosity=<number>
122      A number to indicate salmonella's verbosity level.  0 means practically
123      silent. 1 is mostly silent and 2 (default) prints some useful information
124      while salmonella is running.
125
126
127===== Some quick tips by example
128
129Simplest case: testing eggs using the remote egg server and the
130chicken tools ({{chicken-install}} and {{csi}}) in the system {{PATH}}
131
132  $ salmonella big-chicken slice
133
134
135You can test all the available eggs using one of the following
136approaches:
137
1381. If you have CHICKEN >= 4.7.2:
139
140  $ salmonella `chicken-install -list`
141
142
1432. If you don't have CHICKEN >= 4.7.2:
144
145  $ salmonella `wget http://code.call-cc.org/cgi-bin/henrietta.cgi?list=1 -q -O -`
146
147
148If you don't want to test some specific eggs, you can skip them:
149
150  $ salmonella --skip-eggs=macosx,hfs+ `chicken-install -list`
151
152
153You can tell salmonella to use a specific CHICKEN version:
154
155  $ salmonella --chicken-installation-prefix=/usr/local/chicken-4.7.3 big-chicken slice
156
157
158Not cleaning the egg installation repository after installing each egg
159may significantly speed up the salmonella execution time (the default
160behavior is to set the egg installation repository empty after testing
161each egg):
162
163  $ salmonella --keep-repo big-chicken slice
164
165warning: if you use --keep-repo, salmonella will not be able to catch
166dependencies problems.
167
168
169If you want to reuse the same egg installation repository for multiple
170salmonella runs, you can provide a specific directory:
171
172  $ salmonella --repo-dir=my-repo --keep-repo big-chicken slice
173
174
175By default, salmonella generates a log file named {{salmonella.log}} in
176the current directory.  You can change that by using the {{--log-file}}
177command line option:
178
179  $ salmonella --log-file=my-log-file.log big-chicken slice
180
181
182====== Using salmonella as an egg lint tool
183
184Suppose you are working on a new egg and you want to check if it is
185working ok before releasing it (or a new version).  You can use
186salmonella to check it:
187
188  $ cd my-egg    # where your egg code is stored
189  $ salmonella --this-egg
190
191
192
193==== salmonella-log-viewer
194
195This tool can be used to turn salmonella log files into something
196readable on the standard output.
197
198Just provide a salmonella log file as argument to
199{{salmonella-log-viewer}}:
200
201    $ salmonella-log-viewer salmonella.log
202
203Alternatively, you can use
204[[/egg/salmonella-html-report|salmonella-html-report]] for a prettier
205and more complete format.
206
207
208
209==== salmonella-epidemy
210
211{{salmonella-epidemy}} can be used to run multiple salmonella
212instances in parallel.  It can be handy when you have a multi-core
213machine and you want to make use of all cores, for example.  The
214command line options are basically the same as for {{salmonella}},
215plus a {{--instances=<number>}} to indicate how many {{salmonella}}
216instances you want to run in parallel.
217
218This tool can significantly speed up salmonella execution times on
219multi-core machines.
220
221Usage example:
222
223  $ salmonella-epidemy --instances=2 big-chicken slice spiffy amb
224
225
226
227==== salmonella-log-merger
228
229This tool simply puts more than one salmonella log into a single one,
230so it can be used by tools like {{salmonella-log-viewer}} and
231[[/egg/salmonella-html-report|salmonella-html-report]].
232
233
234Usage example:
235
236  $ salmonella-log-merger --log-file=full.log file1.log file2.log
237
238
239
240==== Log file format
241
242The command line tool writes a log file which contains records in the
243following format:
244
245 (<egg> <action> <status> <message> <duration>)
246
247
248===== <egg>
249
250Can be either a symbol that indicates the egg-name or {{#f}} to
251indicate the {{start}} and {{end}} actions (logged when salmonella is
252started and when it finishes testing, respectively).
253
254===== <action>
255
256A symbol to indicate the action that was executed.  Can be one of the
257following values:
258
259* {{start}}: starting salmonella
260* {{fetch}}: fetching egg
261* {{install}}: installing egg
262* {{test}}: testing egg
263* {{end}}: salmonella has finished
264
265===== <status>
266
267A numeric value indicating the exit status of the executed action.
268When the action is {{test}} and {{status}} is {{-1}}, it means that
269the egg has no tests.
270
271
272===== <message>
273
274The output generated by the commands executed to perform {{<action>}}.
275A string.
276
277
278===== <duration>
279
280The time (in seconds) that was taken to execute {{<action>}}.
281
282For the {{start}} and {{end}} actions, the value is the seconds since
283epoch, so the total salmonella execution time can be determined by
284subtracting the start time from the end time.
285
286
287=== Modules
288
289Salmonella provides two modules:
290
291; {{salmonella}}: the core salmonella functionality and basic data strucuture for logs ({{report}} records)
292
293; {{salmonella-log-parser}}: provides procedures to access log files and compute simple statistics regarding log file data.
294
295
296==== salmonella
297
298===== report
299<record>(report egg action status message duration)</record>
300<procedure>make-report</procedure>
301<procedure>report?</procedure>
302<procedure>report-egg</procedure>
303<procedure>report-action</procedure>
304<procedure>report-status</procedure>
305<procedure>report-message</procedure>
306<procedure>report-duration</procedure>
307<procedure>report-egg-set!</procedure>
308<procedure>report-action-set!</procedure>
309<procedure>report-status-set!</procedure>
310<procedure>report-message-set!</procedure>
311<procedure>report-duration-set!</procedure>
312
313{{report}} objects.  Each log file registry is represented by a
314{{report}} object (serialized as a list).
315
316===== report->list
317<procedure>(report->list report)</procedure>
318
319Convert a {{report}} object to a list.
320
321
322===== log!
323<procedure>(log! report log-file)</procedure>
324
325Print the {{report}} representation to {{log-file}}.
326
327
328===== make-salmonella
329<procedure>(make-salmonella tmp-dir #!key chicken-installation-prefix chicken-install-args eggs-source-dir eggs-doc-dir this-egg?)</procedure>
330
331The salmonella maker.  Returns a procedure that receives symbols
332(''methods'') to indicate the actions to be performed.  The available
333methods are (example considering a {{salmonella}} object returned by
334{{make-salmonella}}):
335
336====== {{(salmonella 'init-repo!)}}
337
338====== {{(salmonella 'clear-repo!)}}
339
340====== {{(salmonella 'fetch <egg>)}}
341
342====== {{(salmonella 'install <egg>)}}
343
344====== {{(salmonella 'test <egg>)}}
345
346====== {{(salmonella 'check-version <egg>)}}
347
348====== {{(salmonella 'env-info)}}
349
350====== {{(salmonella 'meta-data <egg>)}}
351
352====== {{(salmonella 'check-dependencies <egg> <meta data>)}}
353
354====== {{(salmonella 'check-category <egg> <meta data>)}}
355
356====== {{(salmonella 'check-license <egg> <meta data>)}}
357
358====== {{(salmonella 'check-author <egg> <meta data>)}}
359
360====== {{(salmonella 'check-doc <egg>)}}
361
362
363
364==== salmonella-log-parser
365
366===== Reading
367
368<procedure>(read-log-file filename)</procedure>
369
370Reads the log file {{filename}} and returns a list of report records.
371
372===== {{fetch}} action
373
374====== fetch-status
375<procedure>(fetch-status egg log)</procedure>
376
377====== fetch-message
378<procedure>(fetch-message egg log)</procedure>
379
380====== fetch-duration
381<procedure>(fetch-duration egg log)</procedure>
382
383
384
385===== {{install}} action
386
387====== install-status
388<procedure>(install-status egg log)</procedure>
389
390====== install-message
391<procedure>(install-message egg log)</procedure>
392
393====== install-duration
394<procedure>(install-duration egg log)</procedure>
395
396
397
398===== {{check-version}} action
399
400====== check-version-status
401<procedure>(check-version-status egg log)</procedure>
402
403====== check-version-message
404<procedure>(check-version-message egg log)</procedure>
405
406====== egg-version
407<procedure>(egg-version egg log)</procedure>
408
409====== check-version-ok?
410<procedure>(check-version-ok? egg log)</procedure>
411
412
413===== {{test}} action
414
415====== test-status
416<procedure>(test-status egg log)</procedure>
417
418====== test-message
419<procedure>(test-message egg log)</procedure>
420
421====== test-duration
422<procedure>(test-duration egg log)</procedure>
423
424====== has-test?
425<procedure>(has-test? egg log)</procedure>
426
427
428===== {{meta-data}} action
429
430====== meta-data
431<procedure>(meta-data egg log)</procedure>
432
433====== egg-dependencies
434<procedure>(egg-dependencies egg log)</procedure>
435
436====== egg-license
437<procedure>(egg-license egg log #!key with-test-dependencies? with-versions?)</procedure>
438
439
440
441===== {{check-doc}} action
442
443====== doc-exists?
444<procedure>(doc-exists? egg log)</procedure>
445
446
447
448===== {{start}} & {{end}} actions
449
450====== start-time
451<procedure>(start-time log)</procedure>
452
453====== end-time
454<procedure>(end-time log)</procedure>
455
456====== total-time
457<procedure>(total-time log)</procedure>
458
459====== salmonella-info
460<procedure>(salmonella-info log)</procedure>
461
462
463
464===== Statistics
465
466====== count-install-ok
467<procedure>(count-install-ok log)</procedure>
468
469====== count-install-fail
470<procedure>(count-install-fail log)</procedure>
471
472====== count-test-ok
473<procedure>(count-test-ok log)</procedure>
474
475====== count-test-fail
476<procedure>(count-test-fail log)</procedure>
477
478====== count-no-test
479<procedure>(count-no-test log)</procedure>
480
481====== count-total-eggs
482<procedure>(count-total-eggs log #!key with-skipped?)</procedure>
483
484====== count-documented
485<procedure>(count-documented log)</procedure>
486
487====== count-undocumented
488<procedure>(count-undocumented log)</procedure>
489
490
491===== Miscelaneous
492
493====== prettify-time
494<procedure>(prettify-time time)</procedure>
495
496====== sort-eggs
497<procedure>(sort-eggs eggs)</procedure>
498
499====== log-eggs
500<procedure>(log-eggs log)</procedure>
501
502====== log-skipped-eggs
503<procedure>(log-skipped-eggs log)</procedure>
504
505
506
507=== Environment variables
508
509When running, salmonella sets the {{SALMONELLA_RUNNING}} environment
510variable.  If you need to check if your tests code is being run by
511salmonella, this variable can be used.
512
513
514
515=== License
516
517BSD
518
519
520
521=== Version history
522
523==== Version 2.1
524
525* Hours, minutes and seconds formatted with exact numbers ({{prettify-time}})
526
527
528==== Version 2.0
529
530* Rewrite of the 1.x version
Note: See TracBrowser for help on using the repository browser.