NAME

JSTAPd::Manual::Test - HOW TO WRITE JSTAPd TESTS

DESCRIPTION

JSTAPd tests are unlike Test::More tests in that the .t files themselves don't execute the actual tests. They are more like a set of setup functions. JSTAPd will invoke the appropriate functions to run the JSTAPd tests.

Normally you will setup functions to specify some JS code (the actual tests), HTML code that goes with it, and other files that go with it.

SETUP

Your JSTAPd .t files should start with the following:

  use JSTAPd::Suite;

This will do the proper preparation to run JSTAPd tests.

FUNCTIONS YOU MAY PROVIDE

You may provide any of the following functions. If they are not present, JSTAPd::Suite will Do The Right Thing and provide defaults for you.

sub client_script { return $JS }

Return the actual JavaScript code that gets executed. You should return the actual string that gets executed -- but how you create it is up to you. You can load the JavaScript from a file, generate it on the fly, whatever.

sub html_body { return $HTML }

Provide the HTML code that should be used. This value will be used to substitute $BODY in your index file.

sub server_api { }

This function will be called when non-JSTAPd Ajax calls are made to JSTAPd server. You should provide the server-side logic through this function

  sub server_api {
      my($self, $global, $req, $method, $path) = @_;

      return { ... }; # or return [ ... ] or return 'strings'
  }

The return value can be any Perl construct. If it's a reference, the return value will be JSON encoded. Otherwise it will be passed as-is.

The server_api() function takes the following parameters:

$self

$self contains the test instance. The test instance will also receive any subroutines defined in your .t file. For example,

  sub foo {
    ...
  }

  sub server_api {
    my ($self, $global, $req, $method, $path) = @_;

    $sef->foo();
  }

$global

$global is hashref that's available during the test session, and can be used as a stash.

$req

A HTTP::Engine::Request instance

$method

Contains the request method

$path

Contains the request path

include

You can specify the URL(s) of JavaScript libraries that YOU wrote via this function. You may return a single scalar, or a list of urls

The difference between include and include_ex is that (while it's currently unimplemented) JavaScript files specified via include will be checked for syntax errors and such before loading.

include_ex

The same as include, but will NOT be checked for correctness. JavaScript libraries provided by JSTAPd or other parties (such as jQuery, et al) should be specified here.