view release on metacpan or  search on metacpan

lib/Test/SSH.pm  view on Meta::CPAN

works running some simple commands there. It would try hard to not
return the details of a server that is not working properly.

=head2 API

The module provides the following methods:

=over 4

=item $sshd = Test::SSH-E<gt>sshd(%opts)

Returns an object that can be queried to obtain the details of an
accesible SSH server. If no server is found or can be launched, undef
is returned.

In case a slave SSH server had been started, it will be killed once
the returned object goes out of scope.

For modules distributed through CPAN or that are going to be tested
on uncontrolled environments, commonly, no options should be
given as the default should already be the right choice.

In any case, these are the accepted options:

=over 4

=item requested_uri =E<gt> $uri

The module looks for a SSH server at the location given.

=item backends =E<gt> \@be

The module has several backend modules, every one implementing a
different approach for finding a SSH server. This argument allows to
select a specific subset of them.

=item path =E<gt> \@path

By default the module looks for SSH program binaries on the path and
on several common directories (i.e. C</opt/*SSH*>). This parameter
allows to change that.

=item timeout =E<gt> $timeout

Timeout used for running commands and stablishing remote
connections. The default is 10s.

=item test_commands =E<gt> \@cmds

When testing a SSH connection the module would try running the
commands given here until any of them succeeds. The defaults is a set
of very common Unix and shell commands (i.e. C<echo> or C<true>).

=item private_dir =E<gt> $dir

Location used to save data bewteen runs (i.e. generated user and host
key pairs).

The default is C<~/.libtest-ssh-perl>

=item private_keys =E<gt> \@key_paths

List of private keys that will be used for login into the remote host.

The default is to look for keys in C<~/.ssh>.

=item logger =E<gt> sub { ... }

Subroutine that will be called to report activity to the user.

The default is to use L<Test::More::diag>.

=item run_server => $bool

Enables/disables the backends that start a new SSH server.

For instance:

  my $sshd = Test::SSH->new(run_server => ($ENV{AUTHOR_TESTING} || $ENV{AUTOMATED_TESTING}));

=item override_server_config => $hash_reference

Key/Value pairs in this hash reference will be used to override the
defaults for the C<sshd_config> file of the C<sshd> server started. If
a value in this hash is undef, the respective key of the server config
will be deleted.

=back

Also, the following environment variables can be used to change the
module behaviour:

=over 4

=item TEST_SSH_TARGET

Target URI. When set, the module will look for the SSH server at the
location given. For instance:

  TEST_SSH_TARGET=ssh://root:12345@ssh.google.com/ perl testing_script.pl

Setting this variable will also dissable launching a custom SSH server
for testing.

=item TEST_SSH_PASSWORD

When set, the value will be used as the login password. For instance:

  TEST_SSH_PASSWORD=12345 perl testing_script.pl

=back

=item $sshd-E<gt>host

Returns the name of the host.

=item $sshd-E<gt>port

Returns the TCP port number where the server is listening.

=item $sshd-E<gt>user