Document coverage ignore syntax, fixes #438

[skeggse]

It's a pretty long example, but I wanted it to be believable. Comments?

[geek]

Mind removing the part about being difficult, maybe rephrase to something like:

"Sometimes you want to disable code coverage for specific lines, below is an example demonstrating this:"

[skeggse]

Can do. Will change in about an hour.

[skeggse]

@geek there ya go

[gergoerdosi]

I'm not sure this is a good example. If a code may throw an error, then it should definitely have a test case.

[skeggse]

The thrown error is a logical error - it's basically an assertion. It's like having the following:

var fn = function () {

    var value = 7;
    assert(value !== 6);
};

The assert could theoretically throw an error. I mean, it is a function, and it has a statement that throws an error. However, in no conceivable case would the error actually be thrown, and there aren't any tests you can write that would cause the assertion to fail.

My example is a little more involved, but it boils down to the same thing: you cannot write a test to make the variable anything but 0 and 1, because the only two changes to the variable are state = 0 and state = 1. There's no state = option or anything.

[gergoerdosi]

I get the code part. What I'm saying is that users reading the documentation are only interested in the syntax - how to disable coverage for a certain part of the code. Most of them won't spend time on understanding the whole code in your example (it's 33 lines long), they will just see this part:

// $lab:coverage:off$
default:
    throw new Error('State machine violation');
// $lab:coverage:on$

So what they will think is that coverage can be ignored for thrown errors in the code. Which I think is a bad message, because exceptions affect the flow of the code, so they should have a test case.

[skeggse]

Hmm good point.

[skeggse]

That look better?

[gergoerdosi]

Yes, I think a simpler example is better. I actually like the one which is already in the code of lab (https://github.com/hapijs/lab/blob/master/lib/reporters/console.js#L99-L103):

/* $lab:coverage:off$ */ // There is no way to cover that in node 0.10
if (typeof value === 'symbol') {
    return '[' + value.toString() + ']';
}
/* $lab:coverage:on$ */

It is clear why coverage is ignored. But I'm fine with your example too. It was only the previous one that I didn't like.

[lock]

This thread has been automatically locked due to inactivity. Please open a new issue for related bugs or questions following the new issue template instructions.