[Catalyst-dev] RFC: Catalyst::Test::LocalContext

Tue Sep 18 00:32:03 GMT 2007

Hi all,

I often found myself wanting to test some internal aspects of my request
handling in Catalyst or were to lazy to check the full returned HTML and
rather just inspect the stack.

For this purpose I expanded Catalyst::Test and threw away its remote
functionality. So without further ado, I'd like to ask for your comments
on this idea/module/name. POD follows.

Cheers,
  Sebastian

---

NAME
  Catalyst::Test::LocalContext - Test Catalyst Applications

SYNOPSIS
      use Test::More tests => 5;
      use Catalyst::Test::LocalContext ’TestApp’;

      my $response = request(’/foo’);
      isa_ok( $response, q/HTTP::Response/ )

      like( get(’/foo’), qr/bar/ );

      my $c = prepare(’/foo’);
      ok( $c->action->name, ’foo’ )
      dispatch( $c );
      like( $c->response->body, qr/bar/ );

      use HTTP::Request::Common;
      $c = dispatch( POST( ’/foo’, [ bar => ’baz’ ] ) );
      is( $c->request->method, ’POST’ );

DESCRIPTION
  This module tries to provide a test environment for those situations
  where Catayst::Test is simply not enough.  Basically, it allows you to
  test local Catalyst applications and accesses the dispatched context
  after the request handling, or create a pristine context object and 
  manipulate it at your hearts content before dispatching it yourself.

INSTALLED METHODS
  All installed methods take either an URI path, a HTTP::Request (e.g.
  one produced by HTTP::Request::Common) or a previously prepared
context
  object (with the exception of prepare() itself, for obvious reasons).

  get

  Returns the content.

      my $content = get(’foo/bar?test=1’);

  Note that this method doesn’t follow redirects, so to test for a
  correctly redirecting page you’ll need to use a combination of this
  method and the request method below:

      my $res = request(’/’); # redirects to /y
      warn $res->header(’location’);
      use URI;
      my $uri = URI->new($res->header(’location’));
      is ( $uri->path , ’/y’);
      my $content = get($uri->path);

  request

  Returns the "HTTP::Response" object for this request.

      my $res = request(’foo/bar?test=1’);

  prepare

  Returns a "Catalyst" context object (before dispatching the actual
  request). This is especially useful when you like to test internals of
  your application or your components.

      my $c = prepare(’foo/bar?test=1’);

      # do whatever you would do with $c in your actions
      ok( $c->request->model, ’GET’ );

  dispatch

  Returns a "Catalyst" context object (after executing the request) and
  the "HTTP::Response" object as an array. You can silently ignore the
  response if you are not interested in it and just inspect the context
  object.

      my $c = dispatch(’foo/bar?test=1’);
      my ( $c, $res ) = dispatch(’foo/bar?test=2’);

INTERNAL METHODS
  prepare_request

  Creates and returns a new context object for a request without
  dispatching it. Also returns the HTTP::Request::AsCGI object in list
  context.

  dispatch_request

  Creates a new request object and runs the actual request on it.
  Returns the context object (and the response in array context).