The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Test-Varnish-0.03
River stage zero No dependents
++
/ Test::Varnish

NAME

Test::Varnish - Put your Varnish server to the test!

VERSION

Version 0.03

SYNOPSIS

Varnish is a high performance reverse proxy.

This module allows you to perform tests against a varnish server, asserting that a given resource (URL) is cached by varnish or not.

See it as a sort of Test::More extension to test Varnish. This can be useful when you want to test that your varnish setup and configuration works as expected.

Another use for this module would be to poll random webservers to discover who is using Varnish.

    use Test::Varnish;

    plan tests => 2;

    my $test_client = Test::Varnish->new({
        verbose => 1
    });

    $test_client->isnt_cached(
        {
            url => 'http://my.opera.com/community/',
        },
        'My Opera frontpage is not (yet) cached by Varnish'
    );

    $test_client->is_cached(
        {
            url => 'http://www.cnn.com/',
        },
        'Is CNN.com using Varnish?'
    );

FUNCTIONS

new

Class constructor.

Allows you to create a Test::Varnish object. The allowed options are:

verbose

Controls the verbose mode, where additional diagnostic messages (not many, actually) are output together with the test assertions.

Set it to a true value to enable, false to disable.

Example

  use Test::Varnish;

  my $tv = Test::Varnish->new();

or

  use Test::Varnish;

  my $tv = Test::Varnish->new({
      verbose => 1
  });

METHODS

analyze_response

Takes an HTTP::Response object as argument. Examines the response headers to look for the default Varnish header (X-Varnish), to tell you if the response was coming directly from the Varnish cache, or not.

In other words, this tells you if the request was a Varnish cache hit or miss.

is_cached

is_cached() is a test assertion.

Asserts that a given request to a URL with certain headers, and such, is cached by the given Varnish instance.

Needs 2 arguments:

  • \%request

    Request data, as hashref. You can specify:

    url

    The URL where to send the request to

    headers

    Additional HTTP headers, as hashref. See the example. Most probably you will need the Host header for Varnish to direct the request to the appropriate backend. YMMV.

  • $message (optional)

    A message for the test assertion (ex.: Request to the frontpage with cookies should not be cached).

    A default message will be provided if none is passed.

Example

    use Test::Varnish;

    my $tv = Test::Varnish->new();

    $tv->is_cached(
        {
            url => 'http://your-server.your-domain.local',
            headers => {
                Host => 'www.your-domain.local',
                # ...
            }
        }
    );

or:

    use Test::Varnish;

    my $tv = Test::Varnish->new();

    $tv->is_cached(
        {
            url => 'http://192.168.1.100/super/',
            headers => {
                'Host' => 'www.your-domain.local',
                'Accept-Language' => 'it',
            }
        }, 'The super pages should always be cached, also in italian',
    );

isnt_cached

isnt_cached() is a test assertion, exactly the opposite of "is_cached".

Asserts that a given request to a URL is not cached by the queried Varnish instance.

user_agent

Returns a suitable user agent object (currently an LWP::UserAgent instance), that can be used to interact with the varnish instance.

user_agent_string

Defines the default user agent string to be used for the requests issued by the default user agent object returned by "user_agent".

You can subclass Test::Varnish to define your own user agent string. I'm not sure this is 100% reasonable. Maybe.

verbose

Used internally, tells us if we're running in verbose mode. When verbose mode is active, the test assertions methods will output a bunch of diagnostic messages through Test::More::diag().

You can activate the verbose mode by saying:

    my $tv = Test::Varnish->new();
    $tv->verbose(1);

Or, by instantiating the Test::Varnish object with the verbose option, giving it a true value:

    my $tv = Test::Varnish->new({ verbose => 1 });

AUTHOR

Cosimo Streppone, <cosimo at cpan.org>

BUGS

Please report any bugs or feature requests to bug-test-varnish at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Varnish. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Test::Varnish

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2010 Cosimo Streppone, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.