adobeFerrum Doctest
Ferrum.doctest allows you to test examples included in your documentation.
Did you every try an example from a project just to notice that it contains a syntax error? Did you ever avoid writing examples because it is extra work and you basically wrote the same code in your tests?
This is what ferrum.doctest is designed to solve! It parses your source code, extracts all the examples from your jsdoc and generates a file that can be executed with your test framework!
Using it
Install it:
$ npm install --only-dev ferrum.doctest
And execute your tests:
$ npx ferrum.doctest exec \
-s src/ --mdsrc README.md \
-c 'mocha --require source-map-support/register \"$DOCTEST_FILE\" test/'
The -s and --mdsrc indicate which source files/directories to scan for examples.
The -c indicates your command to invoke tests. "$DOCTEST_FILE" is a variable indicating
the location of the generated tests.
ferrum.doctest also features a generate command which just generates the tests without
execting any actual tests. Invoke $ ferrum.doctest help for more information.
Selectively disabling tests
You can use the notest tag on code blocks inside markdown to disable
testing that particular block
```notest
This will not be tested.
```
Other testing frameworks
You will have to provide a test file template for your particular testing framework.
$ npx ferrum.doctest exec \
-t ./myJasmineTemplate.js.sqrl \
-s src/ --mdsrc README.md \
-c 'jasmine ...'
See defaultTemplate inside index.js.
Stack Traces/Source Maps
Ferrum.doctest automatically generates source maps. We use the source-map-support package to add support for them while testing.
Note that the mocha example above already provides support for source maps!
Unfortunately source maps currently do not work for syntax errors, but support for syntax errors is planned.
Using from javascript
Ferrum.doctest has an extensive api documentation. See index.js
and the generateTests() function in particular.
Changelog
- 1.0.0 Update to squirelly 8: The
Renderfunction is now calledrender; some other function names changed too. Variables passed to the render context are now addressed usingit.<variable>in templates.
Build
$ npm install
Test
$ npm test
Lint
$ npm run lint