From 6dd4ba5558d81b00f431d55dd5c3dfc1d92a0dae Mon Sep 17 00:00:00 2001 From: Ruben Bridgewater Date: Mon, 20 May 2019 00:30:45 +0200 Subject: [PATCH] doc: update assert's validation functions Using `assert.throws()` or `assert.rejects()` in combination with validation function can be very powerful. Using them by returning any value besides `true` makes debugging very difficult though because there's no context or reason why the error validation failed. Thus, it is recommended to throw an error in such cases instead of returning anything besides `true`. --- doc/api/assert.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/doc/api/assert.md b/doc/api/assert.md index 22383a16b62d14..062a6a204c7a42 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -1210,10 +1210,14 @@ assert.throws( () => { throw new Error('Wrong value'); }, - function(err) { - if ((err instanceof Error) && /value/.test(err)) { - return true; - } + (err) => { + assert(err instanceof Error); + assert(/value/.test(err)); + // Returning anything from validation functions besides `true` is not + // recommended. Doing so results in the caught error being thrown again. + // That is mostly not the desired outcome. Throw an error about the specific + // validation that failed instead (as done in this example). + return true; }, 'unexpected error' );