Merge v4 into master

README.md

@@ -1,14 +1,11 @@
 # PhantomJS Runners for Mocha
 
-[Mocha](http://mochajs.org/) is a feature-rich JavaScript test framework running on node and the browser. Along with the [Chai](http://chaijs.com) assertion library they make an impressive combo. [PhantomJS](http://phantomjs.org) is a headless WebKit with a JavaScript/CoffeeScript API. It has fast and native support for various web standards like DOM handling, CSS selectors, JSON, Canvas, and SVG.
+[Mocha](http://mochajs.org/) is a feature-rich JavaScript test framework running on node and the browser. Along with the [Chai](http://chaijs.com) assertion library they make an impressive combo. [PhantomJS](http://phantomjs.org) is a headless WebKit with a JavaScript API.
 
-The mocha-phantomjs project provides a `mocha-phantomjs.coffee` script file and extensions to drive PhantomJS while testing your HTML pages with Mocha from the console. The preferred usage is to install `mocha-phantomjs` via node's packaged modules and use the `mocha-phantomjs` binary wrapper. Tested with Mocha 1.12.x, Chai 1.7.x, and PhantomJS 1.9.1.
-
-  * **Since version 3.0 of mocha-phantomjs, you must use PhantomJS 1.9.1 or higher.**
+Since 4.0, the phantomjs code now is in [mocha-phantomjs-core](https://github.com/nathanboktae/mocha-phantomjs-core). If you need full control over which phantomjs version to use and where to get it, or want to use it more programatically like a build system plugin, please use that package directly. This project is a node.js CLI around it.
 
 [![Build Status](https://secure.travis-ci.org/nathanboktae/mocha-phantomjs.png)](http://travis-ci.org/nathanboktae/mocha-phantomjs)
 
-
 # Key Features
 
 ### Standard Out
@@ -21,21 +18,16 @@ Proper exit status codes from PhantomJS using Mocha's failures count. So in stan
 
 ### Mixed Mode Runs
 
-You can use your existing Mocha HTML file reporters side by side with mocha-phantomjs. This gives you the option to run your tests both in a browser or with PhantomJS. Since mocha-phantomjs needs to control when the `run()` command is sent to the mocha object, we accomplish this by setting the `mochaPhantomJS` on the `window` object to `true`. Below, in the usage section, is an example of a HTML structure that can be used both by opening the file in your browser or choice or using mocha-phantomjs.
-
+You can use your existing Mocha HTML file reporters side by side with mocha-phantomjs. This gives you the option to run your tests both in a browser or with PhantomJS, with no changes needed to your existing test setup.
 
 # Installation
 
-We distribute [mocha-phantomjs as an npm](https://npmjs.org/package/mocha-phantomjs) that is easy to install. Once done, you will have a `mocha-phantomjs` binary. See the next usage section for docs or use the `-h` flag.
-
-Since 3.4, we now declare phantomjs as a peer dependency, and it will be installed adjacent to `mocha-phantomjs` automatically. You may use `-p` to provide an explicit path to phantomjs, or call phantomjs directly yourself via `phantomjs lib/mocha-phantomjs.coffee <page> <reporter> <config-as-JSON>`. The later approach is recommended for build system plugins to avoid another process fork.
-
-Due to [a bug in phantomjs 1.9.8+](https://github.com/nathanboktae/mocha-phantomjs/issues/167), mocha-phantomjs currnently caps its peer depedency to `1.9.7-15`. If you are having install errors due to peer depdendency resolution conflics, expliclity declare your dependency as `"phantomjs": "1.9.7-15"`, or expliclity install 1.9.7, like `npm install [email protected]`.
+We distribute [mocha-phantomjs as an npm package](https://npmjs.org/package/mocha-phantomjs) that is easy to install. Once done, you will have a `mocha-phantomjs` binary. See the next usage section for docs or use the `-h` flag.
 
 # Usage
 
 ```
-Usage: mocha-phantomjs [options] page
+ Usage: mocha-phantomjs [options] page
 
  Options:
 
@@ -56,6 +48,7 @@ Usage: mocha-phantomjs [options] page
    -C, --no-color               disable color escape codes
    -p, --path <path>            path to PhantomJS binary
 
+ Any other options are passed to phantomjs (see `phantomjs --help`)
 
  Examples:
 
@@ -67,7 +60,7 @@ Usage: mocha-phantomjs [options] page
 
 Now as an node package, using `mocha-phantomjs` has never been easier. The page argument can be either a local or fully qualified path or a http or file URL. `--reporter` may be a built-in reporter or a path to your own reporter (see below). See [phantomjs WebPage settings](https://github.com/ariya/phantomjs/wiki/API-Reference-WebPage#wiki-webpage-settings) for options that may be supplied to the `--setting` argument.
 
-Your HTML file's structure should look something like this. The reporter set below to `html` is only needed for viewing the HTML page in your browser. The `mocha-phantomjs.coffee` script overrides that reporter value. The conditional run at the bottom allows the mixed mode feature described above.
+Since 4.0, you need no modifications to your test harness markup file to run. Here is an example `test.html`:
 
 ```html
 <html>
@@ -81,14 +74,13 @@ Your HTML file's structure should look something like this. The reporter set bel
     <script src="mocha.js"></script>
     <script src="chai.js"></script>
     <script>
-      mocha.ui('bdd');
-      mocha.reporter('html');
-      expect = chai.expect;
+      mocha.ui('bdd')
+      expect = chai.expect
     </script>
+    <script src="src/mycode.js"></script>
     <script src="test/mycode.js"></script>
     <script>
-      if (window.mochaPhantomJS) { mochaPhantomJS.run(); }
-      else { mocha.run(); }
+      mocha.run()
     </script>
   </body>
 </html>
@@ -186,13 +178,7 @@ We also use Travis CI to run our tests too. The current build status:
 [![Build Status](https://secure.travis-ci.org/nathanboktae/mocha-phantomjs.png)](http://travis-ci.org/nathanboktae/mocha-phantomjs)
 
 
-# Alternatives
-
-* OpenPhantomScripts - https://github.com/mark-rushakoff/OpenPhantomScripts
-* Front Tests - https://github.com/Backbonist/front-tests
-
-
 # License
 
-Released under the MIT license. Copyright (c) 2012 Ken Collins.
+Released under the MIT license. Copyright (c) 2015 Ken Collins, Nathan Black, and many generous GitHub Contributors.
 

bin/mocha-phantomjs

@@ -58,11 +58,12 @@ function resolveHooks(val) {
 }
 
 program
+  .allowUnknownOption()
   .version(JSON.parse(fs.readFileSync(__dirname + '/../package.json', 'utf8')).version)
   .usage('[options] page')
   .option('-R, --reporter <name>',       'specify the reporter to use', 'spec')
   .option('-f, --file <filename>',       'specify the file to dump reporter output')
-  .option('-t, --timeout <timeout>',     'specify the test startup timeout to use', parseInt, 6000)
+  .option('-t, --timeout <timeout>',     'specify the test startup timeout to use', parseInt)
   .option('-g, --grep <pattern>',        'only run tests matching <pattern>')
   .option('-i, --invert',                'invert --grep matches')
   .option('-b, --bail',                  'exit on the first test failure')
@@ -77,6 +78,8 @@ program
   .option('--ignore-resource-errors',    'ignore resource errors');
 
 program.on('--help', function(){
+  console.log('  Any other options are passed to phantomjs (see `phantomjs --help`)');
+  console.log('');
   console.log('  Examples:');
   console.log('');
   console.log('    $ mocha-phantomjs -R dot /test/file.html');
@@ -90,7 +93,7 @@ program.parse(process.argv);
 if (!program.args.length) { program.outputHelp(); process.exit(1); };
 if (program.agent) { settings.userAgent = program.agent; }
 
-var script   = fs.realpathSync(__dirname + '/../lib/mocha-phantomjs.coffee');
+var script   = fs.realpathSync(__dirname + '/../node_modules/mocha-phantomjs-core/mocha-phantomjs-core.js');
 var reporter = program.reporter;
 var page     = function(){
   var arg = program.args[0];
@@ -103,7 +106,7 @@ var page     = function(){
 }();
 var config = JSON.stringify({
   hooks: program.hooks,
-  timeout: program.timeout,
+  timeout: program.timeout || 6000,
   cookies: cookies,
   headers: headers,
   settings: settings,
@@ -148,8 +151,12 @@ function launchFailure(e) {
   process.exit(-2);
 }
 
+var unknown = program.parseOptions(process.argv).unknown.filter(function(u) {
+  return u !== program.args[0]
+})
+
 try {
-  var phantomjs = spawn(phantomPath, [script, page, reporter, config]);
+  var phantomjs = spawn(phantomPath, unknown.concat([script, page, reporter, config]))
   phantomjs.stdout.pipe(process.stdout);
   phantomjs.stderr.pipe(process.stderr);
   phantomjs.on('exit', function(code){