README.md

Perl-based TAP tests

test/perl/ contains shared infrastructure that's used by Perl-based tests across the source tree

The tests are invoked via perl's prove command. By default every test in the t/ subdirectory is run. Individual test(s) can be run instead by passing something like PROVE_TESTS="t/001_testname.pl t/002_othertestname.pl" to make.

You should prefer to write tests using pg_regress, or isolation tester specs, if possible.

Note that all tests and test tools should have perltidy run on them using perltidy, for example:

perltidy --profile=$TS_SRC_DIR/.perltidyrc /path/to/taptest

Writing tests

Tests are written using Perl's Test::More with some PostgreSQL-specific infrastructure from src/test/perl providing node management, support for invoking psql to run queries and get results, etc. You should read the documentation for Test::More before trying to write tests.

The PG specific infrastructure has been extended via the TimescaleNode class in this directory to add timescale specific configuration parameters and some often used helper functions.

Test scripts in the t/ subdirectory of a suite are executed in alphabetical order.

Each test script should begin with:

    use strict;
    use warnings;
    use TimescaleNode;
    use TestLib;
    # Replace with the number of tests to execute:
    use Test::More tests => 1;

then it will generally need to set up one or more nodes, run commands against them and evaluate the results. For example:

    my $node = get_new_ts_node('access_node');
    $node->init;
    $node->start;

    my $ret = $node->safe_psql('postgres', 'SELECT 1');
    is($ret, '1', 'SELECT 1 returns 1');

    $node->stop('fast');

Test::More::like entails use of the qr// operator. Avoid Perl 5.8.8 bug #39185 by not using the "$" regular expression metacharacter in qr// when also using the "/m" modifier. Instead of "$", use "\n" or "(?=\n|\z)".

Read the Test::More documentation for more on how to write tests:

    perldoc Test::More

For available PostgreSQL-specific test methods and some example tests read the perldoc for the test modules, e.g.:

    cd $COMMUNITY_PG_SRCS
    perldoc src/test/perl/PostgresNode.pm

Required Perl

Tests must run on perl 5.8.0 and newer. perlbrew is a good way to obtain such a Perl; see http://perlbrew.pl .

Just install and

    perlbrew --force install 5.8.0
    perlbrew use 5.8.0
    perlbrew install-cpanm
    cpanm install IPC::Run

then re-run configure to ensure the correct Perl is used when running tests. To verify that the right Perl was found:

    grep ^PERL= config.log