diff options
| author | Mike Pennisi <mike@mikepennisi.com> | 2016-03-13 13:26:10 -0400 |
|---|---|---|
| committer | Mike Pennisi <mike@mikepennisi.com> | 2016-10-19 15:24:21 -0400 |
| commit | 0d4a07ba8c179551fde110a738241da69217db52 (patch) | |
| tree | 824dfff037fe83eb8046adb25b06659dbd026a10 | |
| parent | 2915fe8527d06c2cb1a4780eeac37ef743c02d9f (diff) | |
Update documentation
| -rw-r--r-- | CONTRIBUTING.md | 15 | ||||
| -rw-r--r-- | INTERPRETING.md | 28 |
2 files changed, 35 insertions, 8 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4b50e637e..25d1b05f4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -70,14 +70,21 @@ Eg: Object.prototype.toString - '[object Null]' will be returned when 'this' value is null #### negative -**negative**: [regex] +**negative**: [dictionary containing **phase** and **type**] This means the test is expected to throw an error of the given type. If no error is thrown, a test failure is reported. -If an error is thrown, it is implicitly converted to a string. The second parameter is a regular expression that will be matched against this string. If the match fails, a test failure is reported. Thus the regular expression can match either the error name, or the message contents, or both. +- **type**- If an error is thrown, it is implicitly converted to a string. In order for the test to pass, this value must match the name of the error constructor. +- **phase** - Negative tests whose **phase** value is "early" must produce the specified error prior to executing code. The value "runtime" dictates that the error is expected to be produced as a result of executing the test code. For best practices on how to use the negative tag please see Handling Errors and Negative Test Cases, below. +For example: + + negative: + phase: early + type: ReferenceError + #### es5id **es5id**: [es5-test-id] @@ -181,7 +188,9 @@ Expectations for **parsing errors** should be declared using [the `negative` fro ```javascript /*--- -negative: SyntaxError +negative: + phase: early + type: SyntaxError ---*/ // This `throw` statement guarantees that no code is executed in order to diff --git a/INTERPRETING.md b/INTERPRETING.md index da51fcee3..e1f892df4 100644 --- a/INTERPRETING.md +++ b/INTERPRETING.md @@ -117,20 +117,38 @@ structured as [YAML](http://yaml.org/). ### `negative` These tests are expected to generate an uncaught exception. The value of this -attribute is the name of the constructor of the expected error. If a test -configured with the `negative` attribute completes without throwing an -exception, or if the name of the thrown exception's constructor does not match -the specified constructor name, the test must be interpreted as "failing." +attribute is a YAML dictonary with two keys: + +- `phase` - the stage of the test interpretation process that the error is + expected to be produced; either "early" (meaning, "prior to evaluation") or + "runtime" (meaning, "during evaluation"); in the case of "early", additional + test transformation may be required--see below +- `type` - the name of the constructor of the expected error + +If a test configured with the `negative` attribute completes without throwing +an exception, or if the name of the thrown exception's constructor does not +match the specified constructor name, or if the error occurs at a phase that +differs from the indicated phase, the test must be interpreted as "failing." *Example:* ```js /*--- -negative: ReferenceError +negative: + phase: runtime + type: ReferenceError ---*/ unresolvable; ``` +Consumers are free to assert the "early" phase as they see fit. + +For example, it is possible to insert a `throw` statement with a unique error +type at the beginning of the test file. In this case, the statement should be +inserted *after* the directive desribed in the section titled "Strict Mode" +(where appropriate), though it must *not* be inserted for tests containing the +"raw" flag. + ### `includes` One or more files whose content must be evaluated in the test realm's global |