NAME
Test::Consul - Run a Consul server for testing
SYNOPSIS
use Test::Consul;
# succeeds or dies
my $tc = Test::Consul->start;
my $consul_baseurl = "http://127.0.0.1:".$tc->port;
# do things with Consul here
# kill test server (or let $tc fall out of scope, destructor will clean up)
$tc->end;DESCRIPTION
This module starts and stops a standalone Consul instance. It's designed to be used to help test Consul-aware Perl programs.
It's assumed that you have Consul 0.6.4 installed somewhere.
ARGUMENTS
port
The TCP port for HTTP API endpoint. Consul's default is 8500, but this defaults to a random unused port.
serf_lan_port
The TCP and UDP port for the Serf LAN. Consul's default is 8301, but this defaults to a random unused port.
serf_wan_port
The TCP and UDP port for the Serf WAN. Consul's default is 8302, but this defaults to a random unused port.
server_port
The TCP port for the RPC Server address. Consul's default is 8300, but this defaults to a random unused port.
node_name
The name of this node. If not provided, one will be generated.
datacenter
The name of the datacenter. If not provided, one will be generated.
enable_acls
Set this to true to enable ACLs. Note that Consul ACLs changed substantially in Consul 1.4, and Test::Consul has not yet been updated to support them. If you try to enable them with Consul 1.4+, Test::Consul will croak. See https://github.com/robn/Test-Consul/issues/7 for more info.
acl_default_policy
Set this to either allow or deny. The default is allow. See https://www.consul.io/docs/agent/options.html#acl_default_policy for more information.
acl_master_token
If "enable_acls" is true then this token will be used as the master token. By default this will be 01234567-89AB-CDEF-GHIJ-KLMNOPQRSTUV.
enable_acls
Set this to true to enable remote execution (off by default since Consul 0.8.0)
bin
Location of the consul binary. If not provided then the binary will be retrieved from "found_bin".
datadir
Directory for Consul's data store. If not provided, the -dev option is used and no datadir is used.
ATTRIBUTES
running
Returns true if "start" has been called and "stop" has not been called.
METHODS
start
# As an object method:
my $tc = Test::Consul->new(%args);
$tc->start();
# As a class method:
my $tc = Test::Consul->start(%args);Starts a Consul instance. This method can take a moment to run, because it waits until Consul's HTTP endpoint is available before returning. If it fails for any reason an exception is thrown. In this way you can be sure that Consul is ready for service if this method returns successfully.
stop
$tc->stop();Kill the Consul instance. Graceful shutdown is attempted first, and if it doesn't die within a couple of seconds, the process is killed.
This method is also called if the instance of this class falls out of scope.
join
my $tc1 = Test::Consul->start;
my $tc2 = Test::Consul->start(datacenter => $tc1);
$tc1->wan_join($tc2);Perform a join to another Test::Consul instance. Use this to test Consul applications that operate across nodes.
wan_join
my $tc1 = Test::Consul->start;
my $tc2 = Test::Consul->start;
$tc1->wan_join($tc2);Perform a WAN join to another Test::Consul instance. Use this to test Consul applications that operate across datacenters.
CLASS METHODS
See also "start" which acts as both a class and instance method.
found_bin
Return the value of the CONSUL_BIN env var, if set, or uses File::Which to search the system for an installed binary. Returns undef if no consul binary could be found.
skip_all_if_no_bin
Test::Consul->skip_all_if_no_bin;This class method issues a skip_all on the main package if the consul binary could not be found ("found_bin" returns false).
found_version
Return the version of the consul binary, by running the binary return by "found_bin" with the version argument. Returns 0 if the version can't be determined.
skip_all_unless_version
Test::Consul->skip_all_unless_version($minver, [$maxver]);This class method issues a skip_all on the main package if the consul binary is not between $minver and $maxvar (exclusive).
SEE ALSO
Consul - Consul client library. Uses Test::Consul in its test suite.
SUPPORT
Bugs / Feature Requests
Please report any bugs or feature requests through the issue tracker at https://github.com/robn/Test-Consul/issues. You will be notified automatically of any progress on your issue.
Source Code
This is open source software. The code repository is available for public review and contribution under the terms of the license.
https://github.com/robn/Test-Consul
git clone https://github.com/robn/Test-Consul.gitAUTHORS
Rob Norris <robn@despairlabs.com>
CONTRIBUTORS
Aran Deltac <bluefeet@gmail.com>
Matthew Horsfall <wolfsage@gmail.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2015 by Rob N ★ and was supported by FastMail Pty Ltd.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.