Skip to content
Test the examples in your jsodc documentation!
Branch: master
Clone or download
trieloff Merge pull request #12 from adobe/renovate/major-any
chore(deps): update dependency @semantic-release/github to v7
Latest commit 5ee6b1a Feb 12, 2020
Type Name Latest commit message Commit time
Failed to load latest commit information.

Ferrum 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 \
  -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

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 \
  -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.


$ npm install


$ npm test


$ npm run lint
You can’t perform that action at this time.