Re: TDD in Octave, guidance/tutorial?

[IainIsm]

On 5 February 2013 13:59, Jordi Gutiérrez Hermoso-2 [via Octave]
<[hidden email]> wrote:
> On 5 February 2013 07:01, IainIsm <[hidden email]> wrote:
>
>> On 4 February 2013 18:08, Jordi Gutiérrez Hermoso-2 [via Octave]
[snip]
>> In the meantime, from the documentation at
>> http://www.gnu.org/software/octave/doc/interpreter/Test-Functions.html I
>> was
>> expecting that the following MWE would test successfully:
>
> The following what?

Sorry, minimum working example (shortest bit of code that I could
create that would exhibit the behaviour I was seeing).

> Instead, the fail() function expects a string, like so:
>
>     fail("mustBeZero(1)")

Ah-ha!  Thank you!  I hadn't understood the significance of "Note that
code is a string" in the documentation.

>> (Perhaps what I've found is a problem with the clarity of the
>> documentation?)
>
> Suggest alternative wording, and I will incorporate it into the
> manual.

Between:
*****
If you want to temporarily disable a test block, put # in place of the
block type. This creates a comment block which is echoed in the log
file but not executed. For example:

     %!#demo
     %! t = [0:0.01:2*pi]; x = sin (t);
     %! plot (t, x);
     %! # you should now see a sine wave in your figure window"
*****

and:
*****
"Block type summary:"
*****

I would insert:

*****
The following trivial code snippet provides examples for the use of
fail, assert, error and xtest:

function output = mustBeZero(input)
if (input ~= 0)
  error('Non-zero input!')
end
output = input;

%!fail('mustBeZero(1)');
%!assert(mustBeZero(0), 0);
%!error <Non-zero> mustBeZero(1);
%!xtest error('This code generates an error');

Output in response to:

            test mustBeZero verbose

Is:

            >>>>><path to>\mustBeZero.m
              ***** fail('mustBeZero(1)');
              ***** assert(mustBeZero(0), 0);
              ***** error <Non-zero> mustBeZero(1);
              ***** xtest fail(error('This code generates an error'));
            !!!!! known failure
            This generates an error
            PASSES 4 out of 4 tests (1 expected failures)
*****

And then in the section for fail:

Change:
*****
— Function File: fail (code)
— Function File: fail (code, pattern)
— Function File: fail (code, 'warning', pattern)
Return true if code fails with an error message matching pattern,
otherwise produce an error. Note that code is a string and if code
runs successfully, the error produced is:

                    expected error but got none
If the code fails with a different error, the message produced is:
*****

To:
*****
— Function File: fail (code)
— Function File: fail (code, pattern)
— Function File: fail (code, 'warning', pattern)

If called with one argument, return true if code fails.  If code runs
successfully, the error produced is:

                    expected error <.> but got none

NOTE: code must be in the form of a string that may be passed by fail
to the Octave interpreter via the evalin function (i.e. a (quoted)
string constant or a string variable).

If called with two arguments, the behavior is similar to fail(code),
except the return value will only be true if code fails with an error
message containing pattern (case sensitive).  If the code fails with a
different error to that given in pattern, the message produced is:
*****

Thoughts?

On a related note, the documentation for evalin contains the text:
"One example is the fail (‘code’, ‘pattern’) function which evaluates
‘code’ in the caller's context and checks that the error message it
produces matches the given pattern":
http://www.gnu.org/software/octave/doc/interpreter/Evaluation-in-a-Different-Context.html#doc%2devalin

So I'm not totally sure what the convention for showing strings in the
function documentation is (should be?) to make my suggestion above
consistent with the remainder of the documentation.

Thanks for your help,

Iain

---

View this message in context: Re: TDD in Octave, guidance/tutorial?
Sent from the Octave - General mailing list archive at Nabble.com.