Jest: Feature: add `toBeNil()` matcher

[WickyNilliams]

Do you want to request a feature or report a bug?

Feature

What is the current behavior?

Currently there is no simple way to check a value is not null or undefined. You would have to do:

expect(someValue).not.toBeUndefined();
expect(someValue).not.toBeNull();

What is the expected behavior?

It would be useful to have a matcher toBeNil() which checks a value is null or undefined. WIth this, the above example could be modified to be:

expect(someValue).not.toBeNil();

[SimenB]

expect(someValue == null).not.toBe(true); works.

But since the docs for toBeNull is ".toBeNull() is the same as .toBe(null) but the error messages are a bit nicer." I suppose this would make sense as well?

[WickyNilliams]

Yea, I know there are ways to do it, but it's about being clear in your intentions. A lot of the time, null and undefined are treated as interchangeable, and whether a method returns null or undefined is often an implementation detail that I don't (or shouldn't have to) care about. I just want to know "does x have a value or not?".

And as you mentioned, you get better messaging with a tailored matcher.

[aaronabramov]

i think adding toBeNil makes it even less clear, since there's no nil in javascript and we'll have to add another piece of documentation explaining what nil does.
Also i think this use case is very specific, and can be addressed by either someValue == null as @SimenB mentioned, or adding a custom matcher using expect.extend

[WickyNilliams]

I wasn't pushing specifically for that name, but more for the idea. A failure for someValue == null would be "expected true to be false", that isn't clear at all!

It's equivalent to the exist matcher in chai.

But yes, perhaps i'll go with a custom matcher.

[orta]

I would have expected toBeFalsy to be the matcher that represents what you're trying to do: expect(null).toBeFalsy()

[SimenB]

Falsy also gets '', 0 and NaN, which you might not want to test against.

[WickyNilliams]

Yes, toBeFalsy is too broad, and again doesn't convey intentions

[SimenB]

toExist might make sense. Or just toBeNullOrUndefined.
But I do agree it's more of a custom matcher kind of thing (although it would have given a nice addition next to toBeNull and toBeUndefined).

[thymikee]

toBeNullified ( ͡° ͜ʖ ͡°)

[WickyNilliams]

Name it whatever you want :) I just think it's a handy tool in the belt, and not an uncommon use-case

[WickyNilliams]

Just realised where I got the name from: lodash https://lodash.com/docs/4.17.4#isNil

[finnigantime]

I would really like to see a toExist() matcher like Jasmine and chai support.

toBeTruthy() comes close but is less readable as far as code intent and requires the user to have an intimate knowledge of falsy and truthy values in Javascript, which is arcane knowledge.

With toExist() the intent is to test that the value returned is not null and not undefined. For lack of an obvious matcher to do this, we see folks writing expect(val).not.toBeNull() which will pass for undefined and mask errors. To test for the existence of a value I find it more natural to read and write expect(val).toExist() than expect(val).toBeTruthy().

[SimenB]

You can add jest-extended which has this matcher: https://github.com/jest-community/jest-extended/blob/master/README.md#tobenil