dump_describes
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, Mocha and Jest.
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
------------ | -------------
--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
--debug | Turns on debug mode
--verbose, -v | Also dumps `it` blocks
--help, -h | Show help
Examples
Test on the CLI by piping into stdin
:
cat | dump_describes -v
At which point enter the following snippet, followed by Ctrl-D:
describe('test', () => {
describe('foo', () => {
it('should derp', () => {
});
});
});
The following will dump the result of processing the Filters.js
suite to stdout
:
dump_describes -t Filters.js
Also, print debugging information:
dump_describes --debug -t Filters.js
Also, dump it
blocks:
dump_describes -t Filters.js -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 https://raw.githubusercontent.com/btoll/dump_describes/master/spec/dump_describes_spec.js |
dump_describes -v --html |
cut -d' ' -f3 |
xargs xdg-open
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
Known Issues
The following nodes are not yet supported and parsing them will produce surprising and unexpected results (even errors):
- ForStatement
- ForInStatement
- ForOfStatement
- DoWhileStatement
- WhileStatement
License
Author
Benjamin Toll