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 => '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>user/login</get>
    <submit_form>
      <with_fields>
        <name>myname</name>
        <pass>mypass</pass>
      </with_fields>
    </submit_form>
    <is the="{response.code}">200</is> 
    <set name="random" value="{test.random}"/>
    <set name="mail" value="test+{random}@example.com"/>
    <set name="pass" value="{random}"/>
    <post to="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" value="$(id)"/>
    <diag>Created {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, and are kept for current test file.

*

The web service URLs given are relative paths and are automatically prefixed by the 'base' 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.

*

A jQuery/XPath-like template variable syntax is available for referencing parts of the last received document. E.g. to see the href of the first anchor tag, you would use $(a[1]/@href)

COMMANDS

TODO

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.