Website | User Guide | Report Issue | Development
TAPOUT is the next generation in test results viewing. You may have heard of Turn or minitest-reporters. TAPOUT is the conceptual successor to these gems by virtue of its use of TAP, a standardized intermediate test results protocol.
TAPOUT works as a TAP handler which supports TAP-Y/J as well as traditional TAP streams. TAP-Y/J is a modernization of TAP using pure YAML/JSON streams. Traditional TAP has less detail than TAP-Y/J, but it can still be translated with fairly good results. TAPOUT includes a TAP adapter to handle the translation transparently. Currently TAPOUT supports TAP v12 with some minor limitations.
To learn about the TAP-Y/J specification, see the TAP-Y/J Specification document.
For information about TAP, see http://testanything.org/
To learn more about using Tapout, please see the wiki. It provides more detailed information on how to put Tapout to work for you using your preferred testing framework and build tool. What follows here is a very general overview of usage.
To use TAPOUT you need either a plugin for your current test framework, or use of a test framework that supports TAP-Y/J out of the box. You can find a list of plugins here under the section "Producers".
With a test framework that produces a TAP-Y/J output stream in hand pipe the
output stream into the tapout command by using a standard command line pipe.
$ rubytest -y -Ilib test/foo.rb | tapout
TAPOUT supports a variety of output formats. The default is the common
dot-progress format (simply called dot). Other formats are selectable
via the tapout command's first argument.
$ rubytest -y -Ilib test/foo.rb | tapout progressbar
TAPOUT is smart enough to match the closest matching format name. So, for example, the above could be written as:
$ rubytest -y -Ilib test/foo.rb | tapout pro
And tapout will know to use the progressbar format.
To see a list of supported formats use the list subcommand:
$ tapout --help
If your test framework does not support TAP-Y/J, but does support traditional
TAP, TAPOUT will automatically recognize the difference by TAP's 1..N header
and automatically translate it.
$ rubytest -ftap -Ilib test/foo.rb | tapout progressbar
Since tapout receives test results via a pipe, it has no direct control over
the producer, i.e the test runner. If you need to tell tapout to stop processing
the output then you can send a PAUSE DOCUMENT code. Likewise you can restart
processing by sending a RESUME DOCUMENT code. These codes are taken
from ASCII codes for DLE (Data Link Escape) and ETB (End of Transmission Block),
respectively. When tapout receives a PAUSE DOCUMENT code, it stops interpreting
any data it receives as test results and instead just routes $stdin back
to $stdout unmodified.
A good example of this is debugging with Pry using binding.pry.
def test_something
STDOUT.puts 16.chr # tells tapout to pause processing
binding.pry
STDOUT.puts 23.char # tells tapout to start again
assert something
end
As it turns out, if your are using TAP-Y (not TAP-J) then you can also use YAML's END DOCUMENT marker to acheive a similar result.
def test_something
STDOUT.puts "..." # tells tapout to pause processing
binding.pry
assert something
end
But this only works for YAML and if you happened to be debugging code that emits YAML you might accidentally trigger tapout to resume. Therefore it is recommended that the ASCII codes be used.
Note: When sending these codes, be sure to send a newline character as well.
Copyright (c) 2010 Rubyworks
TAPOUT is modifiable and redistributable in accordance with the BSD-2-Clause license.
See COPYING.md for details.