gerhobbelt / markdown-it-testgen

Tests generator for markdown-it and plugins

markdown-it-testgen

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