Using headless tests

nightmarejs is a headless browser and allows SiteMaster to run tests against a fully rendered webpage (js+css) instead of just the raw DOM tree that PHP can parse. Phantomjs tests are written in nodejs. Please review the nightmare documentation before creating tests.

Sitemaster will run one headless request for every webpage that is scanned. Each metric can add its own tests to the headless request, thus reducing the number of times SiteMaster might have to hit a scanned webpage.

A typical headless metric would look like this

metric_foler/
 - src/
  -- Metric.php
  -- Plugin.php 
 - tests/
  -- MetricDBTest.php
 - headless.js

define headless tests

The headless.js file is where you define the javascript that will be executed by nightmare. It must define an evaluate function that is compatible with nightmare.use().

The file will look something like this: https://github.com/UNLSiteMaster/site_master/blob/master/plugins/example/headless.js

Each metric can define their own tests. These tests are wrapped in a promise block to reduce the chance that one metric might prevent another metric from executing. If an exception is thrown, the results object will contain an exception property which is then passed back to the metric in the PHP layer.

Access headless tests

The Metric::scan method for your plugin is where the logic for logging marks goes. Inside this method you can access $this->headless_results to get access to the results returned by your headless tests. The results from headless are converted to json, passed back to php, and decoded as an array to $this->headless_results.

Testing

As with everything, it is important to test your code. You can test your headless code by extending the SiteMaster\Core\DBTests\AbstractMetricDBTest class and returning your Plugin class in the test's getPlugin() method. This will change the testing environment of SiteMaster to include just your plugin during the test's execution.

Example

TODO: Link to an example, probably the example plugin in the core project. This will have to wait until it is merged.

Configuration

You can set several options via SiteMaster\Core\Config::set() to customize headless execution

• PATH_NODE - the path to the nodejs binary
• HEADLESS_WIDTH - width in pixels of the phantomjs renderer, defaults to 480 (mobile)
• HEADLESS_HEIGHT - height in pixels of the phantomjs renderer, defaults to 800
• PHANTOMJS_WAIT - time in milliseconds to wait before executing tests, defaults to 2500. Useful if you want to wait for the page to load and JS to execute before running tests. Ideally we would wait on a browser event, but nightmare doesn't allow that.
• HEADLESS_TIMEOUT - timeout of the headless process, parameter should work with the timeout linux command.
• XVFB_COMMAND - xvfb command to run (nightmarejs requires xvdb on linux servers). For example Config::set('XVFB_COMMAND', '/usr/bin/xvfb-run -a'); (always try to grad a free server (the -a option)