pattern matching assertion framework for documents
try it with tracery!
(work in progress, see test/example.js
or ask Jason. Not yet ready for public consumption, ymmv)
docrules defines sets of rules
grouped by selectors
. Rule sets can then be run on a document to generate a report of errors, warnings, and info.
var docrules = require('docrules')
first we create a rule set
var rules = new docrules()
Now add a matching selector. Selectors use mongodb style dot notation. A wildcard *
can be used to match any key at that level.
rules.match(selector, (ruleCb) => void)
The second argument of rules.match
is a function which takes a ruleCallback. This ruleCallback is used to define rules which should be run on each item which matches the selector
rules.match('users.*', function (user) {
We define a rule like so:
user('should have an ID', function (assert) {
Rule callbacks require a label (shown in the report if the rule reports an error, warning, or info), and a body function defining the rule. The body function is passed an assert
function which should be used to ensure proper reporting. Other assertion libraries should not be used at this time (see the run
function implementation of index.js
if you want to hack it in). this
is bound to the matching value, in this case, a user object.
assert(this.hasOwnProperty(id))
.error()
})
Assertions are called as chains. They require a condition and a report, and may have a fix in between.
assert(condition)
.report('level','message')
or
assert(condition)
.fix('label', function() {})
.report('level','message')
There are three aliases for .report
which pre-fill the label for you - normally you will use this:
.error('message')
.warn('message')
.info('message')
Note the assertion will not throw if you do not call a report function, even if the condition fails. (This may change in future versions)
After we've created a ruleset, added some match groups, and defined some rules, we can run these by calling
var report = ruleset.run(document)
The resulting report is an array which looks like this:
[ { inner: { name: 'AssertReportError', level: 'error', message: 'not a user' }, selector: 'users.*', path: [ 'users', 'b' ], value: { firstName: 'Bertha', lastName: 'Cortez', likesStarWars: true }, rule: 'schema', level: 'error', message: 'not a user' } ]
With these additional properties:
{ matches: 2, rules: 6, errors: [ { inner: [Object], selector: 'users.*', path: [Object], value: [Object], rule: 'schema', level: 'error', message: 'not a user' } ], warnings: [] }
For a full end-to-end, see test/example.js
internal (c) 2013 Agile Diagnosis.