TIP 522: Test error codes with Tcltest

Login
Author:		Peter Spjuth <peter.spjuth@gmail.com>
State:		Final
Type:		Project
Vote:		Done
Created:	22-Oct-2018
Post-History:
Tcl-Version:	8.7
Vote-Results:	8/0/0 accepted
Votes-For:	KBK, SL, AF, DGP, FV, DKF, AK, JN
Votes-Against:	none
Votes-Present:	none
Tcl-Branch:	tip-522
Keywords:	tcltest, error codes

Abstract

Proposes a new test option to test error codes (not to be confused with return codes).

Rationale

All or most core commands have error codes with their errors. With the addition of try and throw, error codes are now an integral part of the error ecosystem. However, testing them is a bit clunky and few commands have tests for them.

The most obvious test usage for them are exact matching and prefix matching, both easily done with a glob pattern since error codes do not have special characters.

Having an error code check without requiring return code error makes no sense so as a convenience -returnCodes 1 is set if not present. A user that for some reason wants to allow more than 1 may still do so.

Specification

Add a new option, -errorCode, to the test command in the tcltest package. This is a glob pattern and defaults to "*". When an error occurs in the body evaluation, the pattern is tested against the error code from test execution. When -errorCode is given, and -returnCodes does not include 1 (or error, equivalently) so it is impossible for a valid error code to be generated, -returnCodes is set to 1.

Example

This:

test dict-4.13 {dict replace command: type check is mandatory} -body {
    dict replace { a b c d e }
} -returnCodes error -result {missing value to go with key}
test dict-4.13a {dict replace command: type check is mandatory} {
    catch {dict replace { a b c d e }} -> opt
    dict get $opt -errorcode
} {TCL VALUE DICTIONARY}

is replaced by this:

test dict-4.13 {dict replace command: type check is mandatory} -body {
    dict replace { a b c d e }
} -errorCode {TCL VALUE DICTIONARY} -result {missing value to go with key}

Copyright

This document has been placed in the public domain.