Skip to content

Commit 7a116d4

Browse files
mhdawsonaddaleax
authored andcommitted
doc: add guidance on testing new errors
PR-URL: #14207 Reviewed-By: Refael Ackermann <[email protected]> Reviewed-By: Vse Mozhet Byt <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: James M Snell <[email protected]>
1 parent f237ad5 commit 7a116d4

File tree

1 file changed

+47
-0
lines changed

1 file changed

+47
-0
lines changed

doc/guides/using-internal-errors.md

+47
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,53 @@ for the error code should be added to the `doc/api/errors.md` file. This will
6969
give users a place to go to easily look up the meaning of individual error
7070
codes.
7171

72+
## Testing new errors
73+
74+
When adding a new error, corresponding test(s) for the error message
75+
formatting may also be required. If the messasge for the error is a
76+
constant string then no test is required for the error message formatting
77+
as we can trust the error helper implementation. An example of this kind of
78+
error would be:
79+
80+
```js
81+
E('ERR_SOCKET_ALREADY_BOUND', 'Socket is already bound');
82+
```
83+
84+
If the error message is not a constant string then tests to validate
85+
the formatting of the message based on the parameters used when
86+
creating the error should be added to
87+
`test/parallel/test-internal-errors.js`. These tests should validate
88+
all of the different ways parameters can be used to generate the final
89+
message string. A simple example is:
90+
91+
```js
92+
// Test ERR_TLS_CERT_ALTNAME_INVALID
93+
assert.strictEqual(
94+
errors.message('ERR_TLS_CERT_ALTNAME_INVALID', ['altname']),
95+
'Hostname/IP does not match certificate\'s altnames: altname');
96+
```
97+
98+
In addition, there should also be tests which validate the use of the
99+
error based on where it is used in the codebase. For these tests, except in
100+
special cases, they should only validate that the expected code is received
101+
and NOT validate the message. This will reduce the amount of test change
102+
required when the message for an error changes.
103+
104+
For example:
105+
106+
```js
107+
assert.throws(() => {
108+
socket.bind();
109+
}, common.expectsError({
110+
code: 'ERR_SOCKET_ALREADY_BOUND',
111+
type: Error
112+
}));
113+
```
114+
115+
Avoid changing the format of the message after the error has been created.
116+
If it does make sense to do this for some reason, then additional tests
117+
validating the formatting of the error message for those cases will
118+
likely be required.
72119

73120
## API
74121

0 commit comments

Comments
 (0)