[Feat] Add descriptive messages for skipped asserts

[r0mflip]

Now asserts can take skip as a string or boolean, strings get printed as the reason for skipping the assert.

(ok|not ok) 3 <assert message> # SKIP <reason for skipping>

[ljharb]

Is this a convenience feature, or something that you'd expect as part of any tap client? Are their other TAP-producing runners that do this?

[r0mflip]

TAP indicates that any individual assert can be skipped or marked todo. node-tap allows this and this also plays really well with tap-parser. The same should work for todo, but node 0.8 has problems with the stack.

test('this skipps', { skip: true }, function (t) {
    t.fail('doesn\'t run');
    t.fail('this doesn\'t run too', { skip: false });
    t.end();
});

test('some tests might skip', function (t) {
    t.pass('this runs');
    t.fail('failing assert is skipped', { skip: true });
    t.pass('this runs');
    t.end();
});

test('incomplete test', function (t) {
    // var platform = process.platform; something like this needed
    var platform = 'win32';

    t.pass('run sh', { skip: platform !== 'win32' });
    t.pass('run openssl', { skip: platform === 'win32' });
    t.end();
});

test('incomplete test with explanation', function (t) {
    // var platform = process.platform; something like this needed
    var platform = 'win32';

    t.fail('run sh (conditional skip)', { skip: platform === 'win32' });
    t.fail('run openssl', { skip: platform === 'win32' && 'can\'t run on windows platforms' });
    t.pass('this runs');
    t.end();
});

tap-parser output

[
  [ 'version', 13 ],
  [ 'comment', '# SKIP this skipps\n' ],
  [ 'comment', '# some tests might skip\n' ],
  [
    'assert',
    Result { ok: true, id: 1, name: 'this runs', fullname: '' }
  ],
  [
    'assert',
    Result {
      ok: true,
      id: 2,
      skip: true,
      name: 'failing assert is skipped',
      fullname: ''
    }
  ],
  [
    'assert',
    Result { ok: true, id: 3, name: 'this runs', fullname: '' }
  ],
  [ 'comment', '# incomplete test\n' ],
  [
    'assert',
    Result { ok: true, id: 4, name: 'run sh', fullname: '' }
  ],
  [
    'assert',
    Result {
      ok: true,
      id: 5,
      skip: true,
      name: 'run openssl',
      fullname: ''
    }
  ],
  [ 'comment', '# incomplete test with explanation\n' ],
  [
    'assert',
    Result {
      ok: true,
      id: 6,
      skip: true,
      name: 'run sh (conditional skip)',
      fullname: ''
    }
  ],
  [
    'assert',
    Result {
      ok: true,
      id: 7,
      skip: "can't run on windows platforms",
      name: 'run openssl',
      fullname: ''
    }
  ],
  [
    'assert',
    Result { ok: true, id: 8, name: 'this runs', fullname: '' }
  ],
  [ 'plan', { start: 1, end: 8 } ],
  [ 'comment', '# tests 8\n' ],
  [ 'comment', '# pass  8\n' ],
  [ 'comment', '# ok\n' ],
  [ 'comment', '# skip: 4\n' ],
  [
    'complete',
    FinalResults {
      ok: true,
      count: 8,
      pass: 8,
      fail: 0,
      bailout: false,
      todo: 0,
      skip: 4,
      plan: FinalPlan {
        start: 1,
        end: 8,
        skipAll: false,
        skipReason: '',
        comment: ''
      },
      failures: []
    }
  ]
]