NAME

Gerrit::Client::Test - test helpers for Gerrit::Client

DESCRIPTION

This package provides various utilities written for testing of the Gerrit::Client package. It is not intended for general use and the interface is subject to change.

Gerrit::Client::Test may be used to install and manage a local Gerrit instance for the purpose of running system tests.

FUNCTIONS

create_mock_command( OPTIONS )

Creates a mock command whose behavior is defined by the content of OPTIONS.

The purpose of this function is to facilitate the testing of code which interacts with possibly failing external processes. This is made clear with an example: to test how a script handles temporary network failures from git, the following code could be used:

create_mock_command(
  name        =>  'git',
  directory   =>  $tempdir,
  sequence    =>  [
    # first two times, simulate the server hanging up for unknown
    # reasons after a few seconds
    { stdout => q{}, stderr => "fatal: The remote end hung up unexpectedly\n",
      exitcode => 2, delay => 3 },
    { stdout => q{}, stderr => "fatal: The remote end hung up unexpectedly\n",
      exitcode => 2, delay => 3 },
    # on the third try, complete successfully
    { stdout => q{}, stderr => q{}, exitcode => 0 },
  ],
);

# make the above mocked git first in PATH...
local $ENV{PATH} = $tempdir . ':' . $ENV{PATH};

# and verify that some code can robustly handle the above errors
# (but warned about them)
my $result;
my ($stdout, $stderr) = capture {
  $result = $git->clone('git://example.com/repo')
};
ok( $result );
is( $stderr,
  "Warning: 3 attempt(s) required to successfully complete git operation\n" );

OPTIONS is a hash or hashref with the following keys:

name

The basename of the command, e.g. `git'.

directory

The directory in which the command should be created, e.g. `/tmp/command-test'.

This should be a temporary directory, because create_mock_command will write some otherwise useless data files to this directory. The caller is responsible for creating and deleting this directory (and prepending it to $ENV{PATH}, if that is appropriate).

sequence

The test sequence which should be simulated by the command.

This is a reference to an array of hashrefs, each of which has these keys:

stdout

Standard output to be written by the command.

stderr

Standard error to be written by the command.

exitcode

The exit code for the command.

delay

Delay, in seconds, to wait after the command has printed its output and before the command exits.

Each time the mock command is executed, the next element in the array is used to determine the command's behavior. For example, with this sequence:

sequence => [
  { stdout => q{},    stderr => "example.com: host not found\n",
    exitcode => 2 },
  { stdout => "OK\n", stderr => q{}, exitcode => 0 },
]

... the first time the command is run, it will print "example.com: host not found" to standard error, and exit with exit code 2 (failure). The second time the command is run, it will print "OK" to standard output, and exit with exit code 0 (success). (It is an error to run the command a third time - if this is done, it will die, noisily).

METHODS

In typical usage, ensure_gerrit_installed would first be called in order to obtain a handle to a local Gerrit instance; afterwards, other methods act in the context of that Gerrit. This means that git and ssh commands are adjusted so that passwordless superuser access is available to the local Gerrit.

Gerrit::Client::Test->ensure_gerrit_installed

Gerrit::Client::Test->ensure_gerrit_installed( OPTIONS )

Installs Gerrit, or checks an existing Gerrit installation, and returns an object representing the Gerrit site.

If no options are provided, an arbitrary version of Gerrit is downloaded and installed to a temporary directory.

OPTIONS is a hashref with the following permitted keys:

dir

Directory in which gerrit should be installed.

Defaults to a new temporary directory, which will be removed when the returned object is destroyed.

war

URL or path to a gerrit.war to use for installation.

Defaults to http://gerrit-releases.storage.googleapis.com/gerrit-2.8.5.war .

user

Username for the initial gerrit user account (account 1000000). This account has administrative privileges.

Defaults to "perl-gerrit-client-test".

ssh_port

http_port

TCP ports for the ssh and http interfaces to this Gerrit site.

Defaults to any unused ports chosen by the operating system.

All of the above described options may also be directly extracted from the returned object, which is a blessed hashref.

ssh_base

ssh_base( USERNAME )

Returns the initial part of the ssh command which should be used when interacting with this Gerrit installation. The command includes options for setting the port number and identity file to allow passwordless access to this Gerrit site.

If USERNAME is given, the command will also contain the USER@HOST argument; otherwise, it must be specified manually. The HOST is always "127.0.0.1".

git( COMMAND )

Runs the given git COMMAND in the context of this gerrit. COMMAND should be a git command with arguments, excluding the leading 'git', as in the following example:

$gerrit->git( 'fetch', 'origin', 'refs/heads/*:refs/remotes/origin/*' );

Returns the exit status of the git command.

git_ok( COMMAND )

Like git, but the command is treated as a test. If the command fails, the test fails and the command's output is printed to the test log.

gerrit( COMMAND )

gerrit( OPTIONS, COMMAND )

Runs the given gerrit COMMAND, via ssh, in the context of this gerrit. COMMAND should be a gerrit command with arguments, excluding the leading 'gerrit', as in the following example:

$gerrit->gerrit( 'create-project', 'testproject' );

OPTIONS may be passed as a hashref with the following keys:

user

Username for the gerrit connection.

Defaults to $gerrit->{user}, which is the first created user and has administrative privileges.

Returns the exit status of the ssh command.

gerrit_ok( COMMAND )

gerrit_ok( OPTIONS, COMMAND )

Like gerrit, but the command is treated as a test. If the command fails, the test fails and the command's output is printed to the test log.

git_test_commit

git_test_commit( MESSAGE )

Create a test commit (an arbitrary, non-empty commit) in the local git repository.

If MESSAGE is given, it is used as the commit message; otherwise, a reasonable default is used.

giturl_base

giturl_base( USER )

Returns the base git URL for this gerrit site.

The URL contains scheme, user, host and port components. By default, $gerrit->{user} is used as the username; this may be overriden by the USER parameter.

The URL has no path component, and hence the full git URL for a given project may be constructed as in the following example:

my $giturl = $gerrit->giturl_base() . '/some/project';
$gerrit->git( 'clone', $giturl );
...

http_url

Returns the base HTTP URL for this gerrit site.

git_ssh_wrapper

Returns the path to a wrapper script for the ssh command. The wrapper script may be used in place of 'ssh' to ensure that the correct setup is used for passwordless access to this gerrit site.

Useful in conjunction with @Gerrit::Client::SSH to allow Gerrit::Client passwordless access to this gerrit:

local @Gerrit::Client::SSH = ( $gerrit->git_ssh_wrapper() );
my $stream = Gerrit::Client::stream_events(
  url => $gerrit->giturl_base(),
  ...
);

git_wrapper

Returns the path to a wrapper script for the git command. The wrapper script may be used in place of 'git' to ensure that the correct setup is used for passwordless access to this gerrit site.

Useful in conjunction with @Gerrit::Client::GIT to allow Gerrit::Client passwordless access to this gerrit:

local @Gerrit::Client::GIT = ( $gerrit->git_wrapper() );
my $stream = Gerrit::Client::stream_events(
  url => $gerrit->giturl_base(),
  ...
);

start_gerrit

Start the gerrit daemon or add a failure to the test log.

stop_gerrit

Stop the gerrit daemon or add a failure to the test log.

gerrit_pid

Returns the PID of the main Gerrit process, if available.

This may return a stale value if Gerrit was terminated unexpectedly.

gerrit_running

Returns 1 if and only if this Gerrit instance appears to be running.

ensure_gerrit_running

Start gerrit only if it is not already running, or add a failure to the test log.

ensure_gerrit_stopped

Stop gerrit only if it is running, or add a failure to the test log.

have_git

Returns true if and only if a functional git command is in PATH.