From add5995203cabe3c7d16313de5bd90c092b66843 Mon Sep 17 00:00:00 2001 From: Peter Tseng Date: Sun, 12 Feb 2017 15:38:52 -0800 Subject: [PATCH 1/3] README: explain principles for descriptions --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 93699d8133..67b334afa4 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,8 @@ variations. Each test case has the the following keys: - description: which will be used to name each generated test + - The description should not simply explain **what** each case is (that is redundant information) + - The description should explain **why** each case is there. For example, what kinds of implementation mistakes might this case help us find? - 'variable names': one or more variable names with values which will be passed to the solution method - expected: the expected result (this would be -1 when we expect an exception) - msg: a nice message for the failing case From 1f238c41210af1cde8621d506eaef1adec3c7aaa Mon Sep 17 00:00:00 2001 From: Peter Tseng Date: Sun, 12 Feb 2017 15:41:59 -0800 Subject: [PATCH 2/3] README: Use null and new error value defined in #401 We would also need to clean up remaining instances, so this is necessary but not sufficient for #401. This relates to discussions in #338 about how to distinguish between `null` and error cases. --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 67b334afa4..d5c94263eb 100644 --- a/README.md +++ b/README.md @@ -50,7 +50,11 @@ Each test case has the the following keys: - The description should not simply explain **what** each case is (that is redundant information) - The description should explain **why** each case is there. For example, what kinds of implementation mistakes might this case help us find? - 'variable names': one or more variable names with values which will be passed to the solution method -- expected: the expected result (this would be -1 when we expect an exception) +- expected: the expected result + - if the input is valid but there is no result for the input, the value at `"expected"` should be `null`. + - if an error is expected (because the input is invalid, or any other reason), the value at `"expected"` should be an object containing exactly one property, `"error"`, whose value is a string. + - The string should explain why the error would occur. + - A particular track's implementation of the exercise **need not** necessarily check that the error includes that exact string as the cause, depending on what is idiomatic in the language (it may not be idiomatic to check strings for error messages). - msg: a nice message for the failing case ## Automated Tests From 9afe4c12c570f97dc280de547932a97c18348576 Mon Sep 17 00:00:00 2001 From: Peter Tseng Date: Sun, 12 Feb 2017 15:46:49 -0800 Subject: [PATCH 3/3] README: remove msg This isn't used anymore. Grep for `msg` and the only instance seen is rail-fence-cipher, and it's used as an input in that case,o Evidence of our past intent to remove the `msg` key: * #163 * [2dee540593776ba138e89670b1aaf611db631da5][cmt1] * [1483fe9fafcc74f9e09b518cf0de9065047d3eb7][cmt2] [cmt1]: https://github.com/exercism/x-common/commit/2dee540593776ba138e89670b1aaf611db631da5 [cmt2]: https://github.com/exercism/x-common/commit/1483fe9fafcc74f9e09b518cf0de9065047d3eb7 --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index d5c94263eb..f5f0a615d3 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,6 @@ Each test case has the the following keys: - if an error is expected (because the input is invalid, or any other reason), the value at `"expected"` should be an object containing exactly one property, `"error"`, whose value is a string. - The string should explain why the error would occur. - A particular track's implementation of the exercise **need not** necessarily check that the error includes that exact string as the cause, depending on what is idiomatic in the language (it may not be idiomatic to check strings for error messages). -- msg: a nice message for the failing case ## Automated Tests