granicus.if.org Git - postgresql/blob - src/test/perl/README

   1 Perl-based TAP tests
   2 ====================
   3
   4 src/test/perl/ contains shared infrastructure that's used by Perl-based tests
   5 across the source tree, particularly tests in src/bin and src/test. It's used
   6 to drive tests for backup and restore, replication, etc - anything that can't
   7 really be expressed using pg_regress or the isolation test framework.
   8
   9 The tests are invoked via perl's 'prove' command, wrapped in PostgreSQL
  10 makefiles to handle instance setup etc. See the $(prove_check) and
  11 $(prove_installcheck) targets in Makefile.global. By default every test in the
  12 t/ subdirectory is run. Individual test(s) can be run instead by passing
  13 something like PROVE_TESTS="t/001_testname.pl t/002_othertestname.pl" to make.
  14
  15 You should prefer to write tests using pg_regress in src/test/regress, or
  16 isolation tester specs in src/test/isolation, if possible. If not, check to
  17 see if your new tests make sense under an existing tree in src/test, like
  18 src/test/ssl, or should be added to one of the suites for an existing utility.
  19
  20 Note that all tests and test tools should have perltidy run on them before
  21 patches are submitted, using perltidy --profile=src/tools/pgindent/perltidyrc
  22
  23 Writing tests
  24 -------------
  25
  26 Tests are written using Perl's Test::More with some PostgreSQL-specific
  27 infrastructure from src/test/perl providing node management, support for
  28 invoking 'psql' to run queries and get results, etc. You should read the
  29 documentation for Test::More before trying to write tests.
  30
  31 Test scripts in the t/ subdirectory of a suite are executed in alphabetical
  32 order.
  33
  34 Each test script should begin with:
  35
  36     use strict;
  37     use warnings;
  38     use PostgresNode;
  39     use TestLib;
  40     # Replace with the number of tests to execute:
  41     use Test::More tests => 1;
  42
  43 then it will generally need to set up one or more nodes, run commands
  44 against them and evaluate the results. For example:
  45
  46     my $node = get_new_node('master');
  47     $node->init;
  48     $node->start;
  49
  50     my $ret = $node->safe_psql('postgres', 'SELECT 1');
  51     is($ret, '1', 'SELECT 1 returns 1');
  52
  53     $node->stop('fast');
  54
  55 Test::More::like entails use of the qr// operator.  Avoid Perl 5.8.8 bug
  56 #39185 by not using the "$" regular expression metacharacter in qr// when also
  57 using the "/m" modifier.  Instead of "$", use "\n" or "(?=\n|\z)".
  58
  59 Read the Test::More documentation for more on how to write tests:
  60
  61     perldoc Test::More
  62
  63 For available PostgreSQL-specific test methods and some example tests read the
  64 perldoc for the test modules, e.g.:
  65
  66     perldoc src/test/perl/PostgresNode.pm
  67
  68 Required Perl
  69 -------------
  70
  71 Tests must run on perl 5.8.0 and newer. perlbrew is a good way to obtain such
  72 a Perl; see http://perlbrew.pl .
  73
  74 Just install and
  75
  76     perlbrew --force install 5.8.0
  77     perlbrew use 5.8.0
  78     perlbrew install-cpanm
  79     cpanm install IPC::Run
  80
  81 then re-run configure to ensure the correct Perl is used when running
  82 tests. To verify that the right Perl was found:
  83
  84     grep ^PERL= config.log