JSTAPd::Tutorial::Intro - Introduction To 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.
prove
$ cpan JSTAPd # or from github $ git clone git://github.com/Yappo/JSTAPd.git
$ ./scripts/jstapd -n foo create foo create foo/index create foo/conf.pl create foo/01_base.t
$ ./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/
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
make test
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.
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.
JSTAP_AUTO_OPEN_COMMAND
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
$ 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.
window.close()
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
conf.pl
jstap
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.
foo/bar/index
foo/index
These files contain are a few macros that will get expanded:
$HEAD gets replaced by JSTAPd's own JavaScript code, and other script tags that are automatically inserted.
script
$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 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:
Specifies the "root" mount point for the test server. The default value is ____jstapd
____jstapd
Specifies which URLs should be mapped to the API urls declared in server_api() Normally you shouldn't need to change this value.
server_api()
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/', }, ];
Specifies the command to use when running tests. See the section "RUN THE TEST (VIA COMMAND LINE)" for more details
To install JSTAPd, copy and paste the appropriate command in to your terminal.
cpanm
cpanm JSTAPd
CPAN shell
perl -MCPAN -e shell install JSTAPd
For more information on module installation, please visit the detailed CPAN module installation guide.