-
Notifications
You must be signed in to change notification settings - Fork 29.6k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
assert: improve assert.throws #17585
Conversation
doc/api/assert.md
Outdated
@@ -772,7 +772,7 @@ argument, then `error` is assumed to be omitted and the string will be used for | |||
<!-- eslint-disable no-restricted-syntax --> | |||
```js | |||
// THIS IS A MISTAKE! DO NOT DO THIS! | |||
assert.throws(myFunction, 'missing foo', 'did not throw with expected message'); | |||
assert.throws(myFunction, 'missing foo'); // Did not throw with expected message |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The text above this example needs to be re-written now as well as the example on line 778 as well. Rather than moving the third argument to a comment, perhaps just remove it entirely. The user should still be cautioned against using a string for the expected error message because a string will be interpreted as the message to provide if the function doesn't throw rather than something to validate the thrown error.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I am not sure I can follow. The situation was only improved in case three arguments are passed to throws
. Otherwise the problem continues to exist. So the mitigation is only very tiny as the typical wrong use case is probably assert.throws(fn, "error msg")
.
I thought a few times about how to improve the two args situation but as far as I see it there is nothing that can be done to improve it. I actually also thought about deprecating using a string as second argument but that would be very inconsistent and weird as well.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Refining my comment a bit: The current version of the example code (assert.throws(fn, str, str)
) is obviously an error. The version above in this PR (assert.throws(fn, str)
) is less obviously an error because maybe "missing foo" is not an expected error message but rather the error message we want to provide if the function doesn't throw as expected. It's not clear to me if the best way to clarify is to edit the text preceding the block or if it is to edit missing foo
to say something else.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM with doc comment addressed.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Agree with @Trott abotu the doc being a little confusing now.
I updated the example and tried to be as detailed and precise as possible. |
While thinking about this further: is this actually a semver-patch instead of semver-major? Because the use case when a error is now thrown is clearly a mistake and did not work as the user intended. |
doc/api/assert.md
Outdated
``` | ||
|
||
Due to the confusing notation it is recommended not to use a string as second | ||
argument at all. This might otherwise lead to difficult to spot errors. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nit: difficult to spot
-> difficult-to-spot
doc/api/assert.md
Outdated
``` | ||
|
||
Due to the confusing notation it is recommended not to use a string as second |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should it be as the second
instead of as second
? That seems more natural to me.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hm, for me as second
sounds better but I am probably not the best one to ask in this case. Are there any other votes? 😆
doc/api/assert.md
Outdated
// If you originally intended to match for the error message do this instead: | ||
assert.throws(throwingMatched, /^Error: Matched$/); | ||
// Does not throw because the error messages match. | ||
assert.throws(throwingMismatch, /^Error: Matched$/); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Am I missing something subtle? It looks like line 794 and line 796 are the same?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The called function is named similar but different. I clarified it now by choosing a different name.
@BridgeAR I'm OK with patch for this but would be interested in some other @nodejs/tsc opinions. Technically, anything that introduces a |
Left some nits on the new doc changes, but I really like the direction you went with it. 👍 |
I updated it and also added a independent commit to clarify how the RegExp actually works. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM
I would release this as minor. Mainly to give it a bit more time to bake for LTS. |
doc/api/assert.md
Outdated
assert.throws(notThrowing, 'Second'); | ||
// AssertionError [ERR_ASSERTION]: Missing expected exception: Second | ||
|
||
// If you originally intended to match for the error message do this instead: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Please void using informal pronouns like you
in the docs :-)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I rephrased that but I am not really happy with what I came up with
Please read the example below carefully if using a string as the second argument gets considered:
and
If it was intended to match for the error message do this instead:
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Few grammar notes
doc/api/assert.md
Outdated
``` | ||
|
||
Due to the confusing notation it is recommended not to use a string as second |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Comma after notation
as a second argument
- ✂️
at all
- ✂️
otherwise
doc/api/assert.md
Outdated
@@ -740,12 +740,15 @@ assert.throws( | |||
|
|||
Validate error message using [`RegExp`][]: | |||
|
|||
Using a regular expression runs `.toString` on the error object and will |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Needs a comma after object
doc/api/assert.md
Outdated
@@ -767,17 +770,41 @@ assert.throws( | |||
|
|||
Note that `error` can not be a string. If a string is provided as the second | |||
argument, then `error` is assumed to be omitted and the string will be used for | |||
`message` instead. This can lead to easy-to-miss mistakes: | |||
`message` instead. This can lead to easy-to-miss mistakes. Please read the | |||
example below carefully if you intend to use a string as second argument: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
as a second argument
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would think it should be more like as the second argument
since there can only be one
doc/api/assert.md
Outdated
@@ -767,17 +770,41 @@ assert.throws( | |||
|
|||
Note that `error` can not be a string. If a string is provided as the second | |||
argument, then `error` is assumed to be omitted and the string will be used for | |||
`message` instead. This can lead to easy-to-miss mistakes: | |||
`message` instead. This can lead to easy-to-miss mistakes. Please read the | |||
example below carefully if you intend to use a string as second argument: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would think it should be more like as the second argument
since there can only be one
I addressed the comments but I am not that happy with all the changes. So it would be nice to get another look at the sentences that contained a |
5847dc0
to
fcf02ed
Compare
@BridgeAR I think this should be using |
@maclover7 I intentionally used that as it should only verify that the rebase was fine. It takes ages to run a full CI for changes that absolutely behave the same on all platforms and there is no point in doing that out of my perspective. |
PTAL |
This does not land cleanly on v9.x, would someone be willing to backport? |
Throw a TypeError in case a error message is provided in the second argument and a third argument is present as well. This is clearly a mistake and should not be done. PR-URL: nodejs#17585 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Evan Lucas <evanlucas@me.com>
It was not clear why the error name is actually also tested for when using a regular expression. This is now clarified. PR-URL: nodejs#17585 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Evan Lucas <evanlucas@me.com>
Backport opened in #19230 |
Throw a TypeError in case a error message is provided in the second argument and a third argument is present as well. This is clearly a mistake and should not be done. Backport-PR-URL: #19230 PR-URL: #17585 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Evan Lucas <evanlucas@me.com>
It was not clear why the error name is actually also tested for when using a regular expression. This is now clarified. Backport-PR-URL: #19230 PR-URL: #17585 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Evan Lucas <evanlucas@me.com>
Throw a TypeError in case a error message is provided in the second argument and a third argument is present as well. This is clearly a mistake and should not be done. Backport-PR-URL: #19230 PR-URL: #17585 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Evan Lucas <evanlucas@me.com>
It was not clear why the error name is actually also tested for when using a regular expression. This is now clarified. Backport-PR-URL: #19230 PR-URL: #17585 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Evan Lucas <evanlucas@me.com>
Requested backport to 8.x in #19230 |
Throw a TypeError in case a error message is provided in the second argument and a third argument is present as well. This is clearly a mistake and should not be done. PR-URL: nodejs#17585 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Evan Lucas <evanlucas@me.com>
Throw a TypeError in case a error message is provided in the second argument and a third argument is present as well. This is clearly a mistake and should not be done. Backport-PR-URL: #23223 PR-URL: #17585 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com> Reviewed-By: Evan Lucas <evanlucas@me.com>
Throw a TypeError in case a error message is provided in the second
argument and a third argument is present as well.
This is clearly a mistake and should not be done.
CI https://ci.nodejs.org/job/node-test-pull-request/12015/
Checklist
make -j4 test
(UNIX), orvcbuild test
(Windows) passesAffected core subsystem(s)
assert