GerHobbeltmarkdown-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
trueto use fixture headers for test names orfalseto use fixture line numbers for test names like so: "line 123". Defaultfalse. - sep - array of allowed separators for samples,
[ '.' ]by default assert - custom assertion package,
require('assert')by default.The
assertlibrary 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:
itis a reference to the globalit()test function (which must have been set up by your test framework)testTitleis either thefixture.headeror a 'line 123' string listing the starting line of the fixture test spec block.fixtureis a reference to the current fixture record, the format of which is described further below at parse record fixtureoptionsis a reference to the shallow copy of theoptionsinstancemdis a reference to the user-providedmdmarkdown-it instance as described further below.envis a shallow copy of the user-providedenvstructure 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.
- header - Set
md -
markdown-itinstance to parse and compare samplesThe
mdinstance is expected to contain arenderfunction member, which will be invoked likemd.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
pathis 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
optionsare a string instead of an options object, theoptionsstring is assumed to be a string of separator characters, which will be split into an array of seaprators like so:options = { sep: options.split('') }.- sep - array of allowed separators for samples,
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
- 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