NAME

Test::Rest - Declarative test framework for RESTful web services

SYNOPSIS

This module is very experimental/alpha and will likely change. It's not super usable at the moment, but I'm open to feedback and suggestions on how to move forward, and feature requests are OK too.

use Test::Rest;

# Scan the directory './tests' for test declaration files 
# and run them against the server http://webservice.example.com/
# e.g.
# ./tests/01-authentication.xml
# ./tests/02-create-a-foobar.xml
# ./tests/03-delete-a-foobar.xml
my $tests = Test::Rest->new(dir => 'tests', base_url => 'http://webservice.example.com/');
$tests->run;

DESCRIPTION

The idea here is to write tests against REST services in a data-driven, declarative way.

Here is an example test description file:

<tests>
  <get>api/login</get>
  <submit_form>
    <with_fields>
      <name>admin</name>
      <pass>admin</pass>
    </with_fields>
  </submit_form>
  <is the="[% response.code %]">200</is> 
  <set name="random">[% c.random %]</set>
  <set name="mail">test+[% random %]@example.com</set>
  <set name="pass">[% random %]</set>
  <post url="rest/user">
    <Content>
      <user>
        <firstname>Testy</firstname>
        <lastname>McTester</lastname>
        <mail>[% mail %]</mail>
        <pass>[% pass %]</pass>
      </user>
    </Content>
  </post>
  <is the="[% response.code %]">200</is> 
  <set name="uid" xpath="id"/>
  <diag>Created a user with ID [% uid %]</diag>
</tests>

Things to note:

*

Each child of the top-level element represents a command or test, and they are executed sequentially by Test::Rest.

*

Methods like 'get', 'post', and 'submit_form' map to the equivalent methods of WWW::Mechanize or LWP::UserAgent - they result in a request being made to the server.

*

The default user agent is WWW::Mechanize. Cookies/sessions are stored between requests.

*

The web service URLs given are relative paths and are automatically prefixed by the 'base_url' parameter given to new().

*

Template::Toolkit is used to expand template variables. The template stash (variable hash) persists until the end of the test file. The 'set' command can be used to add variables to the stash.

*

The most recent HTTP::Response is stored in the stash via the key 'response'. If the response type is an XML document, the response document is automatically parsed and available to future tests/commands via XPath, and via the stash key 'document'. The whole history of responses and documents are available via the stash keys 'responses' and 'documents' respectively.

COMMANDS

get

GETs a URL

Attributes:

• url - the URL to get. Relative URLs are automatically prefixed with 'base_url'

post

POSTs to a URL

Attributes:

url

The URL

Children:

All of the children of the 'post' element are converted to a hash and fed to WWW::Mechanize::post().

The 'Content' element gets special treatment - its first child element is encoded back to XML, and that XML is sent as the content of the post.

TODO: support other content types, including URL-encoded forms.

Content

The content to post. Content-type may be supplied via the 'type' attribute. Default content type is application/xml.

set

Sets a variable in the stash

Attributes:

name

Name of the variable

xpath

If set, the value of the variable is the first result of the XPath expression given, and the text content of the 'set' element is ignored.

Children:

The text content of the 'set' element is the value of the variable (unless the xpath attribute is set).

submit_form

Submits a form (see WWW::Mechanize::submit_form())

Children:

All the child nodes of the submit_form element are converted to a hash and fed to WWW::Mechanize::submit_form()

FUNCTIONS

my $tests = Test::Rest->new(%params)

Create a new Test::Rest object

Parameters:

• dir - directory to scan for test files

• base_url - the base URL of the web service - should end in /

$tests->run

Scan directory for test description files and run them.

$tests->run_test_file($filename)

Run a single test description file.

AUTHOR

Keith Grennan, <kgrennan at cpan.org>

TODO

• This initial implementation is very XML/XPath-centric, but there's certainly room to incorporate other formats (YAML, JSON, etc)

• Figure out how to make friendly with Test::Harness and whatnot

• Allow extensions to supply custom commands, tests, formats

SEE ALSO

LWP::UserAgent, WWW::Mechanize, Template

BUGS

Please report any bugs or feature requests to bug-test-rest at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Rest. 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::Rest

You can also look for information at:

• RT: CPAN's request tracker

  http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Rest

• AnnoCPAN: Annotated CPAN documentation

  http://annocpan.org/dist/Test-Rest

• CPAN Ratings

  http://cpanratings.perl.org/d/Test-Rest

• Search CPAN

  http://search.cpan.org/dist/Test-Rest/

COPYRIGHT & LICENSE

Copyright 2010 Keith Grennan, all rights reserved.

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