# HG changeset patch
# User Jordi Gutiérrez Hermoso <jordigh@octave.org>
# Date 1362433642 18000
# Node ID 7fe4ea72ba4dd919192b90eda68767f5d737ff3c
# Parent  8a8e04aa3c98f81e787a3b128796633127c71e73
doc: Update 'test' and "fail" documentation

With thanks to Iain Cunningham <iain.cunningham@eese.co.uk>

* testfun.txi: Add more examples on how to use fail, assert, error,
  and xtest.

* fail.m: Explain more the kind of input that fail needs and how it
  behaves.

diff -r 8a8e04aa3c98 -r 7fe4ea72ba4d doc/interpreter/testfun.txi
--- a/doc/interpreter/testfun.txi	Thu Feb 21 15:18:02 2013 -0500
+++ b/doc/interpreter/testfun.txi	Mon Mar 04 16:47:22 2013 -0500
@@ -267,6 +267,45 @@
 @end group
 @end example
 
+@noindent
+The following trivial code snippet provides examples for the use of
+fail, assert, error and xtest:
+
+@example
+@group
+function output = must_be_zero (@var{input})
+  if (@var{input} != 0)
+    error ("Non-zero input!")
+  endif
+  output = input;
+endfunction
+
+%!fail ("must_be_zero (1)");
+%!assert (must_be_zero (0), 0);
+%!error <Non-zero> must_be_zero (1);
+%!xtest error ("This code generates an error");
+@end group
+@end example
+
+@noindent
+When putting this a file @file{must_be_zero.m}, and running the test, we see
+
+@example
+@group
+test must_be_zero verbose
+
+@result{}
+>>>>> /path/to/must_be_zero.m
+  ***** fail ("must_be_zero (1)");
+  ***** assert (must_be_zero (0), 0);
+  ***** error <Non-zero> must_be_zero (1);
+  ***** xtest error ("This code generates an error");
+!!!!! known failure
+This code generates an error
+PASSES 4 out of 4 tests (1 expected failures)
+@end group
+@end example
+
 @subsubheading Block type summary:
 
 @table @code
diff -r 8a8e04aa3c98 -r 7fe4ea72ba4d scripts/testfun/fail.m
--- a/scripts/testfun/fail.m	Thu Feb 21 15:18:02 2013 -0500
+++ b/scripts/testfun/fail.m	Mon Mar 04 16:47:22 2013 -0500
@@ -29,10 +29,19 @@
 ## is a string and if @var{code} runs successfully, the error produced is:
 ##
 ## @example
-##           expected error but got none
+##           expected error <.> but got none
 ## @end example
 ##
-## If the code fails with a different error, the message produced is:
+##
+## Code must be in the form of a string that may be passed by
+## @code{fail} to the Octave interpreter via the @code{evalin} function,
+## that is, a (quoted) string constant or a string variable.
+##
+## If called with two arguments, the behavior is similar to
+## @code{fail (@var{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:
 ##
 ## @example
 ## @group