doc: note assert.throws() pitfall

[Trott]

Pull Request check-list

• Is the commit message formatted according to [CONTRIBUTING.md][0]?
• Is a documentation update included (if this change modifies
  existing APIs, or introduces new ones)?

Affected core subsystem(s)

doc assert

Description of change

assert.throws() has a pitfall where you may think you are checking error message text when you are not. Document it.

[cjihrig]

LGTM

[jasnell]

LGTM

[Fishrock123]

maybe we could just fix the API?

Check if the function accepts 3 args then turn arg 2 into a regex?

[jasnell]

that would be more likely to break someone and the assertion API is locked. Likely best to improve the documentation and leave it

[Trott]

@Fishrock123 There are several inter-related problems with "fixing" this issue in the API rather than just documenting it. "Fixing" it would be semver-major because it's actually acting as designed so it would be a breaking change for anyone using the second-argument-is-a-string as intended.

Maybe it's not clear from the example I'm giving in the doc, but the issue more typically manifests itself like this:

assert.throws(myFunction, 'I think this is an error message that is being checked, but it is not');

In other words, the problem really isn't that someone sends three arguments with the second one as a string. The typical problem (and the one that struck on a test that @jasnell recently fixed) is when there are just two arguments. If you "fix" the API so that when the second argument is a string then it is the error message to check...then you are breaking things for people who are using the API as intended, which is thus:

assert.throws(myFunction, 'this is a message that will be used by the AssertionError when this assertion fires');

So, even if we "fix" it, at a minimum, we should still document it as in this PR for versions prior to 6.

If we "fix" it, then we're introducing a breaking change into a Locked API. So... ¯_(ツ)_/¯

[Fishrock123]

eh, just document it then

[jasnell]

Landed in 539cede