Re: Contribution to Perldoc for TestLib module in Postgres

On Fri, Jul 26, 2019 at 09:51:34AM -0400, Andrew Dunstan wrote:
> I've fixed the bitrot and some other infelicities on this patch. It's
> not commitable yet but I think it's more reviewable.

Thanks, I had a look at this version.

+ # Returns the real directory for a virtual path directory under msys
+ real_dir(dir)
real_dir() is no more.

perl2host() is missing.

+ #TODO
+ command_like_safe(cmd, expected_stdout, test_name)
[...]
+=pod
+
+=item command_like_safe(cmd, expected_stdout, test_name)
+
+TODO
+
+=cut
Update not to miss.

+Runs the command which is passed as argument to the function. On failure it
+abandons further tests and exits the program.
"On failure the test suite exits immediately."

I think that the SYNOPSIS could be shaped better. As of now it is a
simple succession of the same commands listed without any link to each
other, which is contrary for example to what we do in PostgresNode.pm,
where it shows up a set of small examples which are useful to
understand how to shape the tests and the possible interactions
between the routines of the module. My take would be to keep it
simple and minimal as TestLib.pm is the lowest level of our TAP test
infrastructure. So here are some simple suggestions, and we could go
with this set to begin with:
# Test basic output of a command.
program_help_ok('initdb');
program_version_ok('initdb');
program_options_handling_ok('initdb');

# Test option combinations
command_fails(['initdb', '--invalid-option'],
'command fails with invalid option');
my $tempdir = TestLib::tempdir;
command_ok('initdb', '-D', $tempdir);

Another thing is that the examples should not overlap with what
PostgresNode.pm presents, and that it is not necessary to show up all
the routines. It also makes little sense to describe in the synopsis
the routines in a way which duplicates with the descriptions on top of
each routine.
--
Michael