Lembas -- Testing framework for command line applications inspired by Cram
use Test::More; use Lembas; open my $specs, '<', 'hg-for-dummies.lembas' or BAILOUT("can't open Mercurial session test specs: $!"); my $lembas = Lembas->new_from_test_spec(handle => $specs); plan tests => $lembas->plan_size; $lembas->run;
It's better than cram :)
In short, you write down shell sessions verbatim, allowing for variance such as "this part here should match this regex" or "then there's some output nobody really cares about" or even "this output should be printed within N seconds". The markup is really very simple so you can almost copy-paste real shell sessions and have it work.
Then Lembas will spawn a shell process of your choice and pass it the commands and test if the output matches what's expected, thereby turning your shell session into a test suite!
You can get the number of tests run for a suite through your Lembas object, so you can plan your tests as usual (or just let done_testing handle it). A design point is that the number of tests should be constant for a given script, no matter how many lines fail to match.
done_testing
An automatic, free test tells you if you had any extra unmatched output after your last matched line for each command. This is not entirely reliable though and may produce false positives. Tuits and patches welcome.
This is a simple script suitable to test the very first chapter of your Mercurial Course for Dummkopfs. Whitespace is important.
#!/bin/bash # Do all the work in /tmp $ cd /tmp $ pwd /tmp # Testing presence of Mercurial $ hg --version re: Mercurial Distributed SCM \(version [\d.]+\) (see http://mercurial.selenic.com for more information) re: Copyright \(C\) [\d-]+ Matt Mackall and others This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. # Creating a repository $ mkdir foo $ cd foo $ pwd /tmp/foo $ hg init $ echo "this is a file" > content $ cat content this is a file $ hg add content $ hg st A content $ hg commit -m "created repo and added a file" # Checking that everything looks good $ hg log re: changeset: 0:[a-f0-9]{12} tag: tip user: Fabrice Gabolde <fabrice.gabolde@gmail.com> re: date: .* summary: created repo and added a file # Cleanup $ rm -Rf /tmp/foo
Lines with content in the first four characters are assumed to be Lembas commands (or comments). The rest are shell commands (if they start with "$ ") or shell output (otherwise). The syntax for "this line of output should be matched as a regex" is problematic; Cram puts " re" at the end of a line but it seems ugly to me.
The shebang-looking line at the top is almost exactly that. It's a user-friendly way of specifying "run this command with these arguments".
You'll notice that this works with or without the color extension for Mercurial; Lembas removes ANSI terminal escape characters before matching output.
color
The manual describes the syntax and lists the available commands.
my $lembas = Lembas->new(shell => [ '/bin/bash' ], commands => [ { shell => 'whoami', outputs => [ 'fgabolde' ] } ]);
Creates a new Lembas object with the corresponding settings and expected outputs.
my $lembas = Lembas->new_from_test_spec(shell => [ '/bin/bash' ], handle => $iohandle);
Same as new, but parses a spec file first and uses it to set the command/outputs list. The shell parameter is optional if you have a shebang in the spec file, but still useful in case you want to force a different program.
new
shell
plan tests => $lembas->plan_size + $the_rest;
If you dislike done_testing, you can use this method to obtain the number of tests that will be run by this Lembas instance. CAVEAT: it will only return a meaningful value if the Lembas instance was created with new_from_test_spec.
new_from_test_spec
$lembas->run;
Uses Test::Builder to run all the tests specified, reporting success, failure and diagnostics in the usual manner.
Test::Builder
The original inspiration for Lembas: Cram
If you're looking for something more complex and low-level, you probably want Expect.pm instead.
Fabrice Gabolde <fabrice.gabolde@gmail.com>
Copyright (C) 2013 Fabrice Gabolde
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.
To install Lembas, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Lembas
CPAN shell
perl -MCPAN -e shell install Lembas
For more information on module installation, please visit the detailed CPAN module installation guide.