/ 
JSTAPd-0.03
River stage zero No dependents
/ JSTAPd::Tutorial::Intro

NAME

JSTAPd::Tutorial::Intro - Introduction To JSTAPd

WHAT IS JSTAPd?

JSTAPd is a testing framework to test Ajax/Javascript libraries. Test results are generated as TAP test results, so you can use tools like prove to integrate it in your daily testing routines.

PREPARATION

INSTALL JSTAPd

$ cpan JSTAPd

# or from github
$ git clone git://github.com/Yappo/JSTAPd.git

CREATE A SKELETON

$ ./scripts/jstapd -n foo
create foo
create foo/index
create foo/conf.pl
create foo/01_base.t

STARTUP THE DAEMON

$ ./scripts/jstapd -d foo
starting: http://127.0.0.1:1978/____jstapd/ at lib/JSTAPd/Server.pm line 98, <DATA> line 16.
HTTP::Engine::Interface::ServerSimple : You can connect to your server at http://127.0.0.1:1978/

Now you can access http://127.0.0.1:1978/____jstapd/

RUN THE TEST (VIA A WEB BROWSER)

Access the server with your web browser, and click on the make test button. You should see the test running, and eventually an output like below will appear

01_base.t .. ok

When you have multiple test files, you can also access http://127.0.0.1:1978/____jstapd/contents/01_base.t directly and run individual tests.

RUN THE TEST (VIA COMMAND LINE)

JSTAPd can be invoked via a command line tool like prove. This is controlled via the JSTAP_AUTO_OPEN_COMMAND environment variable, or the config.pl file that comes with your test.

Once configured, you can invoke the test directly like so:

$ perl foo/01_base.t

or by using prove:

$ prove -v foo/01_base.t

As a sample, here are a few ways to set up your tests to use a particular browser when JSTAPd tests are run

Safari ON Mac OS X
$ export JSTAP_AUTO_OPEN_COMMAND='open -a Safari %s'
$ prove -v foo/01_base.t

The %s in the above command specification will receive the test URL, so you should be able to use it to configure for your particular needs.

However, there's just one caveat: with Firefox, you will not be able to close the browser window automatically, as Firefox does not allow arbitrary JavaScript code to invoke window.close() to close the browser window. This is a feature.

JSTAPd TEST COMPONENTS

REQUIRED FILES

JSTAPd tests must be inside a directory that contains a file called index and a configuration file called conf.pl. These should be automatically created for you by using jstap command.

index

This is a simple template file that gets called when rendering the test HTML code. If you have run a test file

foo/bar/01.t

then the index file contained in the closest directory is used. For example, in this case foo/bar/index is tried first, and the foo/index.

These files contain are a few macros that will get expanded:

$HEAD

$HEAD gets replaced by JSTAPd's own JavaScript code, and other script tags that are automatically inserted.

$BODY

$BODY is replaced by code snippets that were defined in the .t files. If your tests require certain DOM structure, include them here.

conf.pl

conf.pl contains global options for JSTAPd tests. When tests are run via prove, the directory containing this file is taken as prove's root directory, so be sure to place it at the right place.

conf.pl is specified using a simple Perl hash. In this file, simply create a hash, and return a reference to it. JSTAPd will accept the following configuration parameters:

jstapd_prefix

Specifies the "root" mount point for the test server. The default value is ____jstapd

apiurl

Specifies which URLs should be mapped to the API urls declared in server_api() Normally you shouldn't need to change this value.

urlmap

Contains a URL to filesystem mapping.

If your JavaScript files that are supposed to be in /js/* are actually located under /var/www/htdocs/js/, specify it like so:

$config->{urlmap} = [
    +{
        qr!^/js/! => '/var/www/htdocs/js/',
    },
];

auto_open_command

Specifies the command to use when running tests. See the section "RUN THE TEST (VIA COMMAND LINE)" for more details