node package manager

dump_describes

View all describe and it blocks in a test suite

dump_describes

Build Status Coverage Status

dump_describes is a tool that provides a high-level view of all of the describe and it blocks in a test suite. This is useful to quickly gain familiarity with a particular suite and to easily determine where to insert new tests.

Any testing framework that uses describe and it blocks to define a suite is supported, such as Jasmine and Mocha.

How It Works

dump_describes uses Esprima to parse the given JavaScript and create an AST. This is then recursively walked to find all of the describe blocks and, optionally, all of the it blocks. The results are either logged to stdout or written to an html document.

The top-most describe block which wraps the entire suite will be used as the name of the produced output and will lend its name to the generated html file (if the --html switch is given).

When transpiling from another language into JavaScript, it can be useful to pipe the results of the transpilation to dump_describes. This is useful and avoids the intermediary step of having to save to a file:

coffee -p suite.coffee | dump_describes

By default, dump_describes will only dump the describe blocks. Use the --verbose flag to also dump the it blocks.

The following identifiers are supported:

  • describe
  • fdescribe
  • xdescribe
  • it
  • fit
  • xit

Installation

npm install https://github.com/btoll/dump_describes.git -g

Usage

Property Description
--active List only active blocks (i.e., fdescribe, fit)
--inactive List only inactive blocks (i.e., xdescribe, xit)
--destination, -d [Optional] The location to save the output (defaults to $PWD)
--html Creates an html document of the tree
--markdown, --md Creates a markdown document of the tree
--target, -t The target suite to parse
--verbose, -v Also dumps it blocks
--help, -h Show help

Examples

The following will dump the result of processing the Filters.js suite to stdout:

dump_describes -t Filters.js

Also, dump it blocks:

dump_describes -t Filters.js -v

Only dump the 'active' fdescribe blocks to stdout:

dump_describes -t Filters.js --active

Same as the previous, but in addition dump 'active' fit blocks to stdout:

dump_describes -t Filters.js --active

Only dump the 'inactive' xdescribe blocks to stdout:

dump_describes -t Filters.js --inactive

Same as the previous, but in addition dump 'inactive' xit blocks to stdout:

dump_describes -t Filters.js --inactive -v

Create an html document of the same tree produced by the previous command (describe nodes can be expanded/collapsed):

dump_describes -t Filters.js -v --html

Create an markdown document of the same tree produced by the previous command (describe nodes can be expanded/collapsed):

dump_describes -t Filters.js -v --md

Pipe:

coffee -p suite.coffee | dump_describes -v --html

cat suite.js | dump_describes -v

dump_describes -t Filters.js | tee foo

Let's get fancy and open a file from the internet in the default browser:

curl http://bit.ly/1UezNMy | dump_describes -v --html | cut -d' ' -f2 | xargs open
  • Note that the above pipeline is using open which is an OS X tool.

Creating a Custom Code Generator

dump_describes ships with three generators, LOG, HTML and MARKDOWN.

However, it's very easy to create a generator. The only stipulation is that the generator module expose a print method, which is called with the node results and the value of verbose.

print must return a Promise, which in turn will resolve with the list of transformed results or a simple message or something else, depending on the requirements.

Using with Vim

I use the following command abbreviations to view a suite from within Vim.

Typing :dd followed by a [[space]] will become :!clear && dump_describes -t %:

autocmd FileType javascript cnoreabbrev <expr> dd getcmdtype() == ":" && getcmdline() == 'dd' ? '!clear && dump_describes -t %' : 'dd'

Typing :ddv followed by a [[space]] will become :!clear && dump_describes -t % -v:

autocmd FileType javascript cnoreabbrev <expr> ddv getcmdtype() == ":" && getcmdline() == 'ddv' ? '!clear && dump_describes -t % -v' : 'ddv'

Screenshots

ScreenShot ScreenShot ScreenShot ScreenShot

License

MIT

Author

Benjamin Toll