@gerhobbelt/markdown-it-testgen

Tests generator for markdown-it markdown parser

Stats

StarsIssuesVersionUpdatedCreatedSize
@gerhobbelt/markdown-it-testgen
010.1.6-233 months ago4 years agoMinified + gzip package size for @gerhobbelt/markdown-it-testgen in KB

Readme

markdown-it-testgen

Node.js CI CircleCI NPM version

This package parses fixtures in commonmark spec format and generates tests for markdown-it parser and plugins.

npm install markdown-it-testgen

Fixture format

Each fixture can have optional metadata in yaml format:

---
desc: Batch description # file name used if not exists.
skip: true              # mark batch as pending
---

Then tests should follow in this format:

optional header
.
source
data
.
parsed
data
.


header2
.
src
.
result
.

If header missed - line number will be used instead.

API

generate: module.exports(path, options, md, env)

  • path - file or directory name

  • options (not mandatory)

    • header - Set true to use fixture headers for test names or false to use fixture line numbers for test names like so: "line 123". Default false.

    • sep - array of allowed separators for samples, [ '.' ] by default

    • assert - custom assertion package, require('assert') by default.

      The assert library you supply must at least provide these member functions:

      • assert.strictEqual(a, b, message)
      • assert(booleanTestResult, message)
    • test - optional test function which will be used instead of the global it(...) test function when provided.

      The test() function is invoked like so:

      options.test(it, testTitle, fixture, options, md, Object.assign({}, env))

      where:

      • it is a reference to the global it() test function (which must have been set up by your test framework)
      • testTitle is either the fixture.header or a 'line 123' string listing the starting line of the fixture test spec block.
      • fixture is a reference to the current fixture record, the format of which is described further below at parse record fixture
      • options is a reference to the shallow copy of the options instance
      • md is a reference to the user-provided md markdown-it instance as described further below.
      • env is a shallow copy of the user-provided env structure as described further below.

      The options.test() callback allows the creation of arbitrary fixture-file based test rigs, whether it is for markdown-it or another library. See the 'generator correctly handles options.test user-defined test function' test for an example.

  • md - markdown-it instance to parse and compare samples

    The md instance is expected to contain a render function member, which will be invoked like md.render(fixture.first.text, Object.assign({}, env)).

  • env (not mandatory) - environment object to be passed through to markdown-it.render()

module.exports.load(path, options, iterator)

For each loaded file: parse and pass data to iterator function. Currently used for tests only.

Returns NULL (when no fixture file could be found in the given directory) or a non-empty array of parse records. The parse record structure is described further below at the options.iterator option.

  • path - file or directory name

    When the path is a directory, it is traversed rescursively to load all files within. Every non-empty file will be parsed as a single fixture record.

  • options (not mandatory)

    • sep - array of allowed separators for samples, [ '.' ] by default

    Note: when the options are a string instead of an options object, the options string is assumed to be a string of separator characters, which will be split into an array of seaprators like so: options = { sep: options.split('') }.

  • iterator - every non-empty parsed file will invoke the iterator(record) callback once, passing a parse record with the following structure:

    • meta - the YAML-parsed frontmatter metadata at the head of the loaded fixture file -- this frontmatter metadata must be enclosed between a top and bottom line containing only a --- separator as is usual with MarkDown frontmatter.
    • file - the path to the actual file loaded & parsed.
    • fixtures - an array with zero or more fixture records with the following structure:
      • header - (possibly empty) header/title.

        This can serve as a test descriptor/title and is a trimmed copy of the last non-empty line of text preceding the fixture test spec itself.

      • type - identifies the separator used for this particular fixture test spec. '.' by default.

      • first - object:

        • text - the first text extracted from the fixture test spec block
        • range - array listing both the starting and ending line numbers for this text
      • second - object:

        • text - the second text extracted from the fixture test spec block
        • range - array listing both the starting and ending line numbers for this text

License

MIT

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.