https://github.com/hatena/p5-test-www-stub

https://github.com/hatena/p5-test-www-stub

perl testing

Last synced: 9 months ago
JSON representation

• Host: GitHub
• URL: https://github.com/hatena/p5-test-www-stub
• Owner: hatena
• License: other
• Created: 2015-02-23T04:59:24.000Z (over 11 years ago)
• Default Branch: main
• Last Pushed: 2025-10-21T06:39:17.000Z (9 months ago)
• Last Synced: 2025-10-24T22:37:35.802Z (9 months ago)
• Topics: perl, testing
• Language: Perl
• Size: 91.8 KB
• Stars: 3
• Watchers: 5
• Forks: 6
• Open Issues: 6
• Metadata Files:
  • Readme: README.md
  • Changelog: Changes
  • License: LICENSE

Awesome Lists containing this project

README

          
[![Actions Status](https://github.com/hatena/p5-Test-WWW-Stub/workflows/test/badge.svg)](https://github.com/hatena/p5-Test-WWW-Stub/actions)

# NAME

Test::WWW::Stub - Block and stub specified URL for LWP

# SYNOPSIS

    # External http(s) access via LWP is blocked by just declaring 'use Test::WWW::Stub';

    # Note that 'require Test::WWW::Stub' or 'use Test::WWW::Stub ()' doesn't block external access.

    use Test::WWW::Stub;

    my $ua = LWP::UserAgent->new;

    my $stubbed_res = [ 200, [], ['okay'] ];

    {

        my $guard = Test::WWW::Stub->register(q, $stubbed_res);

        is $ua->get('http://example.com/TEST')->content, 'okay';

    }

    isnt $ua->get('http://example.com/TEST')->content, 'okay';

    {

        # registering in void context doesn't create guard.

        Test::WWW::Stub->register(q, $stubbed_res);

        is $ua->get('http://example.com/HOGE')->content, 'okay';

    }

    is $ua->get('http://example.com/HOGE')->content, 'okay';

    {

        # You can also use regexp for uri

        my $guard = Test::WWW::Stub->register(qr<\A\Qhttp://example.com/MATCH/\E>, $stubbed_res);

        is $ua->get('http://example.com/MATCH/hogehoge')->content, 'okay';

    }

    {

        # you can unstub and allow external access temporary

        my $unstub_guard = Test::WWW::Stub->unstub;

        # External access occurs!!

        ok $ua->get('http://example.com');

    }

    my $last_req = Test::WWW::Stub->last_request; # Plack::Request

    is $last_req->uri, 'http://example.com/MATCH/hogehoge';

    Test::WWW::Stub->requested_ok('GET', 'http://example.com/TEST'); # passes

# DESCRIPTION

Test::WWW::Stub is a helper module to block external http(s) request and stub some specific requests in your test.

Because this modules uses [LWP::Protocol::PSGI](https://metacpan.org/pod/LWP%3A%3AProtocol%3A%3APSGI) internally, you don't have to modify target codes using [LWP::UserAgent](https://metacpan.org/pod/LWP%3A%3AUserAgent).

# METHODS

- `register`

        my $guard = Test::WWW::Stub->register( $uri_or_re, $app_or_res );

    Registers a new stub for URI `$uri_or_re`.

    If called in void context, it simply registers the stub.

    Otherwise,it returns a new guard which drops the stub on destroyed.

    `$uri_or_re` is either an URI string or a compiled regular expression for URI.

    `$app_or_res` is a PSGI response array ref, or a code ref which returns a PSGI response array ref.

    If `$app_or_res` is a code ref, requests are passed to the code ref following syntax:

        my $req = Plack::Request->new($env);

        $app_or_res->($env, $req);

    Once registered, `$app_or_res` will be return from LWP::UserAgent on requesting certain URI matches `$uri_or_re`.

- `requested_ok`

        Test::WWW::Stub->requested_ok($method, $uri);

    Passes when `$uri` has been requested with `$method`, otherwise fails and dumps requests handled by Test::WWW::Stub.

    This method calls `Test::More::ok` or `Test::More::diag` internally.

- `requests`

        my @requests = Test::WWW::Stub->requests;

    Returns an array of [Plack::Request](https://metacpan.org/pod/Plack%3A%3ARequest) which is handled by Test::WWW::Stub.

- `last_request`

        my $last_req = Test::WWW::Stub->last_request;

    Returns a Plack::Request object last handled by Test::WWW::Stub.

    This method is same as `[Test::WWW::Stub->requests]->[-1]`.

- `last_request_for`

        my $last_req = Test::WWW::Stub->last_request_for($method, $uri);

    Returns a `Plack::Request` object last handled by Test::WWW::Stub and matched given HTTP method and URI.

- `clear_requests`

        Test::WWW::Stub->clear_requests;

    Clears request history of Test::WWW::Stub.

    `[Test::WWW::Stub->requests]` becomes empty just after this method called.

- `unstub`

        my $unstub_guard = Test::WWW::Stub->unstub;

    Unregister stub and enables external access, and returns a guard object which re-enables stub on destroyed.

    In constrast to `register`, this method doesn't work when called in void context.

- `import`

        Test::WWW::Stub->import(%options)

        or

        use Test:::WWW::Stub

    This `%options` are equivalent to the options of `LWP::Protocol::PSGI->register(%options)`. For example, the options can be set as follows:

        use Test::WWW::Stub (

            uri => sub {

                my $uri = shift;

                $uri ne 'http://localhost:9200'

            }

        );

- `unimport`

        Test::WWW::Stub->unimport

        or

        no Test::WWW::Stub;

    Delete the stubbed app and stop stubbing. If you need to stub again, import Test::WWW::Stub.

# LICENSE

Copyright (C) Hatena Co., Ltd.

This library is free software; you can redistribute it and/or modify

it under the same terms as Perl itself.

# AUTHOR

Asato Wakisaka 

Original implementation written by suzak.