Cuporter

A Cucumber Reporter

Scrapes your feature files to show test counts and tag relationships.

3 Views

  1. Tag Report
    • Tags listed with all features and scenarios associated with them
    • Each scenario shows all of its tags, for simple cross referencing
  2. Feature Report
    • Simple list of all Cucumber features, sorted by name and file name.
    • Collapsable scenario and scenario outline breakdowns
    • Totals, subtotals, scenario numbering
  3. Tree Report
    • Expandy-collapsy jquery.treeview of your features/** dir
    • Same feature data as above
    • Subtotals on folders

4 Output Formats

  1. html
  2. xml
  3. pretty-print text
  4. csv

Splitting the output among multiple formats is supported, so you could run a single report and write it to an html file, a csv file, and show the xml or text on stdout in the terminal.

i18n: Dozens of Languages

Internationalization through the gherkin lanugage file (i18n.yml). Following cucumber’s rules, non-English keywords will be used for any feature file with a ‘# language: <iso-code>’ header on line 1,

A Bunch of Configuration Options

See the help output below for all of the options, which can be supplied in two ways:

  1. Command Line
  2. Yaml File
    • use it to add to or override the program defaults
    • Batch mode: run multiple reports at once simply by specifying an option set for each in cuporter.yml
    • the file name itself is a configurable option
    • See the samples.

option override precedence

  1. Highest Precedence (overrides all): command line
  2. Middle Precedence: yaml file
  3. Lowest Precedence: Cuporter::Config::OptionSet::DEFAULTS

Example Report Output

html samples

See http://twcamper.github.com/cuporter/

xml of single test


<?xml version="1.0" encoding="UTF-8"?>
<xml>
  <body>
    <report view="tag" title="Cucumber Tags" total="1">
      <tag cuke_name="@just_me" total="1">
        <feature cuke_name="Feature: Pretty print report on 3 features" file_path="features/pretty_print.feature" total="1">
          <scenario cuke_name="Scenario: Tag report on everything in fixtures/self_test" tags="@just_me" number="1"/>
        </feature>
      </tag>
    </report>
  </body>
</xml>

numbered pretty text


@failing
   Feature: Abominable Aardvark            @failing, @zoology
   1. Scenario: An Aardvark eats ants
   2. Scenario: Zee Zebra eats zee aardvark
   Feature: Wired                          
   3. Scenario: Everybody's Wired          @failing
      Scenario Outline: Why is everybody so wired?
         Examples: loosely wired
            | arg1 | arg2 |
   4.       | foo  | bar  |
   5.       | shif | fish |
         Examples: tightly wired           @ignore
            | arg1  | arg2  |
   6.       | foo   | bar   |
   7.       | frotz | knurl |
   8. Scenario: Yellow lines
@ignore
   Feature: Wired
      Scenario Outline: Why is everybody so wired?
         Examples: tightly wired
            | arg1  | arg2  |
   1.       | foo   | bar   |
   2.       | frotz | knurl |
@wip
   Feature: HTML formatter
   1. Scenario: Everything in fixtures/self_test
   Feature: not everyone is involved
   2. Scenario: Failure is not an option, people
   Feature: sample
   3. Scenario: And yet another Example
   Feature: search examples
   4. Scenario: Generate PDF with pdf formatter


Install


  $ gem install cuporter

Once installed, you can run $ cuporter anywhere on your system. In any project dir, it will read your features/** by default. If you clone the repo, you can run $ ./bin/cuporter from within it.


Command Lines

help


  $ cuporter -h
  
  Usage: cuporter [options]

    -r, --report [tag|feature|tree]  View, or type of report.
                                         Default: "tag"
            
    -f, --format [xml|html|csv|text] Output format.
                                         Default: text (it's pretty, though!)
            
    -i, --input-dir DIR              Root directory of *.feature files to be read.
                                         Default: "features"

                                         Used to build the glob pattern '[--input-dir]/**/*.feature', which is really most likely
                                         "features/**/*.features" and finds all feature files anywhere under "features" or
                                         your custom root supplied with this option.
                                         Overridden by "--file-input".
            
    -I, --file-input FILE            Single *.feature file.  Full name with extension, like 'path/to/file.feature.'
                                         Overrides "--input-dir" and used mostly for testing.
            
    -H, --output-home PATH           Root directory for the output files, like 'tmp/cucumber'.
                                         Optional, because the path can also be specified along with the 
                                         file name in "--output-file"

                                         Default: ""

        --log-dir PATH               Home directory for the error log 'cuporter_errors.log'.

                                         Default: "." if no report output file is specified, else same as output file dir.

            
    -o, --output-file FILE           Output file path, like 'tmp/cucumber/tag_report.html'.
            
    -t, --tags TAG_EXPRESSION        Filter on tags for name report.
                                         TAG_EXPRESSION rules:
                                             1. $ cucumber --help
                                             2. http://github.com/aslakhellesoy/cucumber/wiki/Tags
            
    -T, --title STRING               Override report default title, which is different for each view/report.
                                         This affects the xml 'report' node title and the html head > title attributes.
            
        --config-file PATH           Specify any of these options in a yml file.
                                           Order of precedence:
                                              1 - command line
                                              2 - yaml file
                                              3 - these defaults

                                           Default: 'config/cuporter.yml'
            
    -d, --dry-run                    Print the configuration without running any reports.
            
        --text-summary               Add a summary to the text format.
            
  CSS and Javascript asset options:

    -l, --link-assets                Do not inline CSS and js in <style/> and <script/> tags, but link to external files instead.
                                           Default:  'false' for the tag and feature views, not optional for the
                                                     tree view, which requires external gifs.
            
    -c, --copy-public-assets         If --output-file is supplied, and you're linking to external 
                                           CSS and JavaScript assets, copy them from 'public/' to 'cuporter_public'
                                           in the same dir as the output file.
                                           Sets --use-copied-public-assets to 'true', and
                                           the html report will link to these files by relative path.

                                           Default: 'false'
            
    -u, --use-copied-public-assets   When running batches of reports, and the assets folder has already been
                                           created by another call to cuporter with '--copy-public-assets'.
                                           Set to 'true' automatically along with --copy-public-assets.

                                           Default: 'false'
            
  Reporting options: on by default but can be turned off:

        --no-sort                    Do not sort tags, features, scenarios, or outlines
        --no-number                  Do not get or show scenario or example numbers, (i.e., do not number the leaf nodes).
        --no-total                   Do not get or show totals
        --no-show-tags               Do not show cucumber tags at the feature, scenario, or outline level.
        --no-show-files              Do not show feature file paths.
        --no-leaves                  Show features only, with no scenarios or outlines.

Examples


  #  pretty-print demo report to stdout
  $ ./bin/cuporter -i fixtures/self_test

  #  same, XML to console
  $ ./bin/cuporter -i fixtures/self_test -f xml

  #  List View: html without totals, xml without leaves (scenarios and examples)
  $ cuporter -i fixtures/ -r feature -f html --no-total  > redirecting_is_ok_too.html
  $ cuporter -i fixtures/ -r feature -f xml -o fixtures_demo.xml --no-leaves

  #  Tree View of default input features/**/*.feature to 
  $ cuporter -f html -r tree -o feature_tree_view.html

  #  filtered html feature report, with non-default title
  $ cuporter -f html -o active_customer.html -r feature -T "Active Customer Test Inventory" -t ~@wip -t @customer,@client

Dependencies

  1. Nokogiri 1.4.1 or above
    • For all things Nodular: XML document building and XSL transformation into HTML
    • Not tested on earlier versions yet but I’d guess you’ll be fine with anything recent.
    • libxml2 and libxslt are required by this gem, which should handle them smoothly. However, libxml and cousins can at times present installation difficulties in the form of clashes with already-installed C resources. It has to do with very specific lib versioning and installation order issues. It’s not always the same problem, so there’s no prescription for it but Google, unfortunately.
  2. Gherkin 1.0.0 or above
    • For looking up keywords Feature, Scenario, Scenario Outline, and Examples by ISO language code.
  3. jQuery and jQueryTreeview
    • packaged with the gem
    • jquery.treeview relies on image files, so our tree view requires the HTML to link to its resources rather than copying them to the <head>.

Acknowledgements

  • Acknowledgements remain due to the Cucumber HTML formatter, and to the human one, too!.
  • Thanks to everyone involved in Nokogiri, jQuery and the Treeview plugin.