Add PostgreSQL::Test::Cluster::read_head_tail() helper to PostgreSQL/Utils.pm

This function reads the lines from a file and filters its contents to
report its head and tail contents.  The amount of contents to read from
a file can be tuned by the environment variable PG_TEST_FILE_READ_LINES,
that can be used to override the default of 50 lines.  If the file whose
content is read has less lines than two times PG_TEST_FILE_READ_LINES,
the whole file is returned.

This will be used in a follow-up commit to limit the amount of
information reported by some of the TAP tests on failure, where we have
noticed that the contents reported by the buildfarm can be heavily
bloated in some cases, with the head and tail contents of a report being
able to provide enough information to be useful for debugging.

Author: Nazir Bilal Yavuz <byavuz81@gmail.com>
Co-authored-by: Michael Paquier <michael@paquier.xyz>
Discussion: https://postgr.es/m/CAN55FZ1D6KXvjSs7YGsDeadqCxNF3UUhjRAfforzzP0k-cE=bA@mail.gmail.com

1 files changed, 8 insertions, 0 deletions

diff --git a/doc/src/sgml/regress.sgml b/doc/src/sgml/regress.sgml
index fd1e142d559..d80dd46c5fd 100644
--- a/doc/src/sgml/regress.sgml
+++ b/doc/src/sgml/regress.sgml
@@ -917,6 +917,14 @@ PG_TEST_NOCLEAN=1 make -C src/bin/pg_dump check
     <varname>PG_TEST_TIMEOUT_DEFAULT</varname> to a higher number will change
     the default to avoid this.
    </para>
+
+   <para>
+    For certain tests, the environment variable
+    <envar>PG_TEST_FILE_READ_LINES</envar> can be set to limit the number of
+    lines read from large output files (head and tail). This is useful when
+    the test output contains a lot of unnecessary content, allowing the test
+    framework to read only a limited number of lines for its reports.
+   </para>
   </sect2>
 
   </sect1>