/ 
Mojo-Phantom-0.12
River stage zero No dependents
/ Test::Mojo::Role::Phantom

NAME

Test::Mojo::Role::Phantom - Adds phantom_ok to Test::Mojo

SYNOPSIS

use Mojolicious::Lite;

use Test::More;
use Test::Mojo::WithRoles qw/Phantom/;

any '/' => 'index';

my $t = Test::Mojo::WithRoles->new;

$t->phantom_ok('/' => <<'JS');
  var text = page.evaluate(function(){
    return document.getElementById('name').innerHTML;
  });
  perl.is(text, 'Bender', 'name changed after loading');
JS

done_testing;

__DATA__

@@ index.html.ep

<!DOCTYPE html>
<html>
  <head></head>
  <body>
    <p id="name">Leela</p>
    <script>
      (function(){ document.getElementById('name').innerHTML = 'Bender' })();
    </script>
  </body>
</html>

DESCRIPTION

Test::Mojo::Role::Phantom is a Role::Tiny role which adds a phantom_ok method to Test::Mojo or a Test::Mojo instance. This method tests the javascript behavior of the app via an external PhantomJS process. You must install that program and it must be in your PATH in order to use this method.

The author recommends using Test::Mojo::WithRoles to manage the role application. The low level interaction is handled by a Mojo::Phantom instance, but for the most part that is transparent to the test method.

WARNING

The upstream phantom.js has been retired in favor of headless chrome. A Mojo::Chrome (and related Test::Mojo::Role::Chrome) is planned and is already in the works (perhaps it is released already who knows?!). While this module will continue to function, just know that it depends on a project that is defunct.

METHODS

phantom_ok

$t = $t->phantom_ok(@url_for, $js, \%opts)

The arguments are as follows

url specification

phantom_ok takes a url or arguments for "url_for" in Mojolicious::Controller, a required string of javascript and and optional hash reference of additional arguments.

javascript

The javascript string will be executed once the phantom object has loaded the page in question. At this point, it will have access to all the symbols of a typical phantom process as well as

page

The page object.

status

The page request status, should be success.

perl

A function which takes the name of a perl function and arguments for that function. The function name and the arguments are serialized as JSON and then executed on the perl side.

If the function dies (or is CORE::die), the test fails.

Since it would be prohibitively expensive to start up a new phantom process for each test in the string, the entire string is executed as a subtest. The test result will be success if the entire subtest is a success.

If there is a javascript error, the subtest will fail.

options

The method also takes a hashreference of additional options. They are as follows:

name

The name of the subtest

plan

The number of tests that are expected. While not required, this is more useful than most plans in Test::More since the transport of the commands is volatile. By specifying a plan in this way, if the process exits (status zero) early or never starts, the test will still fail rather than silently pass assuming there were no tests.

package

The package that is searched for Perl functions if the function name is not fully qualified.

bind

A hash reference of key-value pairs which then have shortcuts built in the phantom process. The pairs passed are merged into

{
  ok    => 'Test::More::ok',
  is    => 'Test::More::is',
  diag  => 'Test::More::diag',
  note  => 'Test::More::note',
  fail  => 'Test::More::fail',
}

In the phantom process you may then use the shortcut as

perl.ok(@args)

Which is handy if you are using a certain function often.

Note that if the value is falsey, the key name is use as the target.

setup

A pass-through option specifying javascript to be run after the page object is created but before the url is opened.

phantom

If you need even more control, you may pass in an instance of Mojo::Phantom and it will be used.

no_exit

Do not automatically call phantom.exit() after the provided JavaScript code. This is useful when testing asynchronous events.

note_console

Redirect console.log output to TAP as note events. This is usually helpful, but can be turned off if it becomes too verbose.

phantom_args

Specifies an array reference of command-line arguments passed directly to the PhantomJS process.

DESIGN GOALS

Not enough people test their client-side javascript. The primary goal is make testing js in you Mojolicious app that you actually DO IT. To accomplish this, I make the following goals:

  • Have the test script not depend on a running mojolicious server (i.e. start one, like Test::Mojo scripts can), whether that be from a js or perl file doesn't matter

  • Emit tap in a normal way in a manner that prove -l can collect tests

  • Not have to reimplement a large chunk of the test methods in either Test::More or Test::Mojo. Note: if some javascript library has functionality like Test::* (that emits tap and can be collected subject to the previous goals) then that would be sufficient.

This module is the result of those goals and my limited design ability. I encourage contribution, whether to this implementation or some other implementation which meets these goals!

NOTES

The phantom_ok test itself mimics a subtest. While this outer test behaves correctly, individual tests do not report the correct line and file, instead emitting from inside the IOLoop. It is hoped that future versions of Test::More will make correct reporting possible, but it is not yet.

SOURCE REPOSITORY

http://github.com/jberger/Test-Mojo-Phantom

AUTHOR

Joel Berger, <joel.a.berger@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2015 by Joel Berger

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