🚀 Feature: Allow adding a description with the reason why a test is pending

[basharov]

I can add pending reason in Jasmine tests with .pend() method and replacing it() with xit() like this:

xit('should save settings when proper object is passed', function(){}).pend('No local storage is supported yet');

Can I somehow add a pending reason message for Mocha tests?

[gurdiga]

As a lightweight workaround, I would think of tweaking the test description to include the reason why it’s pending. 😊

xit('works as expected; PENDING: waiting for a dependency to be implemented', function() {
});

I’m guessing this would work, but I curious to know how would such a feature be useful? 👷

[tommy-p]

This feature is pretty useful, is is not a good idea to mix test description and reason why test is pending. pend() method allows to distinguish pend reason from description. And instead of meaningless reason "No reason given" in jasmine you can add more info, issue number, etc.

[rdennis]

What would the syntax be for this feature? I would expect something like:

// describe.skip = xdescribe
describe.skip('Foo', function () {
    ...
}, 'Reason Foo was skipped');

describe('Bar', function () {
    // it.skip = xit
    it.skip('#baz', function () {
        ...
    }, 'Reason #baz was skipped');
});

Or would a chained function be more readable?

describe.skip('Foo', function () {
    ...
})
.because('Reason Foo was skipped');

describe('Bar', function () {
    it.skip('#baz', function () {
        ...
    })
    .because('Reason #baz was skipped');
});

[Nokel81]

I like the chain version since that seems to be the best inline with how the rest of mocha operates

[dietergeerts]

skip and pending isn't the same though. In mocha, when your it block only has a description, it is pending. So I believe that it would be better to add the reason as the second argument then. So then mocha just has to look at the second argument to see if it is undefined (which it already does) or if it's a string, and then the test is pending, using the string value as the reason.

Of course, if we want the same thing for skipped tests, which you would do because you can't fix the test code for the moment for example, then you still want a way to add a reason. If using the before mentioned way, you can add a reason as third argument.

But using chaining like @rdennis comment, could also be fine. I just wanted to point out that pending isn't the same as skip, and as the topic starter asked about pending reasons....

[fotoflo]

Using xit.() makes tests pending - which confused me as a new user because pending means "awaiting decision or settlement." - i assumed it was some async that hadn't completed.

seems skipped would be a better description for xit.

  24 passing (690ms)
  7 pending

[JoshuaKGoldberg]

Related to the discussion: #1815 tracks separating "pending" and "skipped" categories.

This needs discussion on how the feature should look. Maybe it should be the fluent API (test(...).describe("..."))? Maybe rolled into #928 (test metadata)?

[JoshuaKGoldberg]

As a lightweight workaround, I would think of tweaking the test description to include the reason why it’s pending. 😊

Triaging with @voxpelli: amusingly, this first + simplest approach seems the most reasonable to us. We can see why an explicit indicator would be useful - but it's not a particularly common need, and adding a description to the test description is a pretty good workaround for most.

Closing as wontfix, as #928 (test metadata) would be a better holistic solution. Thanks all! 🤎