From 4960cc4c194575ef1cc87d65406b4ee6f7bfc06c Mon Sep 17 00:00:00 2001
From: Nazir Bilal Yavuz <byavuz81@gmail.com>
Date: Mon, 21 Jul 2025 11:56:54 +0300
Subject: [PATCH v4 1/2] Add read_file_ends() helper to Utils.pm

The read_file_ends() function reads lines from a file, either from the
head or the tail, based on the provided direction. It takes how many
lines to read as a 'line_count' argument. By default, if the
'PG_TEST_FILE_READ_LINES' environment variable is set, it overrides the
'line_count'. However, the 'force_line_count' argument can be used to
bypass this behavior and force the use of the provided 'line_count'
regardless of the environment variable.

Suggested-by: Michael Paquier <michael@paquier.xyz>
Reviewed-by: Michael Paquier <michael@paquier.xyz>
Discussion: https://postgr.es/m/CAN55FZ1D6KXvjSs7YGsDeadqCxNF3UUhjRAfforzzP0k-cE%3DbA%40mail.gmail.com
---
 src/test/perl/PostgreSQL/Test/Utils.pm | 60 ++++++++++++++++++++++++++
 doc/src/sgml/regress.sgml              |  8 ++++
 2 files changed, 68 insertions(+)

diff --git a/src/test/perl/PostgreSQL/Test/Utils.pm b/src/test/perl/PostgreSQL/Test/Utils.pm
index 85d36a3171e..ac00390f9df 100644
--- a/src/test/perl/PostgreSQL/Test/Utils.pm
+++ b/src/test/perl/PostgreSQL/Test/Utils.pm
@@ -68,6 +68,7 @@ our @EXPORT = qw(
   slurp_file
   append_to_file
   string_replace_file
+  read_file_ends
   check_mode_recursive
   chmod_recursive
   check_pg_config
@@ -590,6 +591,65 @@ sub string_replace_file
 
 =pod
 
+=item read_file_ends(filename, direction, line_count, force_line_count)
+
+Return lines from the head or tail of a given file.
+
+=cut
+
+sub read_file_ends
+{
+	my ($filename, $direction, $line_count, $force_line_count) = @_;
+	my @lines;
+
+	if ($direction ne 'tail' && $direction ne 'head')
+	{
+		die
+		  "read_file_ends(_, direction, _, _) direction should be either 'tail' or 'head'.";
+	}
+
+
+	# If the force_line_count is true, then use the provided line_count.
+	# Otherwise, use the PG_TEST_FILE_READ_LINES environment variable if set.
+	if (!$force_line_count)
+	{
+		my $temp_env_var = $ENV{PG_TEST_FILE_READ_LINES};
+		if (defined $temp_env_var)
+		{
+			$line_count = $temp_env_var;
+		}
+	}
+
+	if ($line_count <= 0)
+	{
+		return;
+	}
+
+	open my $fh, '<', $filename or die "couldn't open file: $filename\n";
+
+	if ($direction eq 'head')
+	{
+		while (my $line = <$fh>)
+		{
+			push @lines, $line;
+			last if $. == $line_count;
+		}
+	}
+	elsif ($direction eq 'tail')
+	{
+		while (my $line = <$fh>)
+		{
+			push @lines, $line;
+			shift @lines if @lines > $line_count;
+		}
+	}
+
+	close $fh;
+	return @lines;
+}
+
+=pod
+
 =item check_mode_recursive(dir, expected_dir_mode, expected_file_mode, ignore_list)
 
 Check that all file/dir modes in a directory match the expected values,
diff --git a/doc/src/sgml/regress.sgml b/doc/src/sgml/regress.sgml
index bf4ffb30576..5e3ea98c767 100644
--- a/doc/src/sgml/regress.sgml
+++ b/doc/src/sgml/regress.sgml
@@ -521,6 +521,14 @@ make check EXTRA_TESTS=numeric_big
     can run <command>diff</command> yourself, if you prefer.)
    </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 the output files. This is useful when test output files
+    are large or contain unnecessary content, allowing the test framework to
+    read only a specified number of lines for comparison.
+   </para>
+
    <para>
     If for some reason a particular platform generates a <quote>failure</quote>
     for a given test, but inspection of the output convinces you that
-- 
2.50.0