Re: [PATCH] tests: document CMP/PRE/POST in unit test module

[Bernhard Voelker]

Hi Assaf,

On 04/02/2013 06:11 PM, Assaf Gordon wrote:
> Bernhard Voelker wrote, On 04/02/2013 04:03 AM:
> Thanks for the quick reply.

thanks for the quick response.

> Here's a better patch.

> diff --git a/tests/Coreutils.pm b/tests/Coreutils.pm
> index 71b1516..661fce4 100644
> --- a/tests/Coreutils.pm
> +++ b/tests/Coreutils.pm
> @@ -54,8 +54,12 @@ defined $ENV{DJDIR}
>  # I/O spec: a hash ref with the following properties
>  # ================
>  # - one key/value pair
> -# - the key must be one of these strings: IN, OUT, ERR, AUX, CMP, EXIT
> +# - the key must be one of these strings: IN, IN_PIPE, OUT, ERR, AUX, CMP,
> +#                                         EXIT, PRE, POST
>  # - the value must be a file spec
> +# {IN  => 'data'}    Create file containing 'data'. The filename will be
> +#                    appended as the last parameter on the command-line.

Coreutils uses double-blank-after-dot where possible: s/\. The/.  The/
And we prefer "file name" over "filename".
What about a more simple description like this?

+# {IN  => 'data'}    Create temporary input file containing 'data', and pass
+#                    its name as the last parameter to the program.


> +# {IN_PIPE => 'data'} Send 'data' as input from stdin.

Fine.


Re. CMP usage:

>> 2 notes:
>> * According to the code, instead of a plain string, 'data' can also be a 
>> HASH.
>> * If the file name is '@AUX@', then it is replaced.
> 
> I do not fully understand those uses, so I can't really explain them.
> When are these useful?

There does not seem to be a use case for hash references, so I don't know
either (and therefore that maybe doesn't even work).

For the '@AUX@' syntax, the only use is in tests/dd/skip-seek.pl ... and
hmm, from reading it, I'd say that test and the @AUX@ syntax is not as
useful as it could be, e.g. in the following test, CMP verifies that the
name of the output file name is 'zy123utsrqponmlkji' (which is already
defined by the AUX=> definition:

     [
      'sk-seek1',
      qw (bs=1 skip=1 seek=2 conv=notrunc count=3 status=noxfer of=@AUX@ < ),
      {IN=> '0123456789abcdef'},
      {AUX=> 'zyxwvutsrqponmlkji'},
      {OUT=> ''},
      {ERR=> "3+0 records in\n3+0 records out\n"},
      {CMP=> ['zy123utsrqponmlkji', {'@AUX@'=> undef}]},
     ],

It's like that since the initial implementation in 2000
(6cfcd41e1a49ee16b7a97201bad2d8fba6052e46 and
2d354c5a2e44902ffc5336199973200c3cf02861).

I guess the initial idea behind it was to prove that the content
of the output file is '123'.
WDYT?

Have a nice day,
Berny