You are looking at historical revision 27377 of this page. It may differ significantly from its current revision.


  1. salmonella
    1. Introduction
    2. Author
    3. Repository
    4. Tools
      1. salmonella
        1. Command line options
        2. Some quick tips by example
          1. Using salmonella as an egg lint tool
      2. salmonella-log-viewer
      3. salmonella-epidemy
      4. salmonella-log-merger
      5. Log file format
        1. <egg>
        2. <action>
        3. <status>
        4. <message>
        5. <duration>
    5. Modules
      1. salmonella
        1. report
        2. report->list
        3. log!
        4. make-salmonella
          1. (salmonella 'init-repo!)
          2. (salmonella 'clear-repo!)
          3. (salmonella 'fetch <egg>)
          4. (salmonella 'install <egg>)
          5. (salmonella 'test <egg>)
          6. (salmonella 'check-version <egg>)
          7. (salmonella 'env-info)
          8. (salmonella 'meta-data <egg>)
          9. (salmonella 'check-dependencies <egg> <meta data>)
          10. (salmonella 'check-category <egg> <meta data>)
          11. (salmonella 'check-license <egg> <meta data>)
          12. (salmonella 'check-author <egg> <meta data>)
          13. (salmonella 'check-doc <egg>)
      2. salmonella-log-parser
        1. Reading
        2. fetch action
          1. fetch-status
          2. fetch-message
          3. fetch-duration
        3. install action
          1. install-status
          2. install-message
          3. install-duration
        4. check-version action
          1. check-version-status
          2. check-version-message
          3. egg-version
          4. check-version-ok?
        5. test action
          1. test-status
          2. test-message
          3. test-duration
          4. has-test?
        6. meta-data action
          1. meta-data
          2. egg-dependencies
          3. egg-license
        7. check-doc action
          1. doc-exists?
        8. start & end actions
          1. start-time
          2. end-time
          3. total-time
          4. salmonella-info
        9. Statistics
          1. count-install-ok
          2. count-install-fail
          3. count-test-ok
          4. count-test-fail
          5. count-no-test
          6. count-total-eggs
          7. count-documented
          8. count-undocumented
        10. Miscelaneous
          1. prettify-time
          2. sort-eggs
          3. log-eggs
          4. log-skipped-eggs
    6. Environment variables
    7. License
    8. Version history
      1. Version 2.6
      2. Version 2.5
      3. Version 2.4
      4. Version 2.3
      5. Version 2.2
      6. Version 2.1
      7. Version 2.0


Salmonella is a set of tools to test CHICKEN eggs. Here's a brief summary of features:

Note: starting on version 2.0, salmonella is a rewrite of the salmonella 1.x series, which was available since CHICKEN 2.x. The documentation for the 1.x series is still available at


Mario Domenech Goulart


salmonella is hosted on github:


This egg provides some command line tools. The next sections describe each of them.


This is the core tool for testing eggs. salmonella can perform the following tests:

salmonella generates a sexpr-based log file as output. That file can be used by tools like salmonella-html-report to generate a pretty output in HTML.

When executing, salmonella prints some basic information on the standard output. Detailed information can be viewed with the aforementioned salmonella-html-report or with salmonella-log-viewer, a tool which is provided by this egg. salmonella-log-viewer parses the log file generated by salmonella and formats the data on the standard output.

Command line options

Here's the output of salmonella -h with an explanation for each command line option:

 salmonella [ -h | --help ]
 salmonella <options> eggs
     The name for the log file to be generated by salmonella
 --chicken-installation-prefix=<prefix dir>
     If you want to test eggs using a chicken installed on a certain directory,
     you can use this option (it should point to the same directory as given to
     `PREFIX' when installing CHICKEN). If omitted, salmonella uses CHICKEN
     tools from the system PATH variable.
 --chicken-install-args=<install args>
     This option can be used customize chicken-install's arguments.  You can
     use <repo> to indicate where you want the actual repository directory
     to be replaced by salmonella.
 --eggs-source-dir=<eggs dir>
     By default, salmonella fetches eggs from the egg server.  If you have a
     local copy of eggs code, you can use this option to point to the directory
     where they are located.
 --eggs-doc-dir=<doc dir>
     By default, salmonella checks if documentation for eggs exist by accessing
     the CHICKEN wiki.  If you have a local copy of the wiki documentation for
     eggs, you can use this option to point to the directory where they can be
     For each egg that salmonella tests, it sets the egg installation repository
     empty and removes it at the end of its execution.  This option makes
     salmonella keep the egg installation repository after testing each egg and
     after finishing its execution.  This option can save a lot of time when
     testing several eggs, at the cost of potentially making salmonella unable
     to catch dependencies problems.
 --skip-eggs=<comma-separated list of eggs to skip>
     A comma-separated list of eggs to be skipped.
 --repo-dir=<path to repo dir to be used>
     Alternative location for the egg installation directory used by salmonella.
     By default, salmonella generates a `salmonella-tmp-xxxxx' directory in the
     current directory.  This option can be useful when used with `--keep-repo'
     to reuse egg installation repositories for several salmonella executions.
     A number to indicate salmonella's verbosity level.  0 means practically
     silent. 1 is mostly silent and 2 (default) prints some useful information
     while salmonella is running.
Some quick tips by example

Simplest case: testing eggs using the remote egg server and the chicken tools (chicken-install and csi) in the system PATH

 $ salmonella big-chicken slice

You can test all the available eggs using one of the following approaches:

1. If you have CHICKEN >= 4.7.2:

 $ salmonella `chicken-install -list`

2. If you don't have CHICKEN >= 4.7.2:

 $ salmonella `wget -q -O -`

If you don't want to test some specific eggs, you can skip them:

 $ salmonella --skip-eggs=macosx,hfs+ `chicken-install -list`

You can tell salmonella to use a specific CHICKEN version:

 $ salmonella --chicken-installation-prefix=/usr/local/chicken-4.7.3 big-chicken slice

Not cleaning the egg installation repository after installing each egg may significantly speed up the salmonella execution time (the default behavior is to set the egg installation repository empty after testing each egg):

 $ salmonella --keep-repo big-chicken slice

warning: if you use --keep-repo, salmonella will not be able to catch dependencies problems.

If you want to reuse the same egg installation repository for multiple salmonella runs, you can provide a specific directory:

 $ salmonella --repo-dir=my-repo --keep-repo big-chicken slice

By default, salmonella generates a log file named salmonella.log in the current directory. You can change that by using the --log-file command line option:

 $ salmonella --log-file=my-log-file.log big-chicken slice
Using salmonella as an egg lint tool

Suppose you are working on a new egg and you want to check if it is working ok before releasing it (or a new version). You can use salmonella to check it:

 $ cd my-egg    # where your egg code is stored
 $ salmonella


This tool can be used to turn salmonella log files into something readable on the standard output.

Just provide a salmonella log file as argument to salmonella-log-viewer:

   $ salmonella-log-viewer salmonella.log

Alternatively, you can use salmonella-html-report for a prettier and more complete format.


salmonella-epidemy can be used to run multiple salmonella instances in parallel. It can be handy when you have a multi-core machine and you want to make use of all cores, for example. The command line options are basically the same as for salmonella, plus a --instances=<number> to indicate how many salmonella instances you want to run in parallel.

This tool can significantly speed up salmonella execution times on multi-core machines.

Usage example:

 $ salmonella-epidemy --instances=2 big-chicken slice spiffy amb


This tool simply puts more than one salmonella log into a single one, so it can be used by tools like salmonella-log-viewer and salmonella-html-report.

Usage example:

 $ salmonella-log-merger --log-file=full.log file1.log file2.log

Log file format

The command line tool writes a log file which contains records in the following format:

(<egg> <action> <status> <message> <duration>)

Can be either a symbol that indicates the egg-name or #f to indicate the start and end actions (logged when salmonella is started and when it finishes testing, respectively).


A symbol to indicate the action that was executed. Can be one of the following values:


A numeric value indicating the exit status of the executed action. When the action is test and status is -1, it means that the egg has no tests.


The output generated by the commands executed to perform <action>. A string.


The time (in seconds) that was taken to execute <action>.

For the start and end actions, the value is the seconds since epoch, so the total salmonella execution time can be determined by subtracting the start time from the end time.


Salmonella provides two modules:

the core salmonella functionality and basic data strucuture for logs (report records)
provides procedures to access log files and compute simple statistics regarding log file data.


[record] (report egg action status message duration)
[procedure] make-report
[procedure] report?
[procedure] report-egg
[procedure] report-action
[procedure] report-status
[procedure] report-message
[procedure] report-duration
[procedure] report-egg-set!
[procedure] report-action-set!
[procedure] report-status-set!
[procedure] report-message-set!
[procedure] report-duration-set!

report objects. Each log file registry is represented by a report object (serialized as a list).

[procedure] (report->list report)

Convert a report object to a list.

[procedure] (log! report log-file)

Print the report representation to log-file.

[procedure] (make-salmonella tmp-dir #!key chicken-installation-prefix chicken-install-args eggs-source-dir eggs-doc-dir this-egg?)

The salmonella maker. Returns a procedure that receives symbols (methods) to indicate the actions to be performed. The available methods are (example considering a salmonella object returned by make-salmonella):

(salmonella 'init-repo!)
(salmonella 'clear-repo!)
(salmonella 'fetch <egg>)
(salmonella 'install <egg>)
(salmonella 'test <egg>)
(salmonella 'check-version <egg>)
(salmonella 'env-info)
(salmonella 'meta-data <egg>)
(salmonella 'check-dependencies <egg> <meta data>)
(salmonella 'check-category <egg> <meta data>)
(salmonella 'check-license <egg> <meta data>)
(salmonella 'check-author <egg> <meta data>)
(salmonella 'check-doc <egg>)


[procedure] (read-log-file filename)

Reads the log file filename and returns a list of report records.

fetch action
[procedure] (fetch-status egg log)
[procedure] (fetch-message egg log)
[procedure] (fetch-duration egg log)
install action
[procedure] (install-status egg log)
[procedure] (install-message egg log)
[procedure] (install-duration egg log)
check-version action
[procedure] (check-version-status egg log)
[procedure] (check-version-message egg log)
[procedure] (egg-version egg log)
[procedure] (check-version-ok? egg log)
test action
[procedure] (test-status egg log)
[procedure] (test-message egg log)
[procedure] (test-duration egg log)
[procedure] (has-test? egg log)
meta-data action
[procedure] (meta-data egg log)
[procedure] (egg-dependencies egg log)
[procedure] (egg-license egg log #!key with-test-dependencies? with-versions?)
check-doc action
[procedure] (doc-exists? egg log)
start & end actions
[procedure] (start-time log)
[procedure] (end-time log)
[procedure] (total-time log)
[procedure] (salmonella-info log)
[procedure] (count-install-ok log)
[procedure] (count-install-fail log)
[procedure] (count-test-ok log)
[procedure] (count-test-fail log)
[procedure] (count-no-test log)
[procedure] (count-total-eggs log #!key with-skipped?)
[procedure] (count-documented log)
[procedure] (count-undocumented log)
[procedure] (prettify-time time)
[procedure] (sort-eggs eggs)
[procedure] (log-eggs log)
[procedure] (log-skipped-eggs log)

Environment variables

When running, salmonella sets the SALMONELLA_RUNNING environment variable. If you need to check if your tests code is being run by salmonella, this variable can be used.



Version history

Version 2.6

Version 2.5

Version 2.4

Version 2.3

Version 2.2

Version 2.1

Version 2.0